互換性

サポートされている言語:

サポートされているテストフレームワーク:

サポートされているテストランナー:

レポート方法の構成

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

Ruby Test Visibility ライブラリのインストール

Ruby Test Visibility ライブラリをインストールするには

1. Gemfile に datadog-ci gem を追加します。

source "<https://rubygems.org>"
gem "datadog-ci", "~> 1.0", group: :test

2. bundle install を実行して gem をインストールします。

テストのインスツルメンテーション

require "rspec"
require "datadog/ci"

# CI 上でテストインスツルメンテーションのみを有効にします
if ENV["DD_ENV"] == "ci"
Datadog.configure do |c|
# Test Visibility を有効にします
c.ci.enabled = true

# テスト対象のサービスまたはライブラリの名前
c.service = "my-ruby-app"

# RSpec のインスツルメンテーションを有効にします
c.ci.instrument :rspec
end
end

DD_ENV=ci bundle exec rake spec

require "minitest"
require "datadog/ci"

# CI 上でテストインスツルメンテーションのみを有効にします。
if ENV["DD_ENV"] == "ci"
Datadog.configure do |c|
# Test Visibility を有効にします
c.ci.enabled = true

# テスト対象のサービスまたはライブラリの名前
c.service = "my-ruby-app"

c.ci.instrument :minitest
end
end

DD_ENV=ci bundle exec rake test

require "datadog/ci"
require "minitest/autorun"

if ENV["DD_ENV"] == "ci"
  Datadog.configure do |c|
    c.ci.enabled = true

    c.service = "my-ruby-app"

    c.ci.instrument :minitest
  end
end

require "cucumber"
require "datadog/ci"

# CI 上でテストインスツルメンテーションのみを有効にします
if ENV["DD_ENV"] == "ci"
  Datadog.configure do |c|
    # Test Visibility を有効にします
    c.ci.enabled = true

    # テスト対象のサービスまたはライブラリの名前
    c.service = "my-ruby-app"

    # Cucumber のインスツルメンテーションを有効にします
    c.ci.instrument :cucumber
  end
end

DD_ENV=ci bundle exec rake cucumber

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

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

require "datadog/ci"

# テスト内
Datadog::CI.active_test&.set_tag("test_owner", "my_team")
# テストは正常に続きます
# ...

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

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

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

require "datadog/ci"

# テスト内
Datadog::CI.active_test&.set_metric("memory_allocations", 16)
# テストは正常に続きます
# ...

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

構成設定

以下は、Datadog.configure ブロックを使用するか、環境変数を使用するコードで、Test Visibility ライブラリで使用できる最も重要なコンフィギュレーション設定のリストです。

service

テスト中のサービスまたはライブラリの名前。
環境変数: DD_SERVICE
デフォルト: $PROGRAM_NAME
例: my-ruby-app

env

テストが実行されている環境の名前。
環境変数: DD_ENV
デフォルト: none
例: local、ci

service と env の予約タグの詳細については、統合サービスタグ付けを参照してください。

次の環境変数を使用して、Datadog Agent の場所を構成できます。

DD_TRACE_AGENT_URL

http://hostname:port の形式のトレース収集用の Datadog Agent URL。
デフォルト: http://localhost:8126

他のすべての Datadog トレーサーコンフィギュレーションオプションも使用できます。

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

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

これを実現するには、configure ブロックで追加のインスツルメンテーションを構成します。

if ENV["DD_ENV"] == "ci"
  Datadog.configure do |c|
    #  ... ci 構成とインスツルメンテーションをここに ...
    c.tracing.instrument :redis
    c.tracing.instrument :pg
    # ... Datadog gem がサポートするその他のインスツルメンテーション ...
  end
end

または、test_helper/spec_helper で自動インスツルメンテーションを有効にすることもできます。

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

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

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

Webmock/VCR

Webmock と VCR は、テスト実行時に HTTP リクエストをスタブ化する人気の高い Ruby ライブラリです。デフォルトでは、HTTP コールでトレースが Datadog に送信されるため、datadog-ci と併用時には失敗します。

Datadog バックエンドへの HTTP 接続を許可するには、Webmock と VCR を適切に構成する必要があります。

# Webmock
# エージェントレスモードを使用している場合:
WebMock.disable_net_connect!(:allow => /datadoghq/)

# ローカルで実行している Agent を使用している場合:
WebMock.disable_net_connect!(:allow_localhost => true)

# または、より詳細な設定を行うには、Agent URL を設定します。例:
WebMock.disable_net_connect!(:allow => "localhost:8126")

# VCR
VCR.configure do |config|
  # ... your usual configuration here ...

  # Agent を使用している場合
  config.ignore_hosts "127.0.0.1", "localhost"

  # エージェントレスモードを使用している場合
  config.ignore_request do |request|
    # datadoghq ホストへのすべてのリクエストを無視します
    request.uri =~ /datadoghq/
  end
end

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

Datadog は、テスト結果を可視化し、リポジトリ、ブランチ、コミットごとにグループ化するために Git の情報を使用します。Git のメタデータは、CI プロバイダーの環境変数や、プロジェクトパス内のローカルな .git フォルダがあれば、そこからテストインスツルメンテーションによって自動的に収集されます。

サポートされていない CI プロバイダーでテストを実行する場合や、.git フォルダがない場合は、環境変数を使って Git の情報を手動で設定することができます。これらの環境変数は、自動検出された情報よりも優先されます。Git の情報を提供するために、以下の環境変数を設定します。

DD_GIT_REPOSITORY_URL

コードが格納されているリポジトリの URL。HTTP と SSH の両方の URL に対応しています。
例: git@github.com:MyCompany/MyApp.git、https://github.com/MyCompany/MyApp.git

DD_GIT_BRANCH

テスト中の Git ブランチ。タグ情報を指定する場合は、空のままにしておきます。
例: develop

DD_GIT_TAG

テストされる Git タグ (該当する場合)。ブランチ情報を指定する場合は、空のままにしておきます。
例: 1.0.1

DD_GIT_COMMIT_SHA

フルコミットハッシュ。
例: a18ebf361cc831f5535e58ec4fae04ffd98d8152

DD_GIT_COMMIT_MESSAGE

コミットのメッセージ。
例: Set release number

DD_GIT_COMMIT_AUTHOR_NAME

コミット作成者名。
例: John Smith

DD_GIT_COMMIT_AUTHOR_EMAIL

コミット作成者メールアドレス。
例: john@example.com

DD_GIT_COMMIT_AUTHOR_DATE

ISO 8601 形式のコミット作成者の日付。
例: 2021-03-12T16:00:28Z

DD_GIT_COMMIT_COMMITTER_NAME

コミットのコミッター名。
例: Jane Smith

DD_GIT_COMMIT_COMMITTER_EMAIL

コミットのコミッターのメールアドレス。
例: jane@example.com

DD_GIT_COMMIT_COMMITTER_DATE

ISO 8601 形式のコミットのコミッターの日付。
例: 2021-03-12T16:00:28Z

手動テスト API の使用

RSpec、Minitest、または Cucumber を使用している場合は、手動テスト API を使用しないでください。CI Visibility は自動的にインスツルメンテーションを行い、テスト結果を Datadog に送信するためです。手動テスト 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 を呼び出します。

テスト

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

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

参考資料

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

コンテナ内のテスト用に環境変数を転送するドキュメント テスト結果とパフォーマンスを確認するドキュメント CI Visibility のトラブルシューティングドキュメント