Execute commands with Datadog from within your Continuous Integration/Continuous Deployment scripts to perform end-to-end tests of your application before applying your changes or deploying. datadog-ci allows you to run Continuous Testing tests and wait for the results.
The package is under @datadog/datadog-ci and can be installed through NPM or Yarn:
# NPM
npm install --save-dev @datadog/datadog-ci
# Yarn
yarn add --dev @datadog/datadog-ciIf you need datadog-ci as a CLI tool instead of a package, you can run it with npx or install it globally:
# npx
npx @datadog/datadog-ci [command]
# NPM install globally
npm install -g @datadog/datadog-ci
# Yarn v1 add globally
yarn global add @datadog/datadog-ciFor more ways to install the CLI, see this section.
Usage: datadog-ci <command> <subcommand> [options]The following values are available for each <command>. See the corresponding documentation for more details:
dsyms: iOS dSYM Filesflutter-symbols: Flutter Symbolsgit-metadata: Git metadatajunit: JUnit XMLlambda: Lambdametric: Metricreact-native: React Native sourcemapssourcemaps: Browser sourcemapsstepfunctions: Step Functionssynthetics: Continuous Testingtag: Tagtrace: Trace
Pull requests for bug fixes are welcome, but before submitting new features or changes to current functionality, open an issue and discuss your ideas or propose the changes you wish to make. After a resolution is reached, a PR can be submitted for review.
When developing the tool, it is possible to run commands using yarn launch. It relies on ts-node, so does not require building the project for every new change.
yarn launch synthetics run-tests --config dev/global.config.json- clipanion: CLI library to handle the different commands.
- eslint: Linting (.eslintrc.js).
- jest: Tests are written in Jest.
- volta: NodeJS and yarn versioning.
Commands are stored in the src/commands folder.
The skeleton of a command is composed of a README, an index.ts and a folder for the tests.
src/
└── commands/
└── fakeCommand/
├── __tests__/
│ └── index.test.ts
├── README.md
└── index.tsDocumentation of the command must be placed in the README.md file, the current README must be updated to link to the new command README.
The index.ts file must export classes extending the Command class of clipanion. The commands of all src/commands/*/index.ts files will then be imported and made available in the datadog-ci tool.
A sample index.ts file for a new command would be:
import {Command} from 'clipanion'
export class HelloWorldCommand extends Command {
public async execute() {
this.context.stdout.write('Hello world!')
}
}
module.exports = [HelloWorldCommand]Lastly, test files must be created in the __tests__/ folder. jest is used to run the tests and a CI has been set using GitHub Actions to ensure all tests are passing when merging a Pull Request.
The tests can then be launched through the yarn test command, it will find all files with a filename ending in .test.ts in the repo and execute them.
The CI performs tests to avoid regressions by building the project, running unit tests and running one end-to-end test.
The end-to-end test installs the package in a new project, configures it by using files in the .github/workflows/e2e folder, and runs a synthetics run-tests command in a Datadog org (such as Synthetics E2E Testing Org) to verify the command is able to perform a test.
The Synthetic tests that are run include a browser test (with a test ID of neg-qw9-eut) and an API test (with a test ID of v5u-56k-hgk). Both tests load a page which outputs the headers of the request and verifies the X-Fake-Header header is present. This header is configured as an override in the .github/workflows/e2e/test.synthetics.json file. The API and application keys used by the command are stored in GitHub Secrets named datadog_api_key and datadog_app_key.
The goal of this test is to verify the command is able to run tests and wait for their results as expected as well as handling configuration overrides.
# Compile and watch
yarn watch
# Run the tests
yarn test
# Build code
yarn build
# Make bin executable
yarn prepackInstructions
To release a new version of datadog-ci:
- Create a new branch for the version upgrade.
- Update the
package.jsonversion toX.X.X, commit the changevX.X.Xand tag it withgit tag vX.X.X.- You may refer to Semantic Versioning to determine what level to increment.
- Push the branch along with the tag with
git push --tags origin name-of-the-branch, create a PR, and get at least one approval.- Create a draft GitHub Release (prefilled link) and save it as a draft.
- Please categorize the changes by product or "Documentation" / "Dependencies" / "Chores". You can find commands grouped by product in the
.github/CODEOWNERSfile. - Copy the categorized release notes, and paste them in the description of your PR. This ensures the feature PRs have a link to your release PR.
- See this example PR.
- Once you've received at least one approval, merge the PR with the "Create a merge commit" strategy.
- You may notice that some GitLab jobs are pending, this is expected (see step 7). You can merge the PR when only those jobs are left.
- The "Create a merge commit" strategy is required for step 7, and for the GitHub Release to point to an existing commit once the PR is merged.
- Go back to your draft GitHub Release, and publish it.
- Once the release is published, this GitHub Workflow publishes the NPM package and adds binaries to the release's assets. Wait for it to succeed.
- When the NPM package is published, go to the GitLab pipelines, find the pipeline for your tag, and start the
buildstage to run the Docker image build jobs.- Make sure all the jobs and downstream jobs succeed.
Thanks for creating a release! 🎉
Instructions
To create a pre-release or releasing in a different channel:
- Create a new branch for the channel you want to release to (
alpha,beta, and more). - Create a PR for your feature branch with the channel branch as a base.
- Pick a version following this format:
<version>-<channel>. For example,0.10.9-alpha,1-beta, and more. - Update the
versionfield inpackage.json. - Once you've received at least one approval, merge the Pull Request with the "Create a merge commit" strategy.
- Create a GitHub Release:
- Target the channel branch.
- Pick a tag based on your version
<version>-<channel>. - Check the
This is a pre-releasecheckbox.
- Publish the release and an action publishes it on npm.
If installing NodeJS in the CI is an issue, standalone binaries are provided with releases. linux-x64, darwin-x64 (macOS), and win-x64 (Windows) are supported. These standalone binaries are in beta and their stability is not guaranteed.
To install:
curl -L --fail "https://github.com/DataDog/datadog-ci/releases/latest/download/datadog-ci_linux-x64" --output "/usr/local/bin/datadog-ci" && chmod +x /usr/local/bin/datadog-cicurl -L --fail "https://github.com/DataDog/datadog-ci/releases/latest/download/datadog-ci_darwin-x64" --output "/usr/local/bin/datadog-ci" && chmod +x /usr/local/bin/datadog-ciInvoke-WebRequest -Uri "https://github.com/DataDog/datadog-ci/releases/latest/download/datadog-ci_win-x64.exe" -OutFile "datadog-ci.exe"Then, you can run datadog-ci commands normally:
datadog-ci versionTo run datadog-ci from a container, you can use the datadog/ci image available in Dockerhub as well as the public Amazon ECR and Google GC registries.
docker pull datadog/ci
This example demonstrates how to run a command using the container and passing in the API and APP keys:
export DD_API_KEY=$(cat /secret/dd_api_key)
export DD_APP_KEY=$(cat /secret/dd_app_key)
docker run --rm -it -v $(pwd):/w -e DD_API_KEY -e DD_APP_KEY datadog/ci synthetics run-tests -p pub-lic-id1
You can build an image using the provided Dockerfile:
cd container
docker build --tag datadog-ci .Optionally, you can use the VERSION build argument to build an image for a specific version:
docker build --build-arg "VERSION=v1.14" --t datadog-ci .