Ruby テスト

ドキュメント > Datadog の Test Optimization > Test Visibility の構成 > Ruby テスト

互換性

サポート対象言語:

言語	バージョン
Ruby	2.7 以上

サポート対象テストフレームワーク:

テストフレームワーク	バージョン
RSpec	3.0.0 以上
Minitest	5.0.0 以上
Cucumber	3.0 以上

サポート対象テストランナー:

テストランナー	バージョン
Knapsack Pro	7.2.0 以上
parallel_tests	4.0.0 以上
ci-queue	0.53.0 以上

報告方法の構成

Datadog にテスト結果を報告するには、以下のように datadog-ci gem を構成する必要があります。

We support auto-instrumentation for the following CI providers:

CI Provider	Auto-Instrumentation method
GitHub Actions	Datadog Test Visibility Github Action
Jenkins	UI-based configuration with Datadog Jenkins plugin
GitLab	Datadog Test Visibility GitLab Script
CircleCI	Datadog Test Visibility CircleCI Orb

Auto-instrumentation runs on the CI executor and does not automatically apply to tests in a separate container. Before using it for containerized tests, see Tests in Containers.

If the auto-instrumentation step configures the process that runs your tests, you can skip the rest of the setup steps below.

If you are using a cloud CI provider without access to the underlying worker nodes, such as GitHub Actions or CircleCI, configure the library to use the Agentless mode. For this, set the following environment variables:

Set these variables before starting the test process. For parallel test runners, set them on the parent process so every worker inherits them.

DD_CIVISIBILITY_AGENTLESS_ENABLED=true selects Agentless mode. DD_API_KEY provides authentication but does not enable Agentless mode.

DD_CIVISIBILITY_AGENTLESS_ENABLED=true (Required for Agentless mode): Enables Agentless mode to send test results directly to Datadog.
Default: false
DD_API_KEY (Required for Agentless mode): The Datadog API key used to authenticate test result uploads.
Default: (empty)

If you use a Datadog site other than US1, set the following variable:

DD_SITE (Optional for Agentless mode): The Datadog site to upload results to.
Default: datadoghq.com

If you are running tests on an on-premises CI provider, such as Jenkins or self-managed GitLab CI, install the Datadog Agent on each worker node by following the Agent installation instructions. This is the recommended option as it allows you to automatically link test results to logs and underlying host metrics.

If you are using a Kubernetes executor, Datadog recommends using the Datadog Operator. The operator includes Datadog Admission Controller which can automatically inject the tracer library into the build pods. Note: If you use the Datadog Operator, there is no need to download and inject the tracer library since the Admission Controller can do this for you, so you can skip the corresponding step below. However, you still need to make sure that your pods set the environment variables or command-line parameters necessary to enable Test Visibility.

If you are not using Kubernetes or can’t use the Datadog Admission Controller and the CI provider is using a container-based executor, set the DD_TRACE_AGENT_URL environment variable (which defaults to http://localhost:8126) in the build container running the tracer to an endpoint that is accessible from within that container. Note: Using localhost inside the build references the container itself and not the underlying worker node or any container where the Agent might be running in.

DD_TRACE_AGENT_URL includes the protocol and port (for example, http://localhost:8126) and takes precedence over DD_AGENT_HOST and DD_TRACE_AGENT_PORT, and is the recommended configuration parameter to configure the Datadog Agent’s URL for CI Visibility.

If you still have issues connecting to the Datadog Agent, use the Agentless Mode. Note: When using this method, tests are not correlated with logs and infrastructure metrics.

手動インスツルメンテーション

このセクションは、CI プロバイダーが自動インスツルメンテーションをサポートしていない場合にのみ必要です。上記の『報告方法の構成』セクションで「自動インスツルメンテーションサポートがある CI プロバイダー」を選択した場合は、このセクションをスキップして『構成設定』に進んでください。

CI プロバイダーが自動インスツルメンテーションをサポートしていない場合 (たとえば、Cloud CI provider (Agentless) または On-Premises CI Provider (Datadog Agent) を選択した場合)、以下の手順に従ってライブラリをインストールし、テストを手動でインスツルメンテーションしてください。

Gemfile に Ruby Test Optimization gem を追加します。

Gemfile

gem "datadog-ci", "~> 1.0", group: :test

報告方法を構成します。
テストを実行するコマンドで RUBYOPT 環境変数を設定します。
```
RUBYOPT="-rbundler/setup -rdatadog/ci/auto_instrument" bundle exec rake test
```
注: RUBYOPT 環境変数を設定したくない場合は、テストコマンドの先頭に bundle exec ddcirb exec を追加してください。
```
bundle exec ddcirb exec rake test
```

構成設定

Test Optimization ライブラリを構成するには、テストプロセスを開始する前に以下の環境変数を設定します。並列テストランナーの場合、すべてのワーカーが継承するように親プロセスで設定してください。

DD_CIVISIBILITY_ENABLED=true(必須): Test Optimization を有効にします。
デフォルト: false
DD_ENV (オプション): テストが実行されている環境の名前。
デフォルト: (empty)
例: local、ci
DD_SERVICE (オプション): テスト対象のサービスまたはライブラリの名前。
デフォルト: リポジトリ名
例: my-ruby-app

DD_CIVISIBILITY_AGENTLESS_ENABLED=true (Agentless モードの場合、必須) Agentless モードを有効にして、テスト結果を Datadog に直接送信します。
デフォルト: false

DD_API_KEY (Agentless モードの場合、必須): テスト結果のアップロードを認証するために使用される Datadog API キー。この変数で Agentless モードが有効になることはありません。
デフォルト: (empty)
DD_SITE (Agentless モードの場合、オプション): テスト結果のアップロード先の Datadog サイト。US1 以外のサイトを使用する場合は、この構成を設定します。
デフォルト: datadoghq.com
DD_TRACE_AGENT_URL (Datadog Agent を使用する場合のみ): トレース収集用の Datadog Agent URL。http://hostname:port の形式にします。
デフォルト: http://127.0.0.1:8126
DD_TEST_SESSION_NAME (オプション): unit-tests、integration-tests、smoke-tests などのテストグループを識別します。
デフォルト: CI ジョブ名とテストコマンド、または CI ジョブ名が利用できない場合はテストコマンド。
例: unit-tests、integration-tests、smoke-tests

他のすべての Datadog トレーサー構成オプションも使用できます。

追加の Test Optimization 機能には、それぞれのページに記載されている独自の構成オプションがあります。

テストにカスタムタグを追加する

現在アクティブなテストを使用して、テストにカスタムタグを追加することができます。

require "datadog/ci"

# inside your test
Datadog::CI.active_test&.set_tag("test_owner", "my_team")
# test continues normally
# ...

これらのタグに対してフィルターや group by フィールドを作成するには、まずファセットを作成する必要があります。タグの追加の詳細については、Ruby カスタムインスツルメンテーションドキュメントのタグの追加セクションを参照してください。

テストへのカスタム測定値の追加

タグと同様に、現在アクティブなテストを使用して、テストにカスタムメジャーを追加できます。

require "datadog/ci"

# inside your test
Datadog::CI.active_test&.set_metric("memory_allocations", 16)
# test continues normally
# ...

カスタムメジャーの詳細については、カスタムメジャーの追加ガイドを参照してください。

追加のインスツルメンテーションの使用

データベース操作やその他の外部呼び出しに費やされた時間を含む、テストに関する詳細なトレース情報を取得すると便利です。次のフレームグラフを参照してください。

test_helper/spec_helper に以下の行を追加することで、自動 APM インスツルメンテーションを有効にできます。

require "datadog/auto_instrument" if ENV["DD_ENV"] == "ci"

注: CI モードでは、これらのトレースは Test Optimization に送信され、Datadog APM には表示されません。

利用可能なインスツルメンテーション方法の全リストについては、トレースドキュメントを参照してください。

Git のメタデータを収集する

Datadog uses Git information for visualizing your test results and grouping them by repository, branch, and commit. Git metadata is automatically collected by the test instrumentation from CI provider environment variables and the local .git folder in the project path, if available.

If you are running tests in non-supported CI providers or with no .git folder, you can set the Git information manually using environment variables. These environment variables take precedence over any auto-detected information. Set the following environment variables to provide Git information:

DD_GIT_REPOSITORY_URL: URL of the repository where the code is stored. Both HTTP and SSH URLs are supported.
Example: git@github.com:MyCompany/MyApp.git, https://github.com/MyCompany/MyApp.git
DD_GIT_BRANCH: Git branch being tested. Leave empty if providing tag information instead.
Example: develop
DD_GIT_TAG: Git tag being tested (if applicable). Leave empty if providing branch information instead.
Example: 1.0.1
DD_GIT_COMMIT_SHA: Full commit hash.
Example: a18ebf361cc831f5535e58ec4fae04ffd98d8152
DD_GIT_COMMIT_MESSAGE: Commit message.
Example: Set release number
DD_GIT_COMMIT_AUTHOR_NAME: Commit author name.
Example: John Smith
DD_GIT_COMMIT_AUTHOR_EMAIL: Commit author email.
Example: john@example.com
DD_GIT_COMMIT_AUTHOR_DATE: Commit author date in ISO 8601 format.
Example: 2021-03-12T16:00:28Z
DD_GIT_COMMIT_COMMITTER_NAME: Commit committer name.
Example: Jane Smith
DD_GIT_COMMIT_COMMITTER_EMAIL: Commit committer email.
Example: jane@example.com
DD_GIT_COMMIT_COMMITTER_DATE: Commit committer date in ISO 8601 format.
Example: 2021-03-12T16:00:28Z

サポート対象外のテストフレームワークに対するライブラリのパブリック API の使用

RSpec、Minitest、または Cucumber を使用する場合、Test Optimization がそれらを自動的にインスツルメンテーションしてテスト結果を Datadog に送信するため、手動テスト API は使用しないでください。手動テスト API は、すでにサポートされているテストフレームワークと互換性がありません。

サポート対象外のテストフレームワークを使用する場合や、別のテストメカニズムを持っている場合のみ、手動テスト API を使用してください。完全なパブリック API ドキュメントは YARD サイトにあります。

ドメインモデル

この API は、テストセッション、テストモジュール、テストスイート、テストの 4 つの概念に基づいています。

テストセッション

テストセッションはテストコマンドの実行を表します。

テストセッションを開始するには、Datadog::CI.start_test_session を呼び出し、Datadog サービスとタグ (使用しているテストフレームワークなど) を渡します。

すべてのテストが終了したら、Datadog::CI::TestSession#finish を呼び出します。これによりセッションが閉じられ、セッションのトレースがバックエンドに送信されます。

テストモジュール

テストモジュールは、セッション内のより小さな作業単位を表します。サポート対象テストフレームワークの場合、テストモジュールは常にテストセッションと同じです。お客様のユースケースでは、これはコンポーネント化されたアプリケーションのパッケージに相当する場合があります。

テストモジュールを開始するには、Datadog::CI.start_test_module を呼び出し、モジュール名を渡します。

モジュールの実行が終了したら、Datadog::CI::TestModule#finish を呼び出します。

テストスイート

テストスイートは、類似した機能をテストする一連のテストで構成されます。通常、1 つのスイートは、テストが定義されている 1 つのファイルに対応します。

Datadog::CI#start_test_suite を呼び出し、テストスイート名を渡すことで、テストスイートを作成します。

テストスイート内の関連するテストがすべて実行を完了したら Datadog::CI::TestSuite#finish を呼び出します。

テスト

テストは、テストスイートの一部として実行される単一のテストケースを表します。通常、これはテストロジックを含むメソッドに対応します。

Datadog::CI#start_test または Datadog::CI.trace_test を呼び出し、テスト名とテストスイート名を渡すことで、スイート内にテストを作成します。テストスイート名は、前のステップで開始されたテストスイートの名前と同じである必要があります。

テストの実行が終了したら、Datadog::CI::Test#finish を呼び出します。

コード例

次のコードは、API の使用例を表しています。

require "datadog/ci"

Datadog.configure do |c|
  c.service = "my-test-service"
  c.ci.enabled = true
end

def run_test_suite(tests, test_suite_name)
  test_suite = Datadog::CI.start_test_suite(test_suite_name)

  run_tests(tests, test_suite_name)

  test_suite.passed!
  test_suite.finish
end

def run_tests(tests, test_suite_name)
  tests.each do |test_name|
    Datadog::CI.trace_test(test_name, test_suite_name) do |test|
      test.passed!
    end
  end
end

Datadog::CI.start_test_session(
  tags: {
    Datadog::CI::Ext::Test::TAG_FRAMEWORK => "my-framework",
    Datadog::CI::Ext::Test::TAG_FRAMEWORK_VERSION => "0.0.1",
  }
)
Datadog::CI.start_test_module("my-test-module")

run_test_suite(["test1", "test2", "test3"], "test-suite-name")

Datadog::CI.active_test_module&.passed!
Datadog::CI.active_test_module&.finish

Datadog::CI.active_test_session&.passed!
Datadog::CI.active_test_session&.finish

ベストプラクティス

テストセッション名 `DD_TEST_SESSION_NAME`

DD_TEST_SESSION_NAME を使用してテストセッションの名前と関連するテストグループを定義します。このタグの値の例は次のとおりです。

unit-tests
integration-tests
smoke-tests
flaky-tests
ui-tests
backend-tests

DD_TEST_SESSION_NAME が指定されていない場合、デフォルトで CI ジョブ名とテストコマンドになります。CI ジョブ名が利用できない場合は、テストコマンドが使用されます。

異なるテストグループを区別しやすくするため、テストセッション名はリポジトリ内で一意でなければなりません。

`DD_TEST_SESSION_NAME` を使用するタイミング

Datadog がテストセッション間の対応関係を確立するためにチェックするパラメーターのセットがあります。テストの実行に使用されるテストコマンドもその 1 つです。テストコマンドに、実行するファイルのリストなど、実行ごとに変化する文字列が含まれている場合、Datadog はそれらのセッションを互いに無関係なものとみなします。たとえば、以下のような場合です。