Skip to main content

​
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 POST \
  https://dispatch.empirical.run/v1/trigger \
  -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 POST \
  https://dispatch.empirical.run/v1/trigger \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $EMPIRICALRUN_KEY" \
  -d '{
    "environment": "production",
    "origin": {
      "owner": "$GITHUB_ORG",
      "name": "$GITHUB_REPO"
    },
    "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" }
    ]
  }'