Troubleshooting¶

Solutions to common issues with rjest.

Common Errors¶

"Cannot use import statement outside a module"¶

Cause: TypeScript/ESM not being transformed to CommonJS.

Solution:

Stop and restart the daemon:
```
jest --daemon-stop
jest
```
Clear the transform cache:
```
rm -rf ~/.cache/rjest
jest
```
Ensure your file has a TypeScript extension (.ts, .tsx).

"Daemon is not running"¶

Cause: The daemon hasn't started or crashed.

Solution:

Start the daemon by running any test:
```
jest
```

Check for port conflicts:

# See if something else is using the socket
ls -la /tmp/rjest-*

Check daemon logs:
```
RUST_LOG=debug jest
```

"Connection refused" or Socket Errors¶

Cause: Daemon died or socket file is stale.

Solution:

Kill any stale processes:
```
pkill -f jestd
```
Remove stale socket files:
```
rm -f /tmp/rjest-*
```
Restart:
```
jest
```

Tests Pass in Jest but Fail in rjest¶

Cause: Using unsupported features.

Check for:

jest.requireActual() - Not supported
testEnvironment: 'jsdom' - Not supported
Custom reporters - Not supported
globalSetup/globalTeardown - Not supported

Solution: Check the Migration Guide for workarounds.

Mock Not Working¶

Cause: Mock not set up correctly.

Check:

// Ensure mock is created before use
const mockFn = jest.fn().mockReturnValue(42);

// Ensure you're checking the mock, not original
expect(mockFn).toHaveBeenCalled(); // ✓
expect(originalFn).toHaveBeenCalled(); // ✗ Wrong!

For module mocks:

// Mock must be called before import
jest.mock('./module');

// Then import
import { fn } from './module';

Snapshot Mismatch¶

Cause: Output changed or snapshot is stale.

Solution:

Review the diff carefully
If change is intentional:
```
jest -u
```
If change is unintentional, fix your code.

"expect(...).toSomeMatcher is not a function"¶

Cause: Matcher not implemented in rjest.

Check available matchers in Matchers Guide.

Workaround: Use available matchers:

// Instead of: expect(x).toBeWithinRange(1, 10)
expect(x).toBeGreaterThanOrEqual(1);
expect(x).toBeLessThanOrEqual(10);

Tests Timeout¶

Cause: Async operation taking too long.

Solutions:

Increase timeout:

test('slow test', async () => {
  // ...
}, 30000); // 30 seconds

Check for unresolved promises:

// Bad: Floating promise
test('async', () => {
  fetchData(); // Not awaited!
});

// Good: Await the promise
test('async', async () => {
  await fetchData();
});

Check for infinite loops in mocks.

Daemon Issues¶

Daemon Won't Start¶

Check logs:

RUST_LOG=debug jest 2>&1 | head -50

Common causes:

Port already in use
Insufficient permissions
Missing Node.js

Solutions:

# Check Node.js is available
which node
node --version

# Check for zombie processes
ps aux | grep jest
pkill -f jestd

# Try again
jest

Daemon Crashes¶

Check for errors:

RUST_LOG=trace jest

Common causes:

Out of memory
Invalid configuration
Corrupt cache

Solutions:

# Clear cache
rm -rf ~/.cache/rjest

# Reduce workers
jest --maxWorkers=1

Daemon Uses Too Much Memory¶

Solution: Stop when not testing:

jest --daemon-stop

Or reduce workers:

jest --maxWorkers=2

Configuration Issues¶

Config Not Found¶

Check file exists:

ls jest.config.*

Check format:

// jest.config.js
module.exports = {
  // Must use CommonJS exports
};

Config Changes Not Applied¶

Solution: Restart daemon:

jest --daemon-stop
jest

TypeScript Config Not Working¶

Ensure you're exporting correctly:

// jest.config.ts
import type { Config } from 'jest';

const config: Config = {
  testMatch: ['**/*.test.ts'],
};

export default config;

Debug Mode¶

Enable Verbose Logging¶

# Info level
RUST_LOG=info jest

# Debug level
RUST_LOG=debug jest

# Trace level (very verbose)
RUST_LOG=trace jest

Log Specific Components¶

# Only daemon logs
RUST_LOG=jestd=debug jest

# Only transform logs
RUST_LOG=jestd::transform=debug jest

Save Logs to File¶

RUST_LOG=debug jest 2>&1 | tee rjest.log

Getting Help¶

Check Daemon Status¶

jest --daemon-status

Version Information¶

jest --version

File an Issue¶

When filing an issue, include:

rjest version (jest --version)
Node.js version (node --version)
Operating system
Minimal reproduction
Debug logs (RUST_LOG=debug jest)

Quick Reset¶

If all else fails:

# Kill all rjest processes
pkill -f jestd
pkill -f rjest

# Clear all caches
rm -rf ~/.cache/rjest

# Clear transform cache
rm -rf /tmp/rjest-*

# Start fresh
jest