Synthetics CI CircleCI Orb

Overview

CircleCI Build Status CircleCI Orb Version Apache 2.0 License CircleCI Community

Run Synthetic tests in your CircleCI pipelines using the Datadog CircleCI orb.

The CircleCI command orb installs datadog-ci and uses the datadog-ci synthetics run-tests command to execute Datadog Synthetic tests.

Setup

To get started:

  1. Add your Datadog API and application keys as environment variables to your CircleCI project. See inputs for naming conventions. For more information, see API and Application Keys.
  2. Ensure the image running the orb is a Linux x64 base image with cURL installed.

Your workflow can be simple or complex.

Simple workflows

Example workflow using public IDs

version: 2.1

orbs:
  synthetics-ci: datadog/synthetics-ci-orb@1.0.1

jobs:
  e2e-tests:
    docker:
      - image: cimg/base:stable
    steps:
      - synthetics-ci/run-tests:
          public_ids: 'abc-d3f-ghi, jkl-mn0-pqr'

workflows:
  run-tests:
    jobs:
      - e2e-tests

Example workflow using a global configuration override

version: 2.1

orbs:
  synthetics-ci: datadog/synthetics-ci-orb@1.0.1

jobs:
  e2e-tests:
    docker:
      - image: cimg/base:stable
    steps:
      - synthetics-ci/run-tests:
          files: e2e-tests/*.synthetics.json

workflows:
  run-tests:
    jobs:
      - e2e-tests

Complex workflows

Example workflow using the test_search_query

version: 2.1

orbs:
  synthetics-ci: datadog/synthetics-ci-orb@1.0.1

jobs:
  e2e-tests:
    docker:
      - image: cimg/base:stable
    steps:
      - synthetics-ci/run-tests:
          test_search_query: 'tag:e2e-tests'

workflows:
  run-tests:
    jobs:
      - e2e-tests

Example workflow using the Synthetic Testing Tunnel

version: 2.1

orbs:
  synthetics-ci: datadog/synthetics-ci-orb@1.0.1

jobs:
  e2e-tests:
    docker:
      - image: your-image
    steps:
      - checkout
      - run:
          name: Running server in background
          command: npm start
          background: true
      - synthetics-ci/run-tests:
          config_path: tests/tunnel-config.json
          files: tests/*.synthetics.json
          test_search_query: 'tag:e2e-tests'
          tunnel: true

workflows:
  test-server:
    jobs:
      - build-image
      - integration-tests:
          requires:
            - build-image

For additional options such as customizing the pollingTimeout for your CircleCI pipelines, see CI/CD Integrations Configuration.

Inputs

NameTypeDefaultDescription
api_keyenv var nameDATADOG_API_KEYThe name of the environment variable containing the API key.
api_keyenv var nameDATADOG_APP_KEYThe name of the environment variable containing the app key.
config_pathstringdatadog-ci.jsonThe global JSON configuration used when launching tests.
fail_on_critical_errorsbooleanfalseFail if tests were not triggered or results could not be fetched.
fail_on_timeoutbooleantrueForce the CI to fail (or pass) if one of the results exceeds its test timeout.
filesstring{,!(node_modules)/**/}*.synthetics.jsonGlob pattern to detect Synthetic tests config files.
locationsstringvalues in test config filesString of locations separated by semicolons to override the locations where your tests run.
public_idsstringvalues in test config filesString of public IDs separated by commas for Synthetic tests you want to trigger.
sitestringdatadoghq.comThe Datadog site to send data to. If the DD_SITE environment variable is set, it takes preference.
subdomainstringappThe name of the custom subdomain set to access your Datadog application.
test_search_querystringnoneTrigger tests corresponding to a search query.
tunnelbooleanfalseUse the testing tunnel to trigger tests.
variablesstringnoneKey-value pairs for injecting variables into tests. Must be formatted using KEY=VALUE.
versionstringv1.7.0The version of datadog-ci to use.

Further Reading

Additional helpful documentation, links, and articles: