From CI/CD pipelines

Authentication

All of the methods below use API key to authenticate. Generate a new API key from the dashboard.

GitHub Actions

Use our dispatch-action if you are using GitHub Actions for CI/CD.

- name: Deploy step
  id: deploy-step
  run: ...

- name: Dispatch for tests
  uses: empirical-run/dispatch-action@main
  with:
    auth-key: ${{ secrets.EMPIRICALRUN_KEY }}
    environment: production
    environment-variables: |
      BUILD_URL: ${{ steps.deploy-step.outputs.url }}

Use the environment-variables input to set environment variables for the test run, one per line in NAME: value format. These override the environment’s configured variables. The URL of the build under test is passed to tests as the BUILD_URL environment variable.

The build-url input is deprecated. It is sent to tests as the BUILD_URL environment variable, so set BUILD_URL via environment-variables instead.

Vercel deployments

For Vercel deployments, trigger tests on the deployment_status event. You can copy this workflow into .github/workflows/trigger-e2e.yaml:

name: Trigger e2e tests

on:
  workflow_dispatch:
  deployment_status:

jobs:
  trigger-e2e-tests-production:
    if: github.event_name == 'workflow_dispatch' ||
        (github.event_name == 'deployment_status' &&
          github.event.deployment_status.state == 'success' &&
          github.event.deployment_status.environment == 'Production')
    runs-on: ubuntu-latest
    steps:
      - name: Dispatch for tests
        uses: empirical-run/dispatch-action@main
        with:
          auth-key: ${{ secrets.EMPIRICALRUN_KEY }}
          environment: production
          environment-variables: |
            BUILD_URL: ${{ github.event.deployment_status.target_url }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

The GITHUB_TOKEN environment variable lets the action pull branch info for the deployment, which is attached to the test run report.

Other providers

For other CI/CD providers, you can trigger a test run with an API call.

Minimal snippet

curl -X PUT \
  https://api.empirical.run/api/test-runs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $EMPIRICALRUN_KEY" \
  -d '{ "environment": "production" }'

Metadata for reporting

You can add more metadata which will associated to the test run reports.

Repo where the trigger was sent from
Details of the commit or branch
Other metadata (key-value pairs)

curl -X PUT \
  https://api.empirical.run/api/test-runs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $EMPIRICALRUN_KEY" \
  -d '{
    "environment": "production",
    "build": {
      "url": "$BUILD_URL",
      "commit": "$COMMIT",
      "branch": "$BRANCH",
      "commit_url": "$COMMIT_URL"
    },
    "metadata": {
      "pairs": "of",
      "key": "value"
    },
    "environment_variables_overrides": [
      { "name": "MY_VAR", "value": "my_value" }
    ]
  }'

Getting Started

Platform

Features

Integrations

Trigger a test run

From CI/CD pipelines

Authentication

GitHub Actions

Vercel deployments

Other providers

Minimal snippet

Metadata for reporting

​Authentication

​GitHub Actions

​Vercel deployments

​Other providers

​Minimal snippet

​Metadata for reporting

Authentication

GitHub Actions

Vercel deployments

Other providers

Minimal snippet

Metadata for reporting