Playwright Configuration

Complete reference for all configuration options available in the @spekra/playwright reporter.

Full Example

import { defineConfig } from '@playwright/test';

export default defineConfig({
  reporter: [
    ['html'],
    ['@spekra/playwright', {
      // Required
      apiKey: process.env.SPEKRA_API_KEY,
      
      // Optional
      apiUrl: 'https://spekra.dev/api/reports',
      enabled: process.env.CI === 'true',
      debug: false,
      timeout: 30000,
      batchSize: 100,
      redact: ['my-secret', /password/i],
    }],
  ],
});

Options Reference

apiKey

string

required

Your Spekra API key. Get one from Settings → API Keys.

We recommend using an environment variable rather than hardcoding the key.

apiUrl

string

optional

Default: https://spekra.dev/api/reports

The Spekra API endpoint. Only change this if you're using a self-hosted instance.

enabled

boolean

optional

Default: true

Whether to send results to Spekra. Set to false to disable reporting.

Common pattern: enabled: process.env.CI === 'true' to only report in CI.

debug

boolean

optional

Default: false

Enable verbose logging. Useful for troubleshooting configuration issues.

Logs are written to stderr and include:

Configuration values (redacted)
Number of results captured
API response status

timeout

number

optional

Default: 30000

Timeout in milliseconds for the API request. If exceeded, the request is abandoned silently.

batchSize

number

optional

Default: 100

Maximum number of results to send in a single request. Large test suites are automatically split into batches.

redact

boolean | (string | RegExp)[] | RedactionOptions

optional

Default: true

PII/secrets redaction. Enabled by default with built-in patterns for emails, tokens, API keys, etc.

true (default): Enable with built-in patterns
false: Disable redaction (not recommended)
['pattern', /regex/]: Add custom patterns to built-in
{ enabled, patterns, replaceBuiltIn }: Full control

Environment Variables

The reporter also respects these environment variables:

Variable	Description
`SPEKRA_API_KEY`	API key (can be used instead of config)
`SPEKRA_ENABLED`	Set to false to disable reporting
`SPEKRA_DEBUG`	Set to true for verbose logging

Config options take precedence over environment variables.

CI-Only Reporting

A common pattern is to only report results when running in CI:

['@spekra/playwright', {
  apiKey: process.env.SPEKRA_API_KEY,
  enabled: !!process.env.CI,
}]

Multiple Environments

If you use different Spekra organizations for different environments:

const isProduction = process.env.ENVIRONMENT === 'production';

['@spekra/playwright', {
  apiKey: isProduction 
    ? process.env.SPEKRA_PROD_API_KEY 
    : process.env.SPEKRA_DEV_API_KEY,
}]

Redacting Sensitive Data

Redaction is enabled by default with built-in patterns for common PII/secrets (emails, tokens, API keys, etc.). To add custom patterns:

['@spekra/playwright', {
  apiKey: process.env.SPEKRA_API_KEY,
  redact: [
    'my-internal-secret',
    /custom-token-\w+/gi,
  ],
}]

For full control over redaction:

['@spekra/playwright', {
  apiKey: process.env.SPEKRA_API_KEY,
  redact: {
    enabled: true,
    patterns: ['custom-secret', /internal-\w+/],
    replaceBuiltIn: false,  // Set true to only use your patterns
  },
}]

Matched patterns are replaced with [REDACTED] before sending to Spekra. See Security → Data Handling for the full list of built-in patterns.

Troubleshooting

Results Not Appearing

Check that enabled is true
Verify your API key is correct
Enable debug: true to see what's being sent
Check network connectivity to spekra.dev

Slow Test Completion

The reporter sends results after all tests complete. If this takes too long:

Reduce timeout to fail faster on network issues
Check your network connectivity
Ensure you're not behind a firewall blocking the API

Partial Results

If only some results appear:

Check for errors in the debug output
Verify batchSize isn't too small
Look for timeout errors in logs

Playwright Configuration

Complete reference for all configuration options available in the @spekra/playwright reporter.

Full Example

import { defineConfig } from '@playwright/test';

export default defineConfig({
  reporter: [
    ['html'],
    ['@spekra/playwright', {
      // Required
      apiKey: process.env.SPEKRA_API_KEY,
      
      // Optional
      apiUrl: 'https://spekra.dev/api/reports',
      enabled: process.env.CI === 'true',
      debug: false,
      timeout: 30000,
      batchSize: 100,
      redact: ['my-secret', /password/i],
    }],
  ],
});

Options Reference

apiKey

string

required

Your Spekra API key. Get one from Settings → API Keys.

We recommend using an environment variable rather than hardcoding the key.

apiUrl

string

optional

Default: https://spekra.dev/api/reports

The Spekra API endpoint. Only change this if you're using a self-hosted instance.

enabled

boolean

optional

Default: true

Whether to send results to Spekra. Set to false to disable reporting.

Common pattern: enabled: process.env.CI === 'true' to only report in CI.

debug

boolean

optional

Default: false

Enable verbose logging. Useful for troubleshooting configuration issues.

Logs are written to stderr and include:

Configuration values (redacted)
Number of results captured
API response status

timeout

number

optional

Default: 30000

Timeout in milliseconds for the API request. If exceeded, the request is abandoned silently.

batchSize

number

optional

Default: 100

Maximum number of results to send in a single request. Large test suites are automatically split into batches.

redact

boolean | (string | RegExp)[] | RedactionOptions

optional

Default: true

PII/secrets redaction. Enabled by default with built-in patterns for emails, tokens, API keys, etc.

true (default): Enable with built-in patterns
false: Disable redaction (not recommended)
['pattern', /regex/]: Add custom patterns to built-in
{ enabled, patterns, replaceBuiltIn }: Full control

Environment Variables

The reporter also respects these environment variables:

Variable	Description
`SPEKRA_API_KEY`	API key (can be used instead of config)
`SPEKRA_ENABLED`	Set to false to disable reporting
`SPEKRA_DEBUG`	Set to true for verbose logging

Config options take precedence over environment variables.

CI-Only Reporting

A common pattern is to only report results when running in CI:

['@spekra/playwright', {
  apiKey: process.env.SPEKRA_API_KEY,
  enabled: !!process.env.CI,
}]

Multiple Environments

If you use different Spekra organizations for different environments:

const isProduction = process.env.ENVIRONMENT === 'production';

['@spekra/playwright', {
  apiKey: isProduction 
    ? process.env.SPEKRA_PROD_API_KEY 
    : process.env.SPEKRA_DEV_API_KEY,
}]

Redacting Sensitive Data

Redaction is enabled by default with built-in patterns for common PII/secrets (emails, tokens, API keys, etc.). To add custom patterns:

['@spekra/playwright', {
  apiKey: process.env.SPEKRA_API_KEY,
  redact: [
    'my-internal-secret',
    /custom-token-\w+/gi,
  ],
}]

For full control over redaction:

['@spekra/playwright', {
  apiKey: process.env.SPEKRA_API_KEY,
  redact: {
    enabled: true,
    patterns: ['custom-secret', /internal-\w+/],
    replaceBuiltIn: false,  // Set true to only use your patterns
  },
}]

Matched patterns are replaced with [REDACTED] before sending to Spekra. See Security → Data Handling for the full list of built-in patterns.

Troubleshooting

Results Not Appearing

Check that enabled is true
Verify your API key is correct
Enable debug: true to see what's being sent
Check network connectivity to spekra.dev

Slow Test Completion

The reporter sends results after all tests complete. If this takes too long:

Reduce timeout to fail faster on network issues
Check your network connectivity
Ensure you're not behind a firewall blocking the API

Partial Results

If only some results appear:

Check for errors in the debug output
Verify batchSize isn't too small
Look for timeout errors in logs