Overview

Trigger Datadog Synthetic tests from your GitHub workflows.

For more information on the available configuration, see the datadog-ci synthetics run-tests documentation.

Setup

To get started:

Add your Datadog API and Application Keys as secrets to your GitHub repository.
- For more information, see API and Application Keys.
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@v3.5.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@v3.5.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@v3.5.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@v3.5.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@v3.5.0
        with:
          api-key: ${{secrets.DD_API_KEY}}
          app-key: ${{secrets.DD_APP_KEY}}
          config-path: './global.config.json'

Inputs

For more information on the available configuration, see the datadog-ci synthetics run-tests documentation.

Name	Description
`api-key`	(Required) Your Datadog API key. This key is created in your Datadog organization and should be stored as a secret.
`app-key`	(Required) Your Datadog application key. This key is created in your Datadog organization and should be stored as a secret.
`batch-timeout`	Specifies the timeout duration in milliseconds for the CI batch. When a batch times out, the CI job fails and no new test runs are triggered, but ongoing test runs complete normally. _{Default: 1800000 (30 minutes)}
`config-path`	The path to the global configuration file that configures datadog-ci. _{Default: datadog-ci.json}
`datadog-site`	Your Datadog site. The possible values are listed in this table. _{Default: datadoghq.com}
`fail-on-critical-errors`	Fail the CI job if a critical error that is typically transient occurs, such as rate limits, authentication failures, or Datadog infrastructure issues. _{Default: false}
`fail-on-missing-tests`	Fail the CI job if the list of tests to run is empty or if some explicitly listed tests are missing. _{Default: false}
`fail-on-timeout`	Fail the CI job if the CI batch fails as timed out. _{Default: true}
`files`	Glob patterns to detect Synthetic test configuration files, separated by new lines. _{Default: {,!(node_modules)/*/}.synthetics.json}
`junit-report`	The filename for a JUnit report if you want to generate one. _{Default: none}
`locations`	Override the list of locations to run the test from, separated by new lines or commas. The possible values are listed in this API response. _{Default: none}
`public-ids`	Public IDs of Synthetic tests to run, separated by new lines or commas. If no value is provided, tests are discovered in Synthetic test configuration files. _{Default: none}
`selective-rerun`	Whether to only rerun failed tests. If a test has already passed for a given commit, it is not rerun in subsequent CI batches. By default, your organization's default setting is used. Set it to `false` to force full runs when your configuration enables it by default. _{Default: none}
`subdomain`	The custom subdomain to access your Datadog organization. If your URL is `myorg.datadoghq.com`, the custom subdomain is `myorg`. _{Default: app}
`test-search-query`	Use a search query to select which Synthetic tests to run. Use the Synthetic Tests list page's search bar to craft your query, then copy and paste it. _{Default: none}
`tunnel`	Use the Continuous Testing tunnel to launch tests against internal environments. _{Default: false}
`variables`	Override existing or inject new local and global variables in Synthetic tests as key-value pairs, separated by new lines or commas. For example: `START_URL=https://example.org,MY_VARIABLE=My title`. _{Default: none}

Outputs

Name	Description
`batch-url`	The URL of the CI batch.
`critical-errors-count`	The number of critical errors that occurred during the CI batch.
`failed-count`	The number of results that failed during the CI batch.
`failed-non-blocking-count`	The number of results that failed during the CI batch without blocking the CI.
`passed-count`	The number of results that passed during the CI batch.
`previously-passed-count`	The number of results that already passed in previous CI batches on the same commit.
`tests-not-found-count`	The number of tests that could not be found when starting the CI batch.
`tests-skipped-count`	The number of tests that were skipped when starting the CI batch.
`timed-out-count`	The number of results that failed due to the CI batch timing out.
`raw-results`	The `synthetics.Result[]` array, as a JSON-encoded string.

Contributing

See CONTRIBUTING.md

Further reading

Additional helpful documentation, links, and articles:

License

DataDog/synthetics-ci-github-action

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 63

Uh oh!

Contributors 21

Uh oh!

Languages