Troubleshooting

Having issues with Spekra? This guide covers common problems and their solutions.

Quick Links

Enable Debug Mode

The first step in troubleshooting is enabling debug mode:

Playwright

['@spekra/playwright', {
  apiKey: process.env.SPEKRA_API_KEY,
  debug: true,
}]

Jest

['@spekra/jest', {
  apiKey: process.env.SPEKRA_API_KEY,
  debug: true,
}]

Environment Variable

Alternatively, set the environment variable:

SPEKRA_DEBUG=true npx playwright test

Debug mode outputs:

• Configuration values (with secrets redacted)
• Number of test results captured
• API request details
• Response status and timing

Common Issues

Reporter Not Installed

Symptom: Tests run but no output from Spekra reporter.

Solution: Verify the package is installed:

npm list @spekra/playwright
# or
npm list @spekra/jest

If not listed, install it:

npm install @spekra/playwright

Tests Pass But No Data Appears

Symptom: Tests complete successfully, no errors, but dashboard is empty.

Possible causes:

1. Reporter not configured in test config
2. enabled: false in configuration
3. API key not set or invalid
4. Network issues silently failing

Solution: Enable debug mode and check the output.

"Cannot find module" Error

Symptom: Error: Cannot find module '@spekra/playwright'

Solution:

1. Ensure the package is installed
2. Check you're running from the correct directory
3. Try deleting node_modules and reinstalling

Slow Test Completion

Symptom: Tests finish but the process hangs for several seconds.

Cause: The reporter is waiting for the API request to complete.

Solutions:

1. Reduce timeout: timeout: 5000
2. Check network connectivity
3. Ensure no firewall is blocking requests

Getting Help

If these solutions don't help:

1. Check GitHub Issues - Search for similar problems
2. Open a New Issue - Include debug output and configuration
3. Contact Support - For urgent production issues