Continuous Testing and CI GitHub Actions
Overview
Trigger Synthetic tests from your GitHub workflows with the Datadog CI Synthetics command.
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@v3
- name: Run Datadog Synthetic tests
uses: DataDog/synthetics-ci-github-action@v0.12.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@v3
- name: Run Datadog Synthetic tests
uses: DataDog/synthetics-ci-github-action@v0.12.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@v3
- name: Run Datadog Synthetic tests
uses: DataDog/synthetics-ci-github-action@v0.12.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@v3
- name: Run Datadog Synthetic tests
uses: DataDog/synthetics-ci-github-action@v0.12.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 override with config_path
This GitHub Action overrides the path to the global datadog-ci.config.json
file.
name: Run Synthetic tests with custom config
jobs:
e2e_testing:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Run Datadog Synthetic tests
uses: DataDog/synthetics-ci-github-action@v0.12.0
with:
api_key: ${{secrets.DD_API_KEY}}
app_key: ${{secrets.DD_APP_KEY}}
config_path: './synthetics-config.json'
For an example test file, see this global.config.json
file.
Name | Type | Requirement | Description |
---|
api_key | string | required | Your Datadog API key. This key is created by your Datadog organization and should be stored as a secret. Default: none. |
app_key | string | required | Your Datadog Application key. This key is created by your Datadog organization and should be stored as a secret. Default: none. |
public_ids | string | optional | Comma-separated list of public IDs for Synthetic tests you want to trigger. If no value is provided, the action looks for files named with synthetics.json . Default: none. |
test_search_query | string | optional | Trigger tests corresponding to a search query. Default: none. |
subdomain | string | optional | The 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 . |
files | string | optional | Glob pattern to detect Synthetic test configuration files. Default: {,!(node_modules)/**/}*.synthetics.json . |
datadog_site | string | optional | The Datadog site to send data to. Default: datadoghq.com . |
config_path | string | optional | The global JSON configuration to be used when launching tests. See the example configuration file for more details. Default: datadog-ci.json . |
variables | string | optional | Comma-separated list of global variables to use for Synthetic tests. For example: START_URL=https://example.org,MY_VARIABLE=My title . Default: [] . |
junit_report | string | optional | The filename for a JUnit report if you want to generate one. Default: none. |
tunnel | boolean | optional | Use the Continuous Testing Tunnel to execute your test batch. Default: false . |
polling_timeout | number | optional | The duration (in milliseconds) after which the action stops polling for test results. At the CI level, test results completed after this duration are considered failed. Default: 30 minutes. |
Development
yarn test
# Build project
yarn build
# Compile project and its dependencies for release
yarn package
Release Process
To release a new version of synthetics-ci-github-action
:
Create a new branch for the version upgrade.
Update the package version using yarn version [--patch|--minor|--major]
depending on the nature of your changes. See Semantic Versioning to determine what you need to increment. Once the yarn version
command is done, a new commit vX.Y.Z
along with a new tag should be added to the Git tree.
Update the README.md
example versions, and build and package the project with yarn build && yarn package
.
Make sure to commit these changes within the same commit that holds the vX.Y.Z
tag. You can use git commit --amend
or git rebase -i HEAD~2
to merge the changes into the same commit.
Push the branch along with the release tag (git push --tags
) to the upstream (GitHub).
Create a pull request with the changes introduced in the description. This pull request requires at least one approval.
Merge the pull request.
Create a GitHub Release from the Tags page with a description of your changes.
⚠️ Ensure the release version follows the expected format vX.Y.Z
.
Once the release is created, the new version of the Github Action is available as a workflow.
Further reading
Additional helpful documentation, links, and articles: