Vitest Configuration

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

Full Example

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    reporters: [
      'default',
      ['@spekra/vitest', {
        // Required
        apiKey: process.env.SPEKRA_API_KEY,
        source: 'my-unit-tests',
        
        // Optional
        apiUrl: 'https://spekra.dev/api/v1/reports',
        enabled: !!process.env.CI,
        debug: false,
        failOnError: false,
        onError: (error) => console.error('Spekra error:', error),
        onMetrics: (metrics) => console.log('Reported:', metrics.resultsReported),
      }],
    ],
  },
});

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.

source

string

required

Identifies your test suite in Spekra. Use a descriptive, stable name like 'frontend-unit-tests' or 'api-integration'.

Changing the source creates a new grouping in Spekra, so keep it stable.

apiUrl

string

optional

Default: https://spekra.dev/api/v1/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 to only report in CI.

debug

boolean

optional

Default: false

Enable verbose logging for troubleshooting.

failOnError

boolean

optional

Default: false

Fail the Vitest run if reporting fails. Useful for ensuring test results are always captured in CI.

onError

(error: SpekraError) => void

optional

Callback invoked when reporting fails (after all retries). Useful for custom error handling or alerting.

onMetrics

(metrics: SpekraMetrics) => void

optional

Callback to receive reporter metrics like requests sent, latency, and bytes transferred.

Environment Variables

The reporter respects these environment variables (Vitest-specific vars take priority):

Variable	Description
`SPEKRA_VITEST_API_KEY`	API key (Vitest-specific)
`SPEKRA_API_KEY`	API key (fallback)
`SPEKRA_VITEST_SOURCE`	Source identifier
`SPEKRA_VITEST_ENABLED`	Set to 'false' to disable reporting
`SPEKRA_VITEST_DEBUG`	Set to 'true' for verbose logging
`SPEKRA_VITEST_FAIL_ON_ERROR`	Set to 'true' to fail on reporting errors

CI-Only Reporting

['@spekra/vitest', {
  apiKey: process.env.SPEKRA_API_KEY,
  source: 'my-unit-tests',
  enabled: !!process.env.CI,
}]

With Workspaces

If you're using Vitest workspaces, configure the reporter in the root config:

// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    reporters: [
      'default',
      ['@spekra/vitest', {
        apiKey: process.env.SPEKRA_API_KEY,
        source: 'monorepo-tests',
      }],
    ],
  },
});

The workspace/project name is automatically captured for each test.

With Sharding

When using Vitest's sharding feature, the reporter automatically captures shard information:

# In CI, run shards in parallel
vitest run --shard=1/3
vitest run --shard=2/3
vitest run --shard=3/3

Spekra aggregates results from all shards into a single test run view.

Troubleshooting

Results Not Appearing

Verify enabled is true (or not set)
Check your API key is valid
Ensure source is configured
Enable debug: true to see logs
Make sure you're running vitest run, not watch mode

Watch Mode Not Reporting

This is expected behavior. The reporter only sends results when running vitest run to avoid noise from continuous development reruns.

Slow Test Completion

If tests seem to hang at the end:

Check network connectivity
Look for firewall issues blocking spekra.dev
Enable debug: true to see what's happening

Vitest Configuration

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

Full Example

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    reporters: [
      'default',
      ['@spekra/vitest', {
        // Required
        apiKey: process.env.SPEKRA_API_KEY,
        source: 'my-unit-tests',
        
        // Optional
        apiUrl: 'https://spekra.dev/api/v1/reports',
        enabled: !!process.env.CI,
        debug: false,
        failOnError: false,
        onError: (error) => console.error('Spekra error:', error),
        onMetrics: (metrics) => console.log('Reported:', metrics.resultsReported),
      }],
    ],
  },
});

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.

source

string

required

Identifies your test suite in Spekra. Use a descriptive, stable name like 'frontend-unit-tests' or 'api-integration'.

Changing the source creates a new grouping in Spekra, so keep it stable.

apiUrl

string

optional

Default: https://spekra.dev/api/v1/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 to only report in CI.

debug

boolean

optional

Default: false

Enable verbose logging for troubleshooting.

failOnError

boolean

optional

Default: false

Fail the Vitest run if reporting fails. Useful for ensuring test results are always captured in CI.

onError

(error: SpekraError) => void

optional

Callback invoked when reporting fails (after all retries). Useful for custom error handling or alerting.

onMetrics

(metrics: SpekraMetrics) => void

optional

Callback to receive reporter metrics like requests sent, latency, and bytes transferred.

Environment Variables

The reporter respects these environment variables (Vitest-specific vars take priority):

Variable	Description
`SPEKRA_VITEST_API_KEY`	API key (Vitest-specific)
`SPEKRA_API_KEY`	API key (fallback)
`SPEKRA_VITEST_SOURCE`	Source identifier
`SPEKRA_VITEST_ENABLED`	Set to 'false' to disable reporting
`SPEKRA_VITEST_DEBUG`	Set to 'true' for verbose logging
`SPEKRA_VITEST_FAIL_ON_ERROR`	Set to 'true' to fail on reporting errors

CI-Only Reporting

['@spekra/vitest', {
  apiKey: process.env.SPEKRA_API_KEY,
  source: 'my-unit-tests',
  enabled: !!process.env.CI,
}]

With Workspaces

If you're using Vitest workspaces, configure the reporter in the root config:

// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    reporters: [
      'default',
      ['@spekra/vitest', {
        apiKey: process.env.SPEKRA_API_KEY,
        source: 'monorepo-tests',
      }],
    ],
  },
});

The workspace/project name is automatically captured for each test.

With Sharding

When using Vitest's sharding feature, the reporter automatically captures shard information:

# In CI, run shards in parallel
vitest run --shard=1/3
vitest run --shard=2/3
vitest run --shard=3/3

Spekra aggregates results from all shards into a single test run view.

Troubleshooting

Results Not Appearing

Verify enabled is true (or not set)
Check your API key is valid
Ensure source is configured
Enable debug: true to see logs
Make sure you're running vitest run, not watch mode

Watch Mode Not Reporting

This is expected behavior. The reporter only sends results when running vitest run to avoid noise from continuous development reruns.

Slow Test Completion

If tests seem to hang at the end:

Check network connectivity
Look for firewall issues blocking spekra.dev
Enable debug: true to see what's happening