JavaScript と TypeScript のテスト

選択したサイト () では、現時点では CI Visibility は使用できません。

互換性

対応するテストフレームワーク:

  • Jest >= 24.8.0
    • テスト環境としてサポートされているのは、jsdom (パッケージ jest-environment-jsdom) と node (パッケージ jest-environment-node) のみです。jest-electron-runner に含まれる @jest-runner/electron/environment のようなカスタム環境はサポートされていません。
    • testRunner としては、jest-circusjest-jasmine2 のみをサポートしています。
    • Jest >= 28 は dd-trace>=2.7.0 からしかサポートされません
  • Mocha >= 5.2.0
  • Cucumber-js >= 7.0.0
  • Cypress >= 6.7.0
    • dd-trace>=1.4.0 以降
  • Playwright >= 1.18.0
  • 2.x リリースラインの dd-trace>=3.13.0dd-trace>=2.26.0 以降

インスツルメンテーションは実行時に動作するため、TypeScript、Webpack、Babel などのトランスパイラーにすぐに対応できます。

テストスイートレベルの視覚化互換性

テストスイートレベルの視覚化dd-trace>=3.14.0 および dd-trace>=2.27.0 から完全にサポートされています。Jest、Mocha、Playwright、Cypress、Cucumber がサポートされました。

  • Jest >= 24.8.0
  • dd-trace>=3.10.0 以降
  • testRunner としては、jest-circus のみサポートされます
  • Mocha >= 5.2.0
  • 2.x リリースラインの dd-trace>=3.10.0dd-trace>=2.12.0 以降
  • Playwright >= 1.18.0
  • From dd-trace>=3.13.0 and dd-trace>=2.26.0 for 2.x release line.
  • Cypress >= 6.7.0
  • 2.x リリースラインの dd-trace>=3.14.0dd-trace>=2.27.0 以降
  • Cucumber >= 7.0.0
  • 2.x リリースラインの dd-trace>=3.14.0dd-trace>=2.27.0 以降

報告方法の構成

Datadog にテスト結果を報告するには、Datadog の JavaScript ライブラリを構成する必要があります。

Jenkins や自己管理型の GitLab CI などのオンプレミス CI プロバイダーでテストを実行する場合、Agent インストール手順に従って各ワーカノードに Datadog Agent をインストールします。これは、テスト結果が自動的に基礎となるホストメトリクスにリンクされるため、推奨されるオプションです。

CI プロバイダーがコンテナベースのエグゼキューターを使用している場合、ビルド内の localhost がコンテナ自体を参照しており、Datadog Agent が動作している基礎となるワーカーノードではないため、すべてのビルドで DD_AGENT_HOST 環境変数 (デフォルトは http://localhost:8126) を、ビルドコンテナの中からアクセスできるエンドポイントに設定します。

Kubernetes のエグゼキューターを使用している場合、Datadog は Datadog Admission Controller の使用を推奨しており、これは自動的にビルドポッドの環境変数 DD_AGENT_HOST を設定してローカルの Datadog Agent と通信させます。

Agentless モードは、Datadog JavaScript ライブラリのバージョン >= 2.5.0 で使用できます

GitHub Actions や CircleCI など、基盤となるワーカーノードにアクセスできないクラウド CI プロバイダーを使用している場合は、Agentless モードを使用するようにライブラリを構成します。そのためには、以下の環境変数を設定します。

DD_CIVISIBILITY_AGENTLESS_ENABLED=true (必須)
Agentless モードを有効または無効にします。
デフォルト: false
DD_API_KEY (必須)
テスト結果のアップロードに使用される Datadog API キー
デフォルト: (empty)

さらに、どの Datadog サイトにデータを送信するかを構成します。

DD_SITE (必須)
結果をアップロードする Datadog サイト
デフォルト: datadoghq.com
選択したサイト:

JavaScript トレーサーのインストール

JavaScript tracer をインストールするには、次を実行します:

yarn add --dev dd-trace

詳しくは、JavaScript トレーサーのインストールに関するドキュメントを参照してください。

テストのインスツルメント

NODE_OPTIONS 環境変数を -r dd-trace/ci/init に設定します。環境変数 DD_ENV にテストを実行する環境を指定し、通常通りテストを実行してください。例えば、開発者のワークステーションでテストを実行する場合は DD_ENVlocal に設定し、CI プロバイダでテストを実行する場合は ci に設定します。

NODE_OPTIONS="-r dd-trace/ci/init" DD_ENV=ci DD_SERVICE=my-javascript-app yarn test

重要: NODE_OPTIONS に値を設定する場合、-r dd-trace/ci/init を上書きしないように注意してください。これは ${NODE_OPTIONS:-} 節を使用して行うことができます。

package.json

{
  "scripts": {
    "test": "NODE_OPTIONS=\"--max-old-space-size=12288 ${NODE_OPTIONS:-}\" jest"
  }
}

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

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

  it('sum function can sum', () => {
    const testSpan = require('dd-trace').scope().active()
    testSpan.setTag('team_owner', 'my_team')
    // テストは正常に続きます
    // ...
  })

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

NODE_OPTIONS 環境変数を -r dd-trace/ci/init に設定します。環境変数 DD_ENV にテストを実行する環境を指定し、通常通りテストを実行してください。例えば、開発者のワークステーションでテストを実行する場合は DD_ENVlocal に設定し、CI プロバイダでテストを実行する場合は ci に設定します。

NODE_OPTIONS="-r dd-trace/ci/init" DD_ENV=ci DD_SERVICE=my-javascript-app yarn test

重要: NODE_OPTIONS に値を設定する場合、-r dd-trace/ci/init を上書きしないように注意してください。これは ${NODE_OPTIONS:-} 節を使用して行うことができます。

package.json

{
  "scripts": {
    "test": "NODE_OPTIONS=\"--max-old-space-size=12288 ${NODE_OPTIONS:-}\" jest"
  }
}

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

Playwright では、カスタムタグはサポートされていません。

NODE_OPTIONS 環境変数を -r dd-trace/ci/init に設定します。環境変数 DD_ENV にテストを実行する環境を指定し、通常通りテストを実行してください。例えば、開発者のワークステーションでテストを実行する場合は DD_ENVlocal に設定し、CI プロバイダでテストを実行する場合は ci に設定します。

NODE_OPTIONS="-r dd-trace/ci/init" DD_ENV=ci DD_SERVICE=my-javascript-app yarn test

: NODE_OPTIONS に値を設定する場合、-r dd-trace/ci/init を上書きしないように注意してください。これは ${NODE_OPTIONS:-} 節を使用して行うことができます。

package.json

{
  "scripts": {
    "test": "NODE_OPTIONS=\"--max-old-space-size=12288 ${NODE_OPTIONS:-}\" jest"
  }
}

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

現在アクティブなスパンをつかんで、テストにカスタムタグを追加することができます。

  When('the function is called', function () {
    const stepSpan = require('dd-trace').scope().active()
    testSpan.setTag('team_owner', 'my_team')
    // テストは正常に続きます
    // ...
  })

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

Cypress >=10

Cypress API ドキュメントを使用して、cypress>=10 のためのプラグインの書き方を学ぶことができます。

cypress.config.js ファイルで、以下を設定します。

cypress.config.js

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    setupNodeEvents: require('dd-trace/ci/cypress/plugin'),
    supportFile: 'cypress/support/e2e.js'
  }
})

次の行を supportFileトップレベル に追加します。

cypress/support/e2e.js

// この行の前にコードを記述することができます
// require('./commands')
require('dd-trace/ci/cypress/support')
// こちらもサポート:
// import 'dd-trace/ci/cypress/support'
// この行の後にコードを記述することもできます
// Cypress.Commands.add('login', (email, pw) => {})

他の Cypress プラグインを使用している場合、cypress.config.js ファイルに以下の内容が含まれている必要があります。

cypress.config.js

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      // 前のコードはこの行の前にあります
      require('dd-trace/ci/cypress/plugin')(on, config)
    }
  }
})

Cypress<10

以下は、cypress@10 より古いバージョンを使用している場合の手順です。

  1. pluginsFile を、たとえば cypress.json を介して "dd-trace/ci/cypress/plugin" に設定します:

cypress.json

{
  "pluginsFile": "dd-trace/ci/cypress/plugin"
}

すでに pluginsFile を定義している場合も、以下を使用してインスツルメンテーションを初期化できます:

cypress/plugins/index.js

module.exports = (on, config) => {
  // 以前のコードは、この行の前になります
  require('dd-trace/ci/cypress/plugin')(on, config)
}
  1. 次の行を supportFileトップレベル に追加します。

cypress/support/index.js

// この行の前にコードを記述することができます
// require('./commands')
require('dd-trace/ci/cypress/support')
// この行の後にコードを記述することもできます
// Cypress.Commands.add('login', (email, pw) => {})

DD_ENV 環境変数でテストを実行する環境 (たとえば、開発者ワークステーションでテストを実行する場合は local、CI プロバイダーでテストを実行する場合は ci) を指定して、通常どおりにテストを実行します。例:

DD_ENV=ci DD_SERVICE=my-ui-app npm test

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

テストに、チームオーナーなどの情報を追加するには、テストまたはフックで cy.task('dd:addTags', { yourTags: 'here' }) を使用します。

例:

beforeEach(() => {
  cy.task('dd:addTags', {
    'before.each':
    'certain.information'
  })
})
it('renders a hello world', () => {
  cy.task('dd:addTags', {
    'team.owner': 'ui',
    'test.importance': 3
  })
  cy.get('.hello-world')
    .should('have.text', 'Hello World')
})

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

Cypress - RUM インテグレーション

テスト対象のブラウザアプリケーションが RUM を使用してインスツルメントされている場合、Cypress テストの結果と生成された RUM ブラウザセッションおよびセッションリプレイは自動的にリンクされます。詳しくは、RUM インテグレーションガイドをご参照ください。

Yarn >=2 を使用する場合

yarn>=2.pnp.cjs ファイルを使用していて、NODE_OPTIONS を使用したときに次のようなエラーメッセージが表示された場合

 Error: Cannot find module 'dd-trace/ci/init'

NODE_OPTIONS を以下のように設定することで修正できます。

NODE_OPTIONS="-r $(pwd)/.pnp.cjs -r dd-trace/ci/init" yarn test

コンフィギュレーション設定

以下は、トレーサーで使用できる最も重要なコンフィギュレーション設定のリストです。

service
テスト中のサービスまたはライブラリの名前。
環境変数: DD_SERVICE
デフォルト: (テストフレームワーク名)
: my-ui
env
テストが実行されている環境の名前。
環境変数: DD_ENV
デフォルト: none
: localci
url
http://hostname:port の形式のトレース収集用の Datadog Agent URL。
環境変数: DD_TRACE_AGENT_URL
デフォルト: http://localhost:8126

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

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

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

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

DD_GIT_REPOSITORY_URL
コードが格納されているリポジトリの URL。HTTP と SSH の両方の URL に対応しています。
: git@github.com:MyCompany/MyApp.githttps://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

Git メタデータのアップロード

dd-trace>=3.15.0 および dd-trace>=2.28.0 から、CI Visibility は git メタデータ情報 (コミット履歴) を自動的にアップロードします。このメタデータにはファイル名は含まれていますが、ファイルの内容は含まれていません。この動作をオプトアウトしたい場合は、DD_CIVISIBILITY_GIT_UPLOAD_ENABLEDfalse に設定することで可能です。しかし、Intelligent Test Runner などの機能はこの設定なしでは動作しないため、この設定は推奨されません。

既知の制限

ES モジュール

Mocha >=9.0.0 はテストファイルの読み込みに ESM-first アプローチを採用しています。つまり、ES モジュールが使用されている場合 (たとえば、テストファイルの拡張子を .mjs にして定義している場合) は_インスツルメンテーションが制限されます_。テストは検出されますが、自分のテストを可視化することはできません。ES モジュールについて詳しくは、Node.js に関するドキュメントを参照してください。

ブラウザテスト

mochajestcucumbercypressplaywright で実行されるブラウザテストは dd-trace-js によりインスツルメントされますが、ブラウザセッション自体の可視性はデフォルトでは提供されません(ネットワーク呼び出し、ユーザーのアクション、ページロードなど)。

ブラウザ処理の可視性を希望する場合は、RUM とセッションリプレイの使用をご検討ください。Cypress を使用していると、テスト結果と生成された RUM ブラウザセッションおよびセッションリプレイは自動的にリンクされます。詳しくは、RUM インテグレーションガイドをご参照ください。

Cypress インタラクティブモード

Cypress インタラクティブモード (cypress open を実行することで入ることができる) は、before:run など一部の cypress イベントが発生しないため、CI Visibility ではサポートされていません。もし試してみたい場合は、cypress コンフィグレーションファイルexperimentalInteractiveRunEvents: true を渡してください。

Mocha のパラレルテスト

Mocha のパラレルモードはサポートされていません。パラレルモードで実行されたテストは、CI Visibility のインスツルメンテーションを受けません。

ベストプラクティス

テストフレームワークと CI 表示を最大限に活用するために、以下のプラクティスに従ってください。

パラメーターテスト

可能な限り、テストフレームワークが提供するパラメーター化されたテスト用のツールを活用しましょう。たとえば、jest などを利用できます:

回避したいパターン:

[[1,2,3], [3,4,7]].forEach((a,b,expected) => {
  test('sums correctly', () => {
    expect(a+b).toEqual(expected)
  })
})

代わりに test.each を使用:

test.each([[1,2,3], [3,4,7]])('sums correctly %i and %i', (a,b,expected) => {
  expect(a+b).toEqual(expected)
})

mocha の場合は、mocha-each を使用:

const forEach = require('mocha-each');
forEach([
  [1,2,3],
  [3,4,7]
])
.it('adds %i and %i then returns %i', (a,b,expected) => {
  expect(a+b).to.equal(expected)
});

この方法を使用すると、テストフレームワークと CI 表示の両方でテストを区別することができます。

収集した情報

CI Visibility を有効にすると、プロジェクトから以下のデータが収集されます。

  • テストの名前と時間。
  • CI プロバイダーが設定する事前定義された環境変数。
  • Git のコミット履歴。ハッシュ、メッセージ、作成者情報、変更されたファイル (ファイルの内容は含まず) が含まれます。
  • CODEOWNERS ファイルからの情報。

さらに、Intelligent Test Runner を有効にすると、プロジェクトから以下のデータが収集されます。

  • 各テストでカバーされるファイル名と行数を含むコードカバレッジ情報。

その他の参考資料