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

このページでは、継続的インテグレーション (CI) パイプラインの Synthetic テストの構成について説明します。CI のメトリクスやデータを Datadog のダッシュボードに取り込みたい場合は、継続的インテグレーションの可視性のセクションを参照してください。

概要

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

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

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

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

NPM からパッケージをインストールします。

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

Yarn からパッケージをインストールします。

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 への発信接続に使用されるプロキシ。hostport キーは必須の引数で、protocol キーの初期値は http です。サポートされる protocol キーの値は、httphttpssockssocks4socks4asocks5socks5hpac+datapac+filepac+ftppac+httppac+https です。プロキシの構成に使用されるライブラリは、proxy-agent ライブラリです。
subdomain
Datadog アプリケーションにアクセスするために設定されたカスタムサブドメインの名前。Datadog へのアクセスに使用する URL が myorg.datadoghq.com の場合、subdomain の値は myorg にする必要があります。
tunnel
安全なトンネルを使って、テストバッチを実行します。
testSearchQuery
実行する Synthetic テストを選択するためのクエリを渡します。CLI でテストを実行する場合は、-s フラグを使用します。

例:

Global Configuration File

{
    "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 とテストの構成を上書きするためのオブジェクトの配列が含まれています。

例:

Basic Test Configuration File

{
    "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: グローバルオーバーライドに優先するテストのオーバーライド。

Advanced Test Configuration File

{
    "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 の隣にあるドロップダウンメニューを使用して、各テストの実行ルールをテストレベルで定義します。

テストに関連する実行ルールは、コンフィギュレーションファイルの中で最も制約の多いものです。オプションは、最も制限の厳しいものから順に、 skippednon_blockingblocking となります。例えば、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

: カスタムグローバルコンフィギュレーションファイルを使用してテストを起動している場合は、コマンドに --config <PATH_TO_GLOBAL_CONFIG_FILE を追加します。

package.json に下記を追加します。

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

次に、以下を実行します。

npm run datadog-ci-synthetics

: カスタムグローバルコンフィギュレーションファイルを使用してテストを起動している場合は、datadog-ci-synthetics スクリプトに紐付けられたコマンドに --config <PATH_TO_GLOBAL_CONFIG_FILE を追加します。

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

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

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

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

テスト結果の表示

CI の場合

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

成功したテスト結果

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

失敗したテスト結果

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

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

CI Results Explorer

その他の参考資料