CI/CD インテグレーションコンフィギュレーション

概要

NPM パッケージの @datadog-ci を使用すると、CI/CD パイプライン内で直接 Synthetic テストを実行することができます。Synthetics のテストがリグレッションを検出した場合、自動的にビルドを停止し、デプロイをブロックし、デプロイをロールバックすることが可能です。

テストがどの URL から始まるかを構成するには、テストオブジェクトに startUrl を指定します。テストのオリジナルの開始 URL の任意の部分と、以下の環境変数を使って、独自の開始 URL を構築します。

パッケージのインストール

パッケージは NPM レジストリの @datadog/datadog-ci で公開されています。

npm install --save-dev @datadog/datadog-ci

yarn add --dev @datadog/datadog-ci

クライアントのセットアップ

クライアントをセットアップするには、Datadog API キーとアプリケーションキーを構成する必要があります。これらのキーは次の 3 つの方法で定義できます。

1. 環境変数として定義

   export DATADOG_API_KEY="<API_KEY>"
   export DATADOG_APP_KEY="<APPLICATION_KEY>"
   

2. テストの実行中に CLI に渡す

   datadog-ci synthetics run-tests --apiKey "<API_KEY>" --appKey "<APPLICATION_KEY>"
   

3. グローバルコンフィギュレーションファイルで定義

   グローバル JSON コンフィギュレーションファイルでは、追加の詳細オプションを指定できます。テストを起動するときにフラグ --config を使用して、このファイルへのパスを指定します。グローバルコンフィギュレーションファイルの名前が datadog-ci.json に設定されている場合、その名前がデフォルトになります。

グローバルコンフィギュレーションファイルでは、次のオプションを構成できます。

apiKey

Datadog API にクエリーを送信する際に使用される API キー。

appKey

Datadog API にクエリーを送信する際に使用されるアプリケーションキー。

datadogSite

リクエストの送信先となる Datadog インスタンス。デフォルトは datadoghq.com。Datadog サイトは です。

files

Synthetic テスト用コンフィギュレーションファイルを検出するグロブパターン。

global

すべてのテストに適用される Synthetic テストのオーバーライド (各フィールドの説明については下記を参照してください)。

proxy

Datadog への発信接続に使用されるプロキシ。host と port キーは必須の引数で、protocol キーの初期値は http です。サポートされる protocol キーの値は、http、https、socks、socks4、socks4a、socks5、socks5h、pac+data、pac+file、pac+ftp、pac+http、pac+https です。プロキシの構成に使用されるライブラリは、proxy-agent ライブラリです。

subdomain

Datadog アプリケーションにアクセスするために設定されたカスタムサブドメインの名前。Datadog へのアクセスに使用する URL が myorg.datadoghq.com の場合、subdomain の値は myorg にする必要があります。

tunnel

安全なトンネルを使って、テストバッチを実行します。

testSearchQuery

実行する Synthetic テストを選択するためのクエリを渡します。CLI でテストを実行する場合は、-s フラグを使用します。

例:

{
    "apiKey": "<DATADOG_API_KEY>",
    "appKey": "<DATADOG_APPLICATION_KEY>",
    "datadogSite": "datadoghq.com",
    "files": "{,!(node_modules)/**/}*.synthetics.json",
    "global": {
        "allowInsecureCertificates": true,
        "basicAuth": { "username": "test", "password": "test" },
        "body": "{\"fakeContent\":true}",
        "bodyType": "application/json",
        "cookies": "name1=value1;name2=value2;",
        "deviceIds": ["laptop_large"],
        "followRedirects": true,
        "headers": { "<NEW_HEADER>": "<NEW_VALUE>" },
            "locations": ["aws:us-west-1"],
        "retry": { "count": 2, "interval": 300 },
        "executionRule": "blocking",
        "startUrl": "{{URL}}?static_hash={{STATIC_HASH}}",
        "variables": { "titleVariable": "new value" },
        "pollingTimeout": 180000
    },
    "proxy": {
      "auth": {
        "username": "login",
        "password": "pwd"
      },
      "host": "127.0.0.1",
      "port": 3128,
      "protocol": "http"
    },
    "subdomain": "subdomainname",
    "tunnel": true
}

テストの構成

デフォルトでは、クライアントは **/*.synthetics.json ファイルに指定されたすべてのテストを自動的に検出し、実行します。このパスはグローバルコンフィギュレーションファイルで構成することができます。

これらのファイルには tests というキーがあり、実行するテストの ID とテストの構成を上書きするためのオブジェクトの配列が含まれています。

例:

{
    "tests": [
        {
            "id": "<TEST_PUBLIC_ID>"
        },
        {
            "id": "<TEST_PUBLIC_ID>"
        }
    ]
}

追加のコンフィギュレーション

テストに使用されるデフォルトのコンフィギュレーションはオリジナルテストのコンフィギュレーションです。これは UI または API からテスト用コンフィギュレーションを取得することで確認できます。

しかし、CI デプロイメントの文脈では、以下のオーバーライドでテストパラメーターの一部または全部を上書きすることを決定することができます。すべてのテストに対してオーバーライドを定義するには、グローバルコンフィギュレーションファイルレベルで同じパラメーターを設定します。

allowInsecureCertificates

タイプ: ブール値
HTTP テストの認証チェックを無効化します。

basicAuth

タイプ: オブジェクト
HTTP またはブラウザテストで基本認証を行う際に提供する認証情報。

• username: 文字列。基本認証で使用するユーザー名。
• password: 文字列。基本認証で使用するパスワード。

body

タイプ: 文字列
HTTP テストで送信するデータ。

bodyType

タイプ: 文字列
HTTP テストで送信するデータのタイプ。

cookies

タイプ: 文字列
HTTP またはブラウザテストのクッキーヘッダーとして提供された文字列を使用。

deviceIds

タイプ: 配列
ブラウザテストを実行するデバイスのリスト。

followRedirects

タイプ: ブール値
HTTP テストでリダイレクトに従うかどうかを示す。

headers

タイプ: オブジェクト
HTTP またはブラウザテストで置換するヘッダー。このオブジェクトには、置換するヘッダーの名前 (キー) と、ヘッダーの新しい値 (値) が含まれている必要がある。

locations

タイプ: 配列
テストの実行元となる場所のリスト。

retry

タイプ: オブジェクト
テストの再試行ポリシー。

• count: 整数。テストが失敗した場合に再試行する回数。
• interval: 整数。試行する間隔 (ミリ秒)。

executionRule

タイプ: 文字列
テストが失敗した場合の CLI の挙動を定義するテストの実行規則。

• blocking: テストが失敗した場合、CLI はエラーを返す。
• non_blocking: テストが失敗した場合、CLI は警告のプリントのみを実施する。
• skipped: テストを一切実行しない。

startUrl

タイプ: 文字列
HTTP またはブラウザテストに提供する新しい開始 URL。

variables

タイプ: オブジェクト
テストで置換する変数。このオブジェクトには、置換する変数の名前 (キー) と、変数の新しい値 (値) が含まれている必要がある。

pollingTimeout

タイプ: 整数
datadog-ci がテスト結果のポーリングを停止するまでのミリ秒単位の期間。デフォルトは 120,000 ミリ秒です。CI レベルでは、この期間の後に完了したテスト結果は失敗したと見なされます。

Note: グローバルオーバーライドに優先するテストのオーバーライド。

{
    "tests": [
        {
            "id": "<TEST_PUBLIC_ID>",
            "config": {
                "allowInsecureCertificates": true,
                "basicAuth": { "username": "test", "password": "test" },
                "body": "{\"fakeContent\":true}",
                "bodyType": "application/json",
                "cookies": "name1=value1;name2=value2;",
                "deviceIds": ["laptop_large"],
                "followRedirects": true,
                "headers": { "<NEW_HEADER>": "<NEW_VALUE>" },
            "locations": ["aws:us-west-1"],
                "retry": { "count": 2, "interval": 300 },
                "executionRule": "skipped",
                "startUrl": "{{URL}}?static_hash={{STATIC_HASH}}",
                "variables": { "titleVariable": "new value" },
                "pollingTimeout": 180000
            }
        }
    ]
}

実行規則

CI Execution の隣にあるドロップダウンメニューを使用して、各テストの実行ルールをテストレベルで定義します。

テストに関連する実行ルールは、コンフィギュレーションファイルの中で最も制約の多いものです。オプションは、最も制限の厳しいものから順に、 skipped、non_blocking、blocking となります。例えば、UI 上では skipped に構成されているが、コンフィギュレーションファイル上では blocking になっている場合、テストの実行時には skipped になります。

開始 URL

URL

テストのオリジナルの開始 URL
例: https://www.example.org:81/path/to/something?abc=123#target

DOMAIN

テストのドメイン名
例: example.org

HASH

テストのハッシュ
例: #target

HOST

テストのホスト
例: www.example.org:81

HOSTNAME

テストのホスト名
例: www.example.org

ORIGIN

テストの起点
例: https://www.example.org:81

PARAMS

テストのクエリパラメーター
例: ?abc=123

PATHNAME

テストの URl パス
例: /path/to/something

PORT

テストのホストのポート
例: 81

PROTOCOL

テストのプロトコル
例: https:

SUBDOMAIN

テストのサブドメイン
例: www

Synthetic テストを使用して、CI/CD デプロイメントを本番環境またはステージング環境で制御するかどうかにかかわらず、テストの開始 URL にローカル環境変数を設定することで、本番環境ではなく、生成されたステージング URL に対して Synthetic テストを実行することが可能です。

既存の Synthetics テストを本番環境ではなくステージングエンドポイントでトリガーするには、 $SUBDOMAIN 環境変数を staging-example に、 $PORT 環境変数をステージングに使用するポートに設定します。Synthetic テストは、本番環境で実行するのではなく、生成されたステージング URL に対して実行されます。

例えば、https://app.datadoghq.com/synthetics/details/abc-123-zyx?live=1h#test-results を以下のように記述できます。

• {{PROTOCOL}}//{{SUBDOMAIN}}.{{DOMAIN}}:{{PORT}}{{PATHNAME}}{{PARAMS}}{{HASH}}
• {{PROTOCOL}}//{{HOST}}{{PATHNAME}}{{PARAMS}}{{HASH}}
• {{URL}}

注: 上記の予約済み変数のいずれかに対応する名前の環境変数がある場合、環境変数は無視され、テスト startUrl からパースされた対応するコンポーネントに置き換えられます。

テストを実行する

CLI にすべての **/*.synthetics.json Synthetic テスト (またはグローバルコンフィギュレーションファイルで指定したパスに紐付いたすべてのテスト) を自動検知させるか、-p,--public-id フラグを使用して実行するテストを指定するか、定義できます。

CLI を実行してテストを実行する

yarn datadog-ci synthetics run-tests

{
  "scripts": {
    "datadog-ci-synthetics": "datadog-ci synthetics run-tests"
  }
}

npm run datadog-ci-synthetics

テストトンネルを使用する

また、@datadog/datadog-ci NPM パッケージには安全なトンネリングが付属しており、内部アプリケーションの Synthetic テストを起動することができます。

テストトンネルは、インフラストラクチャーと Datadog の間にエンドツーエンドで暗号化された HTTP プロキシを作成し、CLI を通して送られた全てのテストリクエストが、自動的に datadog-ci クライアントを通してルーティングされることを可能にします。

詳しくは、テストトンネルをご覧ください。

テスト結果の表示

CI の場合

テストの実行中に、テストの実行結果を CI 内で直接確認することができます。

実行ログを確認し、失敗したアサーションの原因を検索することで、テストが失敗した原因を特定できます。

Datadog アプリケーションの場合

CI Results Explorer およびテストの詳細ページにリストされている CI テスト結果も確認できます。

その他の参考資料

お役に立つドキュメント、リンクや記事:

Synthetics と CI/CD について学ぶドキュメント CI Results Explorer について学ぶドキュメント テストトンネルについて学ぶドキュメント Datadog の GitHub Action を使用して、ワークフローに Synthetic テストを追加しますブログ