Overview

GitHub Release

Trigger Synthetic tests from your GitHub workflows with the Datadog CI Synthetics command.

Setup

To get started:

  1. Add your Datadog API and Application Keys as secrets to your GitHub repository.
  2. In your GitHub workflow, use DataDog/synthetics-ci-github-action.

Your workflow can be simple or complex.

Simple workflows

Example workflow using public IDs

name: Run Synthetic tests using the test public IDs
jobs:
  e2e_testing:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Run Datadog Synthetic tests
        uses: DataDog/synthetics-ci-github-action@v2.2.0
        with:
          api-key: ${{secrets.DD_API_KEY}}
          app-key: ${{secrets.DD_APP_KEY}}
          public-ids: |
            abc-d3f-ghi
            jkl-mn0-pqr            

Example workflow using an existing synthetics.json file

name: Run Synthetic tests using an existing synthetics.json file
jobs:
  e2e_testing:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Run Datadog Synthetic tests
        uses: DataDog/synthetics-ci-github-action@v2.2.0
        with:
          api-key: ${{secrets.DD_API_KEY}}
          app-key: ${{secrets.DD_APP_KEY}}

For an example test file, see this test.synthetics.json file.

Note: By default, this workflow runs all the tests listed in {,!(node_modules)/**/}*.synthetics.json files (every file ending with .synthetics.json except for those in the node_modules folder). You can also trigger a list of Synthetic tests by specifying a public_id or using a search query.

Complex workflows

Example workflow using the test_search_query

name: Run Synthetic tests by test tag
jobs:
  e2e_testing:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Run Datadog Synthetic tests
        uses: DataDog/synthetics-ci-github-action@v2.2.0
        with:
          api-key: ${{secrets.DD_API_KEY}}
          app-key: ${{secrets.DD_APP_KEY}}
          test-search-query: 'tag:e2e-tests'

Example workflow using a test search query and variable overrides

name: Run Synthetic tests using search query
jobs:
  e2e_testing:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Run Datadog Synthetic tests
        uses: DataDog/synthetics-ci-github-action@v2.2.0
        with:
          api-key: ${{secrets.DD_API_KEY}}
          app-key: ${{secrets.DD_APP_KEY}}
          test-search-query: 'tag:staging'
          variables: 'START_URL=https://staging.website.com,PASSWORD=stagingpassword'

Example workflow using a global configuration file with config_path

By default, the path to the global configuration file is datadog-ci.json. You can override this path with the config_path input.

name: Run Synthetic tests with custom config
jobs:
  e2e_testing:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Run Datadog Synthetic tests
        uses: DataDog/synthetics-ci-github-action@v2.2.0
        with:
          api-key: ${{secrets.DD_API_KEY}}
          app-key: ${{secrets.DD_APP_KEY}}
          config-path: './global.config.json'

For an example of a global configuration file, see this global.config.json file.

Inputs

NameDescription
api-key(Required) Your Datadog API key. This key is created by your Datadog organization and should be stored as a secret.
app-key(Required) Your Datadog application key. This key is created by your Datadog organization and should be stored as a secret.
batch-timeoutThe duration (in milliseconds) after which the batch fails as timed out.
Default: 1800000 (30 minutes)
config-pathThe global JSON configuration to be used when launching tests. See the example configuration file for more details.
Default: datadog-ci.json
datadog-siteThe Datadog site to send data to.
Default: datadoghq.com
fail-on-critical-errorsFail the CI job if no tests were triggered, or results could not be fetched from Datadog.
Default: false
fail-on-missing-testsFail the CI job if at least one specified test with a public ID (using public_ids or listed in a test file) is missing in a run (for example, if it has been deleted programmatically or on the Datadog site).
Default: false
fail-on-timeoutFail the CI job if at least one test exceeds the default test timeout.
Default: true
filesGlob pattern to detect Synthetic test configuration files.
Default: {,!(node_modules)/**/}*.synthetics.json
junit-reportThe filename for a JUnit report if you want to generate one.
Default: none
public-idsPublic IDs of Synthetic tests to run, separated by new lines or commas. If no value is provided, tests are discovered in *.synthetics.json files.
Default: none
subdomainThe name of the custom subdomain set to access your Datadog application. If the URL used to access Datadog is myorg.datadoghq.com, the subdomain value needs to be set to myorg.
Default: app
test-search-queryTrigger tests corresponding to a search query.
Default: none
tunnelUse the Continuous Testing Tunnel to execute your test batch.
Default: false
variablesKey-value pairs for injecting variables into tests, separated by newlines or commas. For example: START_URL=https://example.org,MY_VARIABLE=My title.
Default: none

Outputs

NameDescription
batch-urlThe URL of the batch.
critical-errors-countThe number of critical errors.
failed-countThe number of failed results.
failed-non-blocking-countThe number of failed non-blocking results.
passed-countThe number of passed results.
previously-passed-countThe number of previously passed results.
tests-not-found-countThe number of not found tests.
tests-skipped-countThe number of skipped tests.
timed-out-countThe number of timed out results.
raw-resultsThe list of results, as a raw JSON string.

Contributing

See CONTRIBUTING.md

Further reading

Additional helpful documentation, links, and articles:

PREVIEWING: yuqing.bian/fix-sources-searchterm