CI/CD Integration

Spekra is designed to run in CI/CD pipelines. This guide covers best practices for integrating Spekra with your continuous integration system.

Supported CI Providers

Spekra automatically detects and captures metadata from these CI providers:

• GitHub Actions
• GitLab CI
• CircleCI
• Jenkins
• Azure Pipelines
• Bitbucket Pipelines
• Travis CI

Even if your provider isn't listed, the reporter will still work - you may just need to set some environment variables manually.

Quick Links

General Setup

Regardless of your CI provider, the setup follows these steps:

1. Store Your API Key Securely

Add your Spekra API key as a secret/environment variable in your CI system. Never hardcode it in your configuration files.

2. Pass the Key to Tests

Make the API key available to your test command:

env:
  SPEKRA_API_KEY: ${{ secrets.SPEKRA_API_KEY }}

3. Run Tests Normally

No special commands needed - just run your tests as usual:

run: npx playwright test

CI-Specific Metadata

The reporter automatically captures CI-specific metadata:

This metadata appears in the Spekra dashboard and helps you trace failures back to specific CI runs.

Best Practices

Run on All Branches

Report results from all branches, not just main:

Include Retry Configuration

For better flaky test detection, configure retries:

// playwright.config.ts
export default defineConfig({
  retries: process.env.CI ? 2 : 0,
});

Cache Dependencies

Speed up your CI by caching node_modules:

- uses: actions/cache@v4
  with:
    path: ~/.pnpm-store
    key: ${{ runner.os }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}

Use Sharding for Large Suites

For large test suites, use Playwright's sharding:

strategy:
  matrix:
    shard: [1, 2, 3, 4]

steps:
  - run: npx playwright test --shard=${{ matrix.shard }}/4

Spekra aggregates results from all shards automatically.

Conditional Reporting

You may want to disable reporting in certain situations:

Skip for Dependabot

if: github.actor != 'dependabot[bot]'

Skip for Draft PRs

if: github.event.pull_request.draft != true

Report Only on Main

// playwright.config.ts
['@spekra/playwright', {
  apiKey: process.env.SPEKRA_API_KEY,
  enabled: process.env.GITHUB_REF === 'refs/heads/main',
}]

Troubleshooting

Results Not Appearing

• Check that secrets are properly configured
• Verify the secret name matches your code
• Look for errors in CI logs

Missing CI Metadata

If job URLs or workflow names aren't appearing:

• Ensure required environment variables are set
• Check CI provider is supported
• Enable debug logging to see what's detected

Next Steps

• GitHub Actions guide
• GitLab CI guide
• Troubleshooting