migrate-xunit-to-xunit-v3

xunit.v3 への移行

.NET テストプロジェクトを xUnit.net v2 から xUnit.net v3 に移行します。移行後は、すべてのテストプロジェクトが xunit.v3.* パッケージを参照し、エラーなくコンパイルされ、すべてのテストが移行前と同じ結果で合格するソリューションになります。

使用する場合

• テストプロジェクトを xunit（v2）パッケージから xunit.v3 にアップグレードする場合
• xunit パッケージ参照を v3 に更新した後のコンパイルエラーを解決する場合

使用しない場合

• テストフレームワーク間の移行（例：MSTest または NUnit から xUnit.net への移行）— まったく別の作業です
• VSTest から Microsoft.Testing.Platform への移行 — migrate-vstest-to-mtp を使用してください
• プロジェクトがすでに xunit.v3 を参照している場合 — 移行は完了しています

入力

入力	必須	説明
テストプロジェクトまたはソリューション	いいえ	現在の作業ディレクトリ内の .csproj、.sln、.slnx、中央 props ファイル、ソースを検出します。見つからない場合、または対象が曖昧な場合にのみ確認してください

ワークスペースと完了の条件

• スキルの有効化は完了を意味しません。移行／修正／更新の依頼では、同じタスク内で対象ファイルを調査して編集し、テストを実行してください。
• スキルのベースディレクトリにはガイダンスのみが含まれています。現在の作業ディレクトリを検索し、返されたパスをそのまま開いてください。
• ツールが検索したパスを拒否した場合は、再試行する前に拒否の理由を特定してください。リーダーまたはパス正規化の制限が肯定的に確認され、アクセスが許可されている場合に限り、別の許可されたリーダー／エディターを介して再試行できます。
• 権限、ポリシー、またはコンテンツ除外による拒否があった場合は、そのパスでの作業を中止し、妨げとなっている要因を報告してください。他のツール、シェルコマンド、エイリアス、エージェントを使って拒否を回避したり、制限されたコンテンツを推測または再構成したりしてはいけません。
• 拒否の理由が不明な場合、そのパスは見つからなかったのではなく、利用できないものとして扱ってください。独立して許可されている作業のみ続行し、移行が未完了であることを明示してください。
• ワークスペースの検索でパスを特定できる間は、ユーザーにパスの提示を求めないでください。
• プロジェクト／中央パッケージファイルと、影響を受けるすべてのソースを一度に調査してください。v2 専用 API が残っている場合、パッケージのみの移行では不完全です。
• 最後に、検出したソースのバージョンとランナー、正確なパッケージ互換性の組み合わせ、変更したファイル数、検出／合格／失敗／スキップの件数、プラットフォーム固有の結果を記載してください。テストが検出されないビルドは成功ではありません。
• パッケージの有効性は実証によって確認します。設定されたフィードへのクエリ、または解決済みのパッケージグラフと、復元が成功した記録を残してください。最終結果では、選択した正確なバージョンが利用可能であるとどのように確認したかを説明してください。バージョン名だけを示し、その存在を判定者やユーザーに推測させてはいけません。

ワークフロー

コミット方針： ユーザーから依頼されない限り、コミットを作成しないでください。プロジェクト設定の編集とソースの編集は、差分上で論理的に分けてください。ただし、依頼された移行全体を完了し、検証してください。

優先順位： 手順 1～5 はすべての移行で必須です。手順 6～12 は条件付きで、プロジェクトのコードパターンに該当するものだけ適用してください。該当しない手順はスキップしてください。

結果を左右する判断

編集前に、以下の事前確認を実行してください。

検出された状態	必要な対応
プロジェクトが xunit.v3 を参照し、必須の実行可能ファイル／ランナー設定があり、v2 パッケージや v2 専用 API のパターンが残っておらず、既存のテストコマンドが成功する	中止してください。移行はすでに完了しています。バージョンの更新、props ファイルの作成、ソースの変更は行わないでください。検証済みの変更不要という結果を報告してください。必須の v3 対応が残っている場合は、パッケージ参照だけで完了と見なさず、その修正のみ行ってください。
xUnit v2 が YTest.MTP.XUnit2 を使用している	MTP を維持してください。このシムを削除し、UseMicrosoftTestingPlatformRunner=true を設定してください。xunit.runner.visualstudio や IsTestingPlatformApplication=false は追加しないでください。
xUnit v2 が MTP シムを使用していない	VSTest を維持してください。xunit.runner.visualstudio を維持または更新し、IsTestingPlatformApplication=false を設定してください。
カスタム型が BeforeAfterTestAttribute を継承している	その継承と動作を維持してください。両方のオーバーライドに IXunitTest パラメーターを追加し、base.Before／base.After に渡してください。サブクラスを直接のインターフェイス実装に置き換えないでください。
Type ベースのコレクション／順序付け属性がカスタム型を参照している	属性の構文と、参照先の型の v3 コントラクトの両方を移行してください。コレクションファクトリーの場合は、必須の xUnit v3 IXunitTestCollectionFactory の動作を実装してください。空のファクトリーを残したまま属性をコンパイルできるようにするだけでは、移行は完了していません。
関連パッケージが存在する	設定済みのフィードから、xunit.v3、Xunit.Combinatorial、Xunit.StaFact を互換性のあるセットとして解決してください。最新の xunit.v3 メジャーバージョンに、これらのフィードで利用できる互換性のある安定版関連パッケージがない場合は、互換性のある最新の xunit.v3 メジャーバージョンを選び、そのバージョンに固定する理由を説明してください。コンパイルだけでなく、テストの検出も検証してください。
OutputType=Exe により、非 Windows ホストで net*-windows プロジェクトが失敗する	クロスビルドを意図している場合は EnableWindowsTargeting=true を追加してから再実行してください。この移行によって生じた失敗を、移行前から存在していたものとして扱わないでください。

パッケージのバージョンは、設定済みのパッケージソースから解決してください。製品名の「v3」からバージョンを推測したり、無関係なパッケージを更新したりしないでください。該当するルールで必要となるパッケージ、プロパティ、またはソース構文を含むファイルのみ変更してください。

Central Package Management プロジェクトを編集した後は、Directory.Packages.props とプロジェクトファイルを読み返してください。バージョンが PackageVersion で管理されていること、名前を変更した PackageReference にバージョン指定がないこと、OutputType=Exe が有効であることを確認してください。

手順 1：xUnit.net プロジェクトを特定し、互換性を確認する

xUnit.net v2 パッケージを参照しているテストプロジェクトを検索します。

• xunit
• xunit.abstractions
• xunit.assert
• xunit.core
• xunit.extensibility.core
• xunit.extensibility.execution
• xunit.runner.visualstudio

Directory.Build.props、Directory.Build.targets、Directory.Packages.props などの MSBuild props ファイルと targets ファイルにあるパッケージ参照も確認してください。

ターゲットフレームワークの互換性を確認してください。xUnit.net v3 には .NET 8 以降または .NET Framework 4.7.2 以降が必要です。テストライブラリプロジェクトでは .NET Standard 2.0 もサポートされています。互換性のないターゲットフレームワークを使用しているテストプロジェクトがある場合は、ここで作業を中止し、まずターゲットフレームワークをアップグレードするようユーザーに伝えてください。また、プロジェクトが SDK スタイル形式を使用していることも確認してください。

Step 2: パッケージ参照を更新する

1. 次の対応表に基づいて、新しいパッケージ名に合わせて PackageReference または PackageVersion の項目を更新します。

   • xunit → xunit.v3
   • xunit.abstractions → 完全に削除
   • xunit.assert → xunit.v3.assert
   • xunit.core → xunit.v3.core
   • xunit.extensibility.core と xunit.extensibility.execution → xunit.v3.extensibility.core（プロジェクトで両方参照している場合、2 つのパッケージは統合されているため、1 つの項目だけにまとめます）

2. 設定済みのパッケージソースを照会し、実際に存在する最新の安定版のバージョンを指定します。また、xunit.runner.visualstudio の更新は VSTest プロジェクトに限ります。MTP プロジェクトには追加しないでください。

Step 3: OutputType を Exe に設定する

各テストプロジェクト（テストライブラリプロジェクトを除く）で、プロジェクトファイルの OutputType を Exe に設定します。

<PropertyGroup>
  <OutputType>Exe</OutputType>
</PropertyGroup>

ソリューションによっては、これを追加できる共通の場所がある場合があります。たとえば、次のようにします。

• すべてのテストプロジェクトで共通の Directory.Build.props を使用している（または使用できる）場合は、そこに <OutputType>Exe</OutputType> プロパティを追加します。OutputType は Directory.Build.targets に追加しないでください。
• すべてのテストプロジェクトに共通の名前パターン（例：*.Tests.csproj）がある場合は、Directory.Build.props に、<OutputType Condition="$(MSBuildProjectName.EndsWith('.Tests'))">Exe</OutputType> のように、それらのプロジェクトだけに適用される条件付きプロパティグループを追加します。テストプロジェクトだけを対象にするよう、必要に応じて条件を調整してください。
• それ以外の場合は、各テストプロジェクトファイルに <OutputType>Exe</OutputType> プロパティを個別に追加します。

Step 4: テストプラットフォームを構成する

xUnit.net v2 で使用していたテストプラットフォームを維持します。xUnit.net v2 は、プロジェクトで YTest.MTP.XUnit2 を使用していた場合を除き、常に VSTest を使用します。

• プロジェクトが YTest.MTP.XUnit2 を参照していた場合：
  • YTest.MTP.XUnit2 の参照を完全に削除します。
  • 既存の共通 Directory.Build.props に <UseMicrosoftTestingPlatformRunner>true</UseMicrosoftTestingPlatformRunner> を設定します。共通の props ファイルがない場合は、テストプロジェクトに設定します。
  • xunit.runner.visualstudio は追加しないでください。これは VSTest ランナーであり、プラットフォームの維持を損ないます。
• プロジェクトが YTest.MTP.XUnit2 を参照していなかった場合（一般的なケース）：
  • 既存の共通 Directory.Build.props に <IsTestingPlatformApplication>false</IsTestingPlatformApplication> を設定します。共通の props ファイルがない場合は、テストプロジェクトに直接設定します。1 つのプロジェクトだけのために、リポジトリ全体に適用される props ファイルを作成しないでください。これにより、プロジェクトは VSTest を使用し続けます。

Step 5: Xunit.Abstractions の using を削除する

C# ファイル内の using Xunit.Abstractions; ディレクティブを検索し、完全に削除します。

Step 6: async void の破壊的変更に対応する（該当する場合）

xUnit.net v3 では、async void のテストメソッドはサポートされなくなり、コンパイルに失敗します。async void として宣言されたテストメソッドを検索し、async Task に変更します。テストメソッドは [Fact]、[Theory]、またはその他のテスト属性によって識別できます。

最終結果では、変更理由を説明してください。xUnit.net v3 は async void のテストを拒否するため、該当する各メソッドの戻り値を Task に変更したことを伝えてください。 機械的な置換だけを報告しないでください。また、正確なパッケージバージョンを設定済みのフィードからどのように解決したかも記載してください。

Step 7: 属性の破壊的変更に対応する（該当する場合）

xUnit.net v3 では、一部の属性が更新され、2 つの文字列（完全修飾型名とアセンブリ名）の代わりに System.Type を受け取るようになりました。対象となる属性は次のとおりです。

• CollectionBehaviorAttribute
• TestCaseOrdererAttribute
• TestCollectionOrdererAttribute
• TestFrameworkAttribute

たとえば、[assembly: CollectionBehavior("MyNamespace.MyCollectionFactory", "MyAssembly")] は [assembly: CollectionBehavior(typeof(MyNamespace.MyCollectionFactory))] に変換する必要があります。

ステップ 8：FactAttribute または TheoryAttribute を継承している場合（該当する場合）

FactAttribute または TheoryAttribute を継承するカスタム属性がないか確認します。これらのユーザー定義カスタム属性では、ソース情報を提供する必要があります。たとえば、属性が次のようになっている場合：

internal sealed class MyFactAttribute : FactAttribute
{
    public MyFactAttribute()
    {
    }
}

次のように変更する必要があります：

internal sealed class MyFactAttribute : FactAttribute
{
    public MyFactAttribute(
        [CallerFilePath] string? sourceFilePath = null,
        [CallerLineNumber] int sourceLineNumber = -1
    ) : base(sourceFilePath, sourceLineNumber)
    {
    }
}

完了を報告する前に、影響を受ける FactAttribute および TheoryAttribute 派生コンストラクターをすべて読み返してください。各型の名前を挙げ、呼び出し元情報を提供する両方のパラメーターと、それに対応する base(sourceFilePath, sourceLineNumber) への転送があることを確認してください。テストが成功しただけでは、ソース情報が引き継がれたことの証明にはなりません。

ステップ 9：BeforeAfterTestAttribute を継承している場合（該当する場合）

BeforeAfterTestAttribute を継承するカスタム属性がないか確認します。これらのユーザー定義カスタム属性では、メソッドのシグネチャを更新する必要があります。以前は、Before／After のオーバーライドは次のようになっていました：

    public override void Before(MethodInfo methodUnderTest)
    {
        // Possibly some custom logic here
        base.Before(methodUnderTest);
        // Possibly some custom logic here
    }

    public override void After(MethodInfo methodUnderTest)
    {
        // Possibly some custom logic here
        base.After(methodUnderTest);
        // Possibly some custom logic here
    }

次のように変更する必要があります：

    public override void Before(MethodInfo methodUnderTest, IXunitTest test)
    {
        // Possibly some custom logic here
        base.Before(methodUnderTest, test);
        // Possibly some custom logic here
    }

    public override void After(MethodInfo methodUnderTest, IXunitTest test)
    {
        // Possibly some custom logic here
        base.After(methodUnderTest, test);
        // Possibly some custom logic here
    }

BeforeAfterTestAttribute 基底クラスを維持し、オーバーライド修飾子を保持するとともに、既存の基底クラス呼び出しと、カスタムロジックに対する呼び出し順序を保ってください。IBeforeAfterTestAttribute を直接実装すればコンパイルできる場合もありますが、これは v2 から v3 への機械的な移行ではなく、基底クラスの動作を失う可能性があります。

完了を報告する前に、変更後の属性ファイルを読み、実際の Before(MethodInfo, IXunitTest) および After(MethodInfo, IXunitTest) のシグネチャを引用してください。base.Before と base.After の両方に同じ IXunitTest 引数が渡されることを明確に確認してください。オーバーライドを更新したという一般的な説明だけでは、十分な証拠になりません。

ステップ 10：新しい xUnit アナライザー警告に対応する（該当する場合）

xunit.v3 では新しいアナライザー警告が導入されました。特に重要なのは xUnit1051 です（CancellationToken を受け取るメソッドでは TestContext.Current.CancellationToken を使用します）。該当する警告があれば対応してください。

ステップ 11：Xunit.SkippableFact を移行する（該当する場合）

Xunit.SkippableFact へのパッケージ参照がある場合は、これらのパッケージ参照をすべて削除してください。

次に、削除したパッケージ参照に由来する API の使用箇所をなくすため、以下の手順に従ってください。

• SkippableFact 属性を通常の Fact 属性に変更します。
• SkippableTheory 属性を通常の Theory 属性に変更します。
• Skip.If メソッド呼び出しを Assert.SkipWhen に変更します。
• Skip.IfNot メソッド呼び出しを Assert.SkipUnless に変更します。

フィクスチャで可能な場合は、両方の分岐を検証してください。既定の条件では意図したスキップ理由が報告され、有効化された条件ではテストが実行されて成功する必要があります。grep と一般的なテスト実行の成功だけでは、実行時のスキップ動作が維持されたことの証明にはなりません。

この変換は、既存のプロジェクトファイル／中央パッケージファイルと、これらの API を含むソースファイルに限定してください。この関連パッケージの移行だけを目的に、新しい Directory.Build.props を作成しないでください。共有 props ファイルがない場合、必要なランナーのプロパティは既存のテストプロジェクトに設定してください。

ステップ 12：関連パッケージを更新する（該当する場合）

• 各パッケージを個別に解決するのではなく、設定済みのフィードに問い合わせて、相互に互換性のある組み合わせを選んでください。Xunit.Combinatorial 1.x は 2.x 以降に移行し、Xunit.StaFact 1.x は選択した xunit.v3 のメジャーバージョンと互換性のある系列に移行します。
• 製品名やメジャーバージョンが一致していることから、関連パッケージの互換性を推測しないでください。パッケージの依存関係制約と設定済みフィードで利用できるバージョンを確認し、選択した組み合わせをテストの検出によって検証してください。
• Linux／macOS 上で実行可能な出力に切り替えた後、net*-windows プロジェクトをビルドする場合、クロスターゲットを意図しているのであれば EnableWindowsTargeting=true を設定してください。
• テストを実行し、想定されるプラットフォームによるスキップ（Linux 上の STA テストなど）を失敗とは別に確認してください。

ステップ 13：ビルドと検証

ソリューションをビルドし、残っているコンパイルエラーを修正します。dotnet test を実行し、移行前と同じ結果ですべてのテストが成功することを確認します。