並列テスト

TeamCity は、テストを複数のビルドエージェントに分散することでテストの実行を並列化できるようになり、テストの全体的な期間を最小限に抑えることができます。ビルドのテストは自動的にバッチに分割でき、各バッチは個別のビルドエージェントで実行されます。この機能は、ビルドが複数のエージェントのリソースを利用して技術的に並行して実行できる一方で、結果的に同じエージェントで多くの独立したテストを実行する場合の一般的なユースケースに対応します。以前は、このような動作をエミュレートするために、一部のユーザーはいくつかのビルド構成を構成し、並列接続を使用してチェーンに参加させていました。このアプローチは機能しますが、バッチ間でテストを分散するという重要なロジックを実装する必要がある場合があります。

TeamCity 2022.04 では、テストのディストリビューションロジックは TeamCity 自体によって提供されます。さらに、Maven、Gradle、IntelliJ IDEA プロジェクト、.NET などのビルドランナーは、ビルドステップの設定を変更することなく、エージェントのテストを自動的にフィルタリングできます。

テストを並行して実行する

並列テストビルド機能は、異なるエージェント上での並列テスト実行のタスクを解決します。

既存のビルド構成でこの機能を有効にするには:

構成設定を開き、機能を構築する設定タブに移動します。
ビルド機能を追加をクリックし、並列テストタイプを選択します。
テストバッチ数を設定します。これは、ビルドで使用する並列エージェントの数も意味します。

TeamCity は、テストをバッチに分割して並行して実行する前に、少なくとも 1 つの先行ビルドのテスト統計を収集する必要があります。この情報は、テストを（テスト期間に基づいて）ほぼ同じサイズのバッチに細分化して、合計ビルド時間を可能な限り短くできます。新しく追加されたビルド構成でこの機能を有効にすると、最初のビルドは通常モードで実行されます。終了してテストレポートを作成すると、TeamCity は 2 番目のレポートを分割できるようになります。

TeamCity は、実行された最新のテストだけでなく、テストの履歴も考慮に入れます。並列テストを使用した次のビルドもこの統計に貢献し、TeamCity がより実用的な決定を下せるようにします。

もっと詳しく

テスト統計が利用可能な場合、新しいビルドがトリガーされると次のようになります。

TeamCity は、ビルド機能で指定されたバッチの数に従って、現在のビルド構成のコピーを生成します。これらのビルド構成は、元の構成と同じビルドステップになります。将来的には、元の構成のビルドステップへの変更は、生成されたものに自動的に反映されます。
トリガーされたビルドは、生成されたビルド構成からのビルドに依存する複合ビルドに変換されます。
最初の依存関係ビルドが開始されるとすぐに、複合ビルドも開始されます。

生成されたビルド構成のビルドは、元のビルド構成で定義されたものと同じ一連のビルドステップを実行します。これらのステップの一部が Maven、Gradle、IntelliJ IDEA プロジェクト、.NET タイプであり、いくつかのテストを実行していた場合、これらのビルドランナーは、現在のバッチに対応するテストの一部のみを自動的に実行します。

テストを別の方法で実行する場合でも、構成に対して並列テストビルド機能を有効にして、自動テスト分割のメリットを享受できます。ビルド機能によって提供されるビルドパラメーターから、実行するテストに関する情報が取得されます。

ランナー固有の要件

テストのセット全体ではなく、テストのバッチの自動実行は、次の要件が満たされている場合にのみサポートされます。

Maven
- Maven の最小サポートバージョン: 3.x。
- Maven Surefire プラグインの最小サポートバージョン: 2.13。
- Maven フェイルセーフプラグインの最小サポートバージョン: 2.13。
Gradle
- Gradle の最小サポートバージョン: 5.0。
.NET
- Microsoft.NET.Test.Sdk の最小サポートバージョン: 16.0。

並列化されたテストのカスタム実行

一部のワークフローでは、TeamCity はテスト実行を制御しないため、テストをバッチに分割できません。例: テストが動的に生成される場合、カスタムビルドステップによって報告される場合、またはファイルからインポートされる場合。

TeamCity は実行されたテストを追跡し、過去の実行を分析して最適なバッチ配分を計算します。このデータは、以下のパラメーターで取得できます。

teamcity.build.parallelTests.currentBatch — 現在のバッチ番号（1 から始まる）。
teamcity.build.parallelTests.totalBatches — バッチの合計数。
system.teamcity.build.parallelTests.excludesFile — currentBatch の実行時に無効にするテストに関する情報を保存する excludesFile.txt ファイルへのエージェントマシン上のパス。

テストを並列に実行するには、これらのパラメーターを読み取り、現在のバッチに属さないテストを無効にするカスタムメカニズム (テストフレームワーク拡張機能やビルドステップなど) を実装します。

excludesFile ファイルは TeamCity サーバーによって生成されるため、手動で変更しないでください。このファイルの形式は次のとおりです。

#version=<value>
#algorithm=<value>
#current_batch=<value>
#total_batches=<value>
#suite=<value1>
#suite=<value2>
...
<newline-separated list of test classes>

バージョン

ファイル形式のバージョンを示す整数値。カスタムテスト実行ロジックはバージョンをチェックし、バージョンが予期しない値である場合はエラーを報告するか、ビルドを失敗させることを意味します。

アルゴリズム

テストをバッチに分割するアルゴリズムのタイプ。使用可能な値:

DURATION — ほぼ同じ実行時間を持つバッチを作成するために、テストクラスの実行時間を主要なメトリクスとして優先します。
SPLIT_SUITE — テストスイート内の各テストクラスを N 個のバッチに分割します。
GROUP_SUITES — DURATION と同じですが、個々のテストクラスを無視して、同じスイートのすべてのテストを 1 つのバッチにグループ化します。

current_batch

現在のバッチ番号。teamcity.build.parallelTests.currentBatch パラメーターと同じです。

total_batches

バッチの合計数。teamcity.build.parallelTests.totalBatches パラメーターと同じです。

スイート

テストスイート名。このパラメーターは空でも構いません。バッチに複数のスイートのテストが含まれている場合、各スイートは別々の行にリストされます。

注: Java および .NET テストフレームワークは通常、次の形式で TeamCity にテストを報告します。

[<suite name>: ]<fully qualified test class name>.<test method>[<test arguments>]

<suite name> および <test arguments> はオプションであり、常に存在するとは限りません。

例: 次の Java テストクラス:

package org.example.tests;

class TestCase1 {

  public void testMethod1() { /* ... */ }

  public void testMethod2() { /* ... */ }
}

TeamCity で次のテスト名が生成されます。

org.example.tests.TestCase1.testMethod1
org.example.tests.TestCase1.testMethod2

次に、パラメーター system.teamcity.build.parallelTests.excludesFile は、次の内容のテキストファイルを指します。

#version=1
#current_batch=1
#total_batches=3
#suite=
org.example.tests.TestCase1

.NET の代替テストフィルタリング

.NET ランナーが大量のテストクラスを処理する場合、並列テストにより、NUnit などのテストエンジンで解析して使用するのが難しい巨大なテストフィルターが生成される可能性があります。

潜在的なパフォーマンスの問題を回避するために、TeamCity は、これらのケースに最適化された代替テストフィルタリングモードを自動的に採用します。このモードは、次の条件が満たされる場合、エージェントごとに有効になります。

テストバッチを実行するエージェントは、.NET CLI (SDK またはランタイム) 6.0 以降を報告します。
テストバッチには 1000 以上のテストクラスが含まれます。このしきい値は、teamcity.internal.dotnet.test.suppression.test.classes.threshold 構成パラメーターを介して変更できます。

TeamCity がこのモードに切り替わらないようにし、個々のプロジェクトまたはビルド構成で通常のフィルターメカニズムを使用して常に並列 .NET テストを実行するように強制できます。これを行うには、teamcity.internal.dotnet.test.suppression=false パラメーターを必要な構成またはプロジェクトに追加します。

バッチビルドによって生成されたアーティファクトの公開

並列テストは独立したバッチビルド内で実行されるため、アーティファクトは親構成のビルドではなく、実際のビルドルーチンを実行するこれらのバッチビルドによって生成されます。TeamCity は、アーティファクトに簡単にアクセスできるように、個々のバッチからのアーティファクトをメイン構成のビルドに集約します。

バッチビルドによって同一のアーティファクトが生成される場合、親構成のアーティファクトタブには最新のバッチビルドのアーティファクトのみが表示されます。

これらのファイルがすべて関連しており、メインビルドから表示する必要がある場合は、並列テスト機能のアーティファクト設定を有効にします。

object Build : BuildType({
    name = "Build"
    artifactRules = ".teamcity/Paralleltests/buildTypes => artifacts"

    // ...

    features {
        parallelTests {
            numberOfBatches = 2
            separateArtifacts = true
        }
    }
})

これにより、TeamCity はメイン構成ビルドでバッチ出力を集約するときに、「batchN」フォルダーに配置できるようになります。

アーティファクトパスにパラメーターを追加することで、カスタムグループ化ロジックを実装できます。パラメーターはバッチごとに一意の値を持つ必要があります。例: teamcity.build.parallelTests.currentBatch パラメーターを追加すると、前述の並列テスト機能の設定と同様の結果が生成されます。

import jetbrains.buildServer.configs.kotlin.*
import jetbrains.buildServer.configs.kotlin.buildFeatures.parallelTests

object Build : BuildType({
    // ...
    artifactRules = "GithubAssets/reports => Artifacts/%teamcity.build.parallelTests.currentBatch%"
    // ...
})

アップストリームチェーンビルドでの並列テスト

常に新しいビルドを実行するの動作 ( スナップショット依存関係の適切なものがあれば、新しいビルドを実行しないでください設定が無効) は、メイン構成ビルドにのみ影響します。並列テスト機能の使用時に動的に生成される仮想ビルド構成では、以前の結果が再利用される可能性があります。新しいリポジトリコミットが検出されなかった場合、以前に失敗したテストバッチのみが新しいビルドを実行し、成功したバッチは再利用されます。

下の図では、「Composite Conf」構成は「Maven App」構成に依存しています。後者は、2 つの並列バッチでテストを実行します。メインの「Maven app」ビルド #18 は新たにトリガーされますが、動的に生成された「Maven app 1」構成は、以前の成功したビルド (#12) を再利用することに注意してください。

TeamCity にすべての仮想構成ビルドを強制的に再実行させることができます。この場合、新しいリポジトリコミットが見つからなくても、個々のテストバッチはすべて新たに実行されます。

これを行うには、並列テスト機能を含む構成に teamcity.internal.splitBuild.dependency.takeStartedBuildWithSameRevisions=false パラメーターを追加します。

この動作をサーバー上のすべての構成に適用するには、このパラメーターを内部プロパティリストに追加します。

既知の制限

コードカバレッジ統計は、現在のバッチによって実行されたテストの一部に対して収集されるため、並列テストを使用したビルドでは不正確になります。
TeamCity にまだ認識されていない新しく追加されたテストは、最初の実行中に各バッチで実行されます。関連する YouTrack チケット: TW-75913(英語)。
TeamCity がテストをバッチに分割する場合、テスト自体の期間のみが考慮されます。setUp/tearDown またはその他の準備方法の期間は TeamCity に認識されていないため、バッチの期間は等しくない場合があります。
ビルドはトリガー後に複合ビルドに変換されるため、並列テストを含むビルドのカスタムビルドダイアログで選択されたエージェントは無視されます。関連する YouTrack チケット: TW-74905(英語)。
setParameter サービスメッセージを介してビルドステップによって公開されたパラメーター、および maven.project.version などのランナー固有のパラメーターは、並列テストを含む複合ビルドでは使用できません。関連する YouTrack チケット: TW-75249(英語)。
TeamCity Professional バージョンのビルド構成の制限に関しては、自動的に生成されたビルド構成が通常のビルド構成としてカウントされます。

既知のバグ

クリーンチェックアウトアクションを実施するは、並列テストが構成されたビルド構成では機能しません。関連する YouTrack チケット: TW-75337(英語)。
Gradle では、XML スイート(英語)から TestNG(英語) テストを実行するために生成されたバッチビルドが、指定されたテストのサブセットではなく、すべてのテストを実行します。関連する YouTrack チケット: TW-75849(英語)。
Maven と TestNG(英語) の組み合わせでは、XML スイート(英語)ファイルは無視されます。関連する YouTrack チケット: TW-95644(英語)。

2025 年 11 月 04 日

TeamCity オンプレミス 2026.1 ヘルプ