JavaScript テスト

互換性

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

• Jest >= 24.8.0
  • テスト環境としてサポートされているのは、jsdom (パッケージ jest-environment-jsdom) と node (パッケージ jest-environment-node) のみです。jest-electron-runner に含まれる @jest-runner/electron/environment のようなカスタム環境はサポートされていません。
  • testRunner としては、jest-circus と jest-jasmine2 のみをサポートしています。
  • Jest >= 28 は dd-trace>=2.7.0 からしかサポートされません
• Mocha >= 5.2.0
  • Mocha >= 9.0.0 は部分的なサポートがあります。
• Cucumber-js >= 7.0.0
• Cypress >= 6.7.0
  • dd-trace>=1.4.0 以降

報告方法の構成

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

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

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

yarn add --dev dd-trace

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

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

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

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

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

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

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

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

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

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

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

module.exports = (on, config) => {
  // 以前のコードは、この行の前になります
  require('dd-trace/ci/cypress/plugin')(on, config)
}

// 以前のコードはこの行の前になります
require('dd-trace/ci/cypress/support')

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

const { defineConfig } = require('cypress')

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

// 前のコードはこの行の前にあります
require('dd-trace/ci/cypress/support')

const { defineConfig } = require('cypress')

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

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')
})

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

以下は、トレーサーで使用できる最も重要なコンフィギュレーション設定のリストです。これらは、その init() 関数で渡すか、環境変数として渡すことができます。

service

テスト中のサービスまたはライブラリの名前。
環境変数: DD_SERVICE
デフォルト: (テストフレームワーク名)
例: my-ui

env

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

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.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

既知の制限

ES モジュール

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

ブラウザテスト

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

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

ベストプラクティス

テストフレームワークと 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ドキュメント