> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# datadog/synthetics-ci-orb

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


## Commands

### run-tests

This command runs Datadog Synthetics tests. If all tests succeed, it passes, and fails otherwise.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `api_key` | env_var_name | DATADOG_API_KEY | Name of the environment variable containing your Datadog API key. |
| `app_key` | env_var_name | DATADOG_APP_KEY | Name of the environment variable containing your Datadog application key. |
| `background` | boolean | false | Whether or not this step should run in the background. |
| `batch_timeout` | integer | 1800000 | Specifies the timeout duration in milliseconds for the CI batch. |
| `config_path` | string |  | The path to the global configuration file that configures datadog-ci. |
| `datadog_site` | string | datadoghq.com | Your Datadog site. |
| `fail_on_critical_errors` | boolean | false | Fail the CI job if a critical error that is typically transient occurs, such as rate limits, authentication failures, or Datadog infrastructure issues. |
| `fail_on_missing_tests` | boolean | false | Fail the CI job if the list of tests to run is empty or if some explicitly listed tests are missing. |
| `fail_on_timeout` | boolean | true | Fail the CI job if the CI batch fails as timed out. |
| `files` | string |  | Glob patterns to detect Synthetic test configuration files, separated by new lines. |
| `junit_report` | string |  | The filename for a JUnit report if you want to generate one. |
| `locations` | string |  | Override the list of locations to run the test from, separated by new lines or commas. |
| `no_output_timeout` | string | 35m | Elapsed time the command can run without output. |
| `public_ids` | string |  | 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. |
| `selective_rerun` | enum |  | Whether to only rerun failed tests for a given commit. |
| `subdomain` | string | app | The custom subdomain to access your Datadog organization. If your URL is `myorg.datadoghq.com`, the custom subdomain is `myorg`. |
| `test_search_query` | string |  | Use a search query to select which Synthetic tests to run. |
| `tunnel` | boolean | false | Use the Continuous Testing tunnel to launch tests against internal environments. |
| `variables` | string |  | 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`. |

## Examples

### advanced-example

An advanced example pipeline that starts a local server and triggers Synthetics tests using the `datadog-ci` tunnel.


```yaml
version: '2.1'
orbs:
  synthetics-ci: datadog/synthetics-ci-orb@5.2.0
jobs:
  integration-tests:
    docker:
      - image: your-image
    steps:
      - checkout
      - run:
          background: true
          command: npm start
          name: Running server in background
      - synthetics-ci/run-tests:
          api_key: DATADOG_API_KEY
          app_key: DATADOG_APP_KEY
          config_path: integration-tests/tunnel-config.json
          files: integration-tests/*.synthetics.json
          test_search_query: tag:e2e-tests
          tunnel: true
workflows:
  test-server:
    jobs:
      - build-image
      - integration-tests:
          requires:
            - build-image
```

### simple-example

An example pipeline that triggers Synthetics tests.


```yaml
version: '2.1'
orbs:
  synthetics-ci-orb: datadog/synthetics-ci-orb@5.2.0
workflows:
  test:
    jobs:
      - integration-tests:
          docker:
            - image: cimg/base:stable
          steps:
            - synthetics-ci-orb/run-tests:
                api_key: DATADOG_API_KEY
                app_key: DATADOG_APP_KEY
                files: integration-tests/*.synthetics.json
```