- 重要な情報
- はじめに
- 用語集
- エージェント
- インテグレーション
- OpenTelemetry
- 開発者
- API
- CoScreen
- アプリ内
- インフラストラクチャー
- アプリケーションパフォーマンス
- 継続的インテグレーション
- ログ管理
- セキュリティ
- UX モニタリング
- 管理
対応するテストフレームワーク:
jsdom
(パッケージ jest-environment-jsdom
) と node
(パッケージ jest-environment-node
) のみです。jest-electron-runner
に含まれる @jest-runner/electron/environment
のようなカスタム環境はサポートされていません。testRunner
としては、jest-circus
と jest-jasmine2
のみをサポートしています。dd-trace>=2.7.0
からしかサポートされませんdd-trace>=1.4.0
以降dd-trace>=3.13.0
と dd-trace>=2.26.0
以降インスツルメンテーションは実行時に動作するため、TypeScript、Webpack、Babel などのトランスパイラーにすぐに対応できます。
テストスイートレベルの視覚化は dd-trace>=3.14.0
および dd-trace>=2.27.0
から完全にサポートされています。Jest、Mocha、Playwright、Cypress、Cucumber がサポートされました。
dd-trace>=3.10.0
以降testRunner
としては、jest-circus
のみサポートされますdd-trace>=3.10.0
と dd-trace>=2.12.0
以降dd-trace>=3.13.0
and dd-trace>=2.26.0
for 2.x release line.dd-trace>=3.14.0
と dd-trace>=2.27.0
以降dd-trace>=3.14.0
と dd-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 と通信させます。
GitHub Actions や CircleCI など、基盤となるワーカーノードにアクセスできないクラウド CI プロバイダーを使用している場合は、Agentless モードを使用するようにライブラリを構成します。そのためには、以下の環境変数を設定します。
DD_CIVISIBILITY_AGENTLESS_ENABLED=true
(必須)false
DD_API_KEY
(必須)(empty)
さらに、どの Datadog サイトにデータを送信するかを構成します。
DD_SITE
(必須)datadoghq.com
JavaScript tracer をインストールするには、次を実行します:
yarn add --dev dd-trace
詳しくは、JavaScript トレーサーのインストールに関するドキュメントを参照してください。
NODE_OPTIONS
環境変数を -r dd-trace/ci/init
に設定します。環境変数 DD_ENV
にテストを実行する環境を指定し、通常通りテストを実行してください。例えば、開発者のワークステーションでテストを実行する場合は DD_ENV
を local
に設定し、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_ENV
を local
に設定し、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_ENV
を local
に設定し、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 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
より古いバージョンを使用している場合の手順です。
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)
}
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 カスタムインスツルメンテーションドキュメントのタグの追加セクションを参照してください。
テスト対象のブラウザアプリケーションが RUM を使用してインスツルメントされている場合、Cypress テストの結果と生成された RUM ブラウザセッションおよびセッションリプレイは自動的にリンクされます。詳しくは、RUM インテグレーションガイドをご参照ください。
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
local
、ci
url
http://hostname:port
の形式のトレース収集用の Datadog Agent URL。DD_TRACE_AGENT_URL
http://localhost:8126
他のすべての Datadog トレーサーコンフィギュレーションオプションも使用できます。
Datadog は、テスト結果を可視化し、リポジトリ、ブランチ、コミットごとにグループ化するために Git の情報を使用します。Git のメタデータは、CI プロバイダーの環境変数や、プロジェクトパス内のローカルな .git
フォルダがあれば、そこからテストインスツルメンテーションによって自動的に収集されます。
サポートされていない CI プロバイダーでテストを実行する場合や、.git
フォルダがない場合は、環境変数を使って Git の情報を手動で設定することができます。これらの環境変数は、自動検出された情報よりも優先されます。Git の情報を提供するために、以下の環境変数を設定します。
DD_GIT_REPOSITORY_URL
git@github.com:MyCompany/MyApp.git
、https://github.com/MyCompany/MyApp.git
DD_GIT_BRANCH
develop
DD_GIT_TAG
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
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
2021-03-12T16:00:28Z
dd-trace>=3.15.0
および dd-trace>=2.28.0
から、CI Visibility は git メタデータ情報 (コミット履歴) を自動的にアップロードします。このメタデータにはファイル名は含まれていますが、ファイルの内容は含まれていません。この動作をオプトアウトしたい場合は、DD_CIVISIBILITY_GIT_UPLOAD_ENABLED
を false
に設定することで可能です。しかし、Intelligent Test Runner などの機能はこの設定なしでは動作しないため、この設定は推奨されません。
Mocha >=9.0.0 はテストファイルの読み込みに ESM-first アプローチを採用しています。つまり、ES モジュールが使用されている場合 (たとえば、テストファイルの拡張子を .mjs
にして定義している場合) は_インスツルメンテーションが制限されます_。テストは検出されますが、自分のテストを可視化することはできません。ES モジュールについて詳しくは、Node.js に関するドキュメントを参照してください。
mocha
、jest
、cucumber
、cypress
、playwright
で実行されるブラウザテストは dd-trace-js
によりインスツルメントされますが、ブラウザセッション自体の可視性はデフォルトでは提供されません(ネットワーク呼び出し、ユーザーのアクション、ページロードなど)。
ブラウザ処理の可視性を希望する場合は、RUM とセッションリプレイの使用をご検討ください。Cypress を使用していると、テスト結果と生成された RUM ブラウザセッションおよびセッションリプレイは自動的にリンクされます。詳しくは、RUM インテグレーションガイドをご参照ください。
Cypress インタラクティブモード (cypress open
を実行することで入ることができる) は、before:run
など一部の cypress イベントが発生しないため、CI Visibility ではサポートされていません。もし試してみたい場合は、cypress コンフィグレーションファイルに experimentalInteractiveRunEvents: true
を渡してください。
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 を有効にすると、プロジェクトから以下のデータが収集されます。
さらに、Intelligent Test Runner を有効にすると、プロジェクトから以下のデータが収集されます。