GitHub Actions

This guide walks you through setting up Spekra in your GitHub Actions workflow.

Prerequisites

• A GitHub repository with Playwright or Jest tests
• A Spekra account and API key

Setup Steps

1. Add Your API Key as a Secret

1. Go to your repository on GitHub
2. Navigate to Settings → Secrets and variables → Actions
3. Click New repository secret
4. Name: SPEKRA_API_KEY
5. Value: Your Spekra API key
6. Click Add secret

2. Update Your Workflow

Add the Spekra API key to your test job:

name: Tests

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Install Playwright browsers
        run: npx playwright install --with-deps
      
      - name: Run tests
        run: npx playwright test
        env:
          SPEKRA_API_KEY: ${{ secrets.SPEKRA_API_KEY }}

That's it! Your test results will now be reported to Spekra.

Full Example with Best Practices

Here's a complete workflow with recommended practices:

name: Tests

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    # Run nightly at 2am UTC
    - cron: '0 2 * * *'

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    
    steps:
      - uses: actions/checkout@v4
      
      - uses: pnpm/action-setup@v2
        with:
          version: 8
      
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'pnpm'
      
      - name: Install dependencies
        run: pnpm install --frozen-lockfile
      
      - name: Install Playwright browsers
        run: pnpm exec playwright install --with-deps chromium
      
      - name: Run tests
        run: pnpm exec playwright test
        env:
          SPEKRA_API_KEY: ${{ secrets.SPEKRA_API_KEY }}
      
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 7

Sharded Tests

For large test suites, use sharding to run tests in parallel:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        shard: [1, 2, 3, 4]
    
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      
      - run: npm ci
      
      - run: npx playwright install --with-deps
      
      - name: Run tests (shard ${{ matrix.shard }}/4)
        run: npx playwright test --shard=${{ matrix.shard }}/4
        env:
          SPEKRA_API_KEY: ${{ secrets.SPEKRA_API_KEY }}

Matrix Builds

If you test across multiple browsers or configurations:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        browser: [chromium, firefox, webkit]
    
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - run: npm ci
      
      - run: npx playwright install --with-deps ${{ matrix.browser }}
      
      - name: Run ${{ matrix.browser }} tests
        run: npx playwright test --project=${{ matrix.browser }}
        env:
          SPEKRA_API_KEY: ${{ secrets.SPEKRA_API_KEY }}

Skip Dependabot PRs

To avoid reporting from automated Dependabot PRs:

jobs:
  test:
    if: github.actor != 'dependabot[bot]'
    runs-on: ubuntu-latest
    # ...

Using Environments

For different API keys per environment:

jobs:
  test:
    runs-on: ubuntu-latest
    environment: testing
    
    steps:
      - run: npx playwright test
        env:
          SPEKRA_API_KEY: ${{ secrets.SPEKRA_API_KEY }}

Captured Metadata

The reporter automatically captures from GitHub Actions:

Troubleshooting

Secret Not Available

• Ensure the secret is created at the repository level (not organization)
• Check the secret name matches exactly: SPEKRA_API_KEY
• For fork PRs, secrets aren't available (this is a security feature)

Results Not Appearing

• Check the Actions logs for errors
• Verify the reporter is configured correctly
• Enable debug mode: SPEKRA_DEBUG: 'true'

Next Steps

• GitLab CI setup
• Troubleshooting
• API Reference