migrate-mstest-v1v2-to-v3

MSTest v1/v2 から v3 への移行

MSTest v1（アセンブリ参照）または MSTest v2（NuGet 1.x～2.x）から、MSTest v3 へテストプロジェクトを移行します。MSTest v3 は v1/v2 とバイナリ互換性がありません。v1/v2 に対してコンパイルされたライブラリは、再コンパイルする必要があります。

最初に行うこと

回答する前に、提供されたワークスペースを調べ、v1、v2、v3 への部分移行済み、または v3 への移行完了のいずれかに分類します。最初にウェブを検索したり、記憶だけを頼りに回答したりしないでください。編集の依頼であれば、依頼されたソースの変更と検証まで続けます。アドバイスの依頼であれば、分類後にそのまま回答します。

使用する場合

• プロジェクトが Microsoft.VisualStudio.QualityTools.UnitTestFramework.dll を参照している（MSTest v1）
• プロジェクトが NuGet 1.x または 2.x の MSTest.TestFramework / MSTest.TestAdapter を使用している
• MSTest パッケージを v1/v2 から v3 に更新した後のビルドエラーを解消する場合。パッケージがすでに 3.x でも、ソースや設定の修正が必要な場合を含みます
• .testsettings を .runsettings に置き換える場合
• MSTest.Sdk またはアセンブリ内の並列実行を採用する場合

使用しない場合

• プロジェクトがすでに MSTest v3 を使用しており、移行に関連するビルドエラーも、残っている .testsettings / <LegacySettings> もない（移行が完了している）場合
• v3 から v4 にアップグレードする場合は、migrate-mstest-v3-to-v4 を使用してください
• フレームワーク間（MSTest から xUnit/NUnit）を移行する場合

境界条件の確認

編集を行う前にパッケージのバージョンを確認します。MSTest の参照がすべてすでに 3.x で、v1/v2 から v3 への移行に関するエラーが報告されておらず、.testsettings または <LegacySettings> も残っていない場合は、移行が完了していると伝え、変更は行いません。パッケージのバージョンが 3.x であるだけでは移行完了とは見なされません。v1/v2 時代の設定ファイルや、破壊的変更に関するエラーが残っていれば、引き続き移行の対象です。正常に動作している v3 パッケージをメタパッケージに統合しないでください。検証を依頼された場合に限り、既存のテストを実行します。この条件は以下のすべての手順に優先します。

入力

入力	必須	説明
プロジェクトまたはソリューションのパス	いいえ	エントリーポイントとなる .csproj、.sln、または .slnx。作業ディレクトリ内を検索してください。見つからない場合、または複数のテストプロジェクトがあり対象を特定できない場合にのみ、ユーザーに確認します
ビルドコマンド	いいえ	ビルド方法（例：dotnet build、リポジトリのビルドスクリプト）。指定がない場合は自動検出します
テストコマンド	いいえ	テストの実行方法（例：dotnet test）。指定がない場合は自動検出します

最初にプロジェクトのパスを尋ねてはいけません。 ユーザーがプロジェクトについて文章で説明している場合、それは質問であり、ファイルを隠しているわけではありません。まずディスク上を確認してください。プロジェクトファイルが本当に存在しない場合は、質問だけを返すのではなく、説明されたセットアップに基づいて回答してください。

検索で返されたパスをそのまま開いてください。 検索結果が ./TestProject.csproj なら、そのファイルは作業ディレクトリからの相対パスにあります。スキル自体のベースディレクトリ配下の絶対パスに組み直してはいけません。そのディレクトリにあるのは SKILL.md であり、ユーザーのプロジェクトではないため、読み込みに失敗し、プロジェクトが存在しないように見えてしまいます。見つけたファイルを開けない場合は、組み立てたパスが間違っています。検索結果のパスをそのまま使って再試行してください。検索でプロジェクトファイルが報告されている間は、「ディスク上にプロジェクトがない」と結論付けてはいけません。また、代替策として文章の説明から代わりのプロジェクトを作成してはいけません。

実行時の契約

• スキルを有効化しても、そこで作業を止めないでください。同じタスク内でワークスペースの調査と依頼された作業を続けてください。
• スキルのディレクトリにはガイダンスが含まれており、ステージングされたプロジェクトは含まれていません。現在の作業ディレクトリを検索し、検索で返された文字どおりのパスを開いてください。有効なパスをツールが受け付けない場合は、利用可能な別の読み取りツールまたは編集ツールを試してください。
• glob 検索またはディレクトリ検索で見つけられる間は、パスを尋ねないでください。現在のワークスペースを網羅的に検索してもプロジェクトが見つからない場合、または複数のプロジェクトがあり対象を特定できない場合に限り、尋ねてください。
• 単独の動詞ではなく、依頼されている成果物を判断してください。「編集してください」「このプロジェクトを更新してください」「その後ビルドして実行してください」は作業の実行を意味します。「何を変更する必要がありますか？」「何を想定すべきですか？」「手順は同じですか？」「見せてください」は、プロンプトにアップグレードや移行の記述があっても、回答を意味します。
• ファイルを変更した後は、検出した MSTest のバージョンとランナー、変更したすべてのファイル、修正した呼び出しや設定を正確に示してください（たとえば、AreEqual<object>、AreNotEqual<object>、AreSame<object> に変更した各アサーションを列挙してください）。クリーンなテスト件数を報告してください。プロジェクトで確認できる根拠がない限り、VSTest の維持、ビルドの実施、テストの合格を主張しないでください。

破壊的変更の概要

MSTest v3 では、v1/v2 から次の破壊的変更が導入されています。プロジェクトに関係するものだけ対処してください。

破壊的変更	影響	修正
Assert.AreEqual(object, object) オーバーロードが削除され、AreEqual<T>(T?, T?) のみが残りました	2 つの引数に共通の推論型がない場合に限り、CS0411（型引数を推論できない）または CS1503 が発生します。object 型の引数が 2 つの場合は T = object と推論されるため、そのままコンパイルできます	エラーが発生する呼び出しに明示的な型引数を追加します：Assert.AreEqual<object>(expected, actual)。AreNotEqual、AreSame、AreNotSame も同様です。すでにコンパイルできるアサーションはそのままにしてください
DataRow の型の厳密な一致	コンパイルエラーではありません。 アナライザー警告 MSTEST0014 が出てビルドされますが、実行時に「Test data doesn't match method parameters」で失敗します。拡大変換（int -> long）は引き続きバインドされますが、縮小変換や無関係な型（1L -> int、1.0 -> float）はバインドされません	リテラルを正確なパラメーター型に変更します：int には 1、long には 1L、float には 1.0f を指定します。テストを実行してください。ビルドが成功しても、問題がないとは限りません
DataRow の引数数が 16 個に制限されます — 3.0.1 と 3.0.2 のみ	これら 2 つのバージョンでは CS1729 が発生します。この制限は 3.0.3 で再び撤廃されました	3.0.3 以降（現在の 3.x はすべて）では、引数が多い行も有効です — そのままにしてください。余分な引数を配列でラップしたり、object にキャストしたり、テストを分割したりしないでください。3.0.1/3.0.2 に固定されているプロジェクトのみ対応が必要です：3.0.3 以降に更新してください
.testsettings / <LegacySettings> はサポートされなくなりました	設定が無視されます	.testsettings を削除し、同等の設定を含む .runsettings を作成します
.NET Core / Framework 間でタイムアウトの動作が統一されました	[Timeout] を使うテストの動作が変わることがあります	タイムアウト値を確認し、必要に応じて調整します
対象フレームワークの廃止：.NET 5、.NET Fx < 4.6.2、netstandard1.0、UWP < 16299、WinUI < 18362	ビルドエラー	TFM を更新します：.NET 5 は net8.0（LTS）または net6.0 以降、netfx は net462 以降、netstandard1.0 は netstandard2.0 に変更します。注：net6.0、net8.0、net9.0 はすべてサポートされています
v1/v2 とのバイナリ互換性はありません	v1/v2 に対してコンパイルされたライブラリは再コンパイルが必要です	すべての依存関係を v3 に対して再コンパイルします
テスト ID の生成方法が変更されました	テスト ID をキーとするプレイリスト、フィルター、CI の履歴がリセットされる可能性があります	ID を再ベースライン化し、影響を受けるフィルターを確認します
TargetInvocationException がラップ解除されます	ラッパー例外を想定しているテストやインフラストラクチャでは、内部例外が認識されます	基になる例外を想定するよう、例外処理を更新します
初期化／クリーンアップのメッセージがテスト結果に含まれるようになりました	これまで表示されていなかったライフサイクルメッセージが、最初または最後のテスト出力に追加される場合があります	ログ処理を更新し、最初と最後のテスト結果を確認します
配置ディレクトリの動作が TFM 間で統一されました	配置パスをハードコードしているテストは失敗する場合があります	固定のパスを想定せず、TestContext.DeploymentDirectory または配置済みアイテムのパスを使用します
Nullable 注釈が追加されました	Nullable が有効なプロジェクトでは警告が増える場合があります	無関係な診断を抑制せずに、警告を修正します

回答のガイドライン

• 必ず最初に現在のバージョンを特定する：移行手順を推奨する前に、プロジェクトで検出された現在の MSTest バージョンを明示します（例：「このプロジェクトでは MSTest v2（2.2.10）を使用しています」または「このプロジェクトは QualityTools アセンブリ参照を使用する MSTest v1 プロジェクトです」）。これにより移行に関するアドバイスの根拠が明確になり、プロジェクトファイルを確認したことも伝わります。
• プロジェクトの根拠を確認する。ただし、その確認は自分で行う：表現だけから v1/v2 を推測せず、プロジェクトファイルまたは中央パッケージファイルを読み、移行元が QualityTools/v1、NuGet 1.x、NuGet 2.x のいずれかを判定します。ユーザーに尋ねるのではなく、作業ディレクトリから根拠を集めます。プロジェクトがすでに v3 以降で、v1/v2 の残存要素がなければ、そこで作業を止め、適切なスキルに案内します。
• テストプラットフォームを維持する：ユーザーからランナーの移行を別途依頼されない限り、フレームワークのアップグレード中も VSTest または MTP を変更しないでください。
• 移行を最後まで実行する：ユーザーからプロジェクトの移行またはアップグレードを依頼された場合は、ファイルを編集し、ビルドしてテストを実行します。重大な変更点を列挙するだけで終わらせないでください。アドバイスのみの回答が適切なのは、ユーザーが変更後の見通しを尋ねている場合だけです。
• 特定の修正依頼（アップグレード後にユーザーから具体的なコンパイルエラーが示された場合）：上の表にある、該当する重大な変更だけに対処します。簡潔な修正前／修正後を示してください。移行の全手順を説明しないでください。
• DataRow の修正依頼：提示された DataRow とメソッドシグネチャを一つずつ比較します。不一致があっても MSTEST0014 が出るだけでビルドでき、テスト実行時に失敗する場合があります。メソッドの契約を維持し、通常はリテラルを修正します（int に対する 1L を 1 にするなど）。その後、該当するテストを実行します。実際に誤っている行だけを変更してください。 3.0.3 以降では、引数の数はそれ自体で不具合とはみなされないため、コンパイラーが拒否しない限り、引数の多い行はそのままにします。
• 疑わしいだけで変更しない。まずエラーを確認する：構文がサポートされていないと考えた場合は、編集する前にビルドし、実際の診断を確認します。コンパイルできるなら、このバージョンではその構文がサポートされているため、変更は不要です。プロジェクトに該当しない制限を避けるために有効なコードを書き換えるのは、慎重さではなく不具合です。
• 特定機能の移行（.testsettings、DataRow、アサーションなど、ユーザーが一つの項目について尋ねている場合）：その機能だけに対処します。ただし、提示されたファイル内の有効な設定または影響を受ける使用箇所はすべて扱います。.testsettings の場合は、MSTest の設定をすべて一つの <MSTest> 要素にまとめ、要求されたデプロイ、テストごとのタイムアウト、データコレクター、その他の有効な構成を対応付けます。セッション全体に適用されるタイムアウトは追加しないでください。無関係な重大な変更について説明しないでください。
• 「変更後の見通し」に関する質問（アップグレード前に重大な変更について尋ねられた場合）：まず v3 に到達するために必要な具体的なパッケージ更新を示し、次に Breaking Changes Summary のすべてのカテゴリを要約して、表示されているプロジェクトに直接適用されるものを明示します。各項目は一行に収め、リリースノートの履歴には踏み込まないでください。
• 「変更後の見通し」に関する回答の必須形式：表示されているプロジェクトに基づく Applies / Watch / No change の表を使用し、Breaking Changes Summary のすべての行を網羅します。このスキルの価値は網羅性にあります。簡潔にするために、実行時のみ影響するカテゴリを省略しないでください。
• 移行全体の依頼（完全な移行を求められた場合）：以下の完全なワークフローに従います。
• 比較に関する質問（v1 と v2 の違いを尋ねられた場合）：簡潔に説明します。v1 はアセンブリ参照を使用するため、まずそれらを削除する必要があります。v2 は NuGet を使用するため、バージョンを上げるだけで済みます。どちらも同じ v3 パッケージと重大な変更に収束します。
• 実行内容はプロジェクト固有に保つ：修正や移行全体の依頼では、表示されているコードや構成に見つかったパターンだけを変更します。より広範な内容を扱うのは、明示的に「変更後に何が予想されるか」と尋ねられた場合に限ります。

移行パス

• MSTest v1（QualityTools へのアセンブリ参照）：アセンブリ参照を削除し（ステップ 2）、v3 NuGet パッケージを追加し（ステップ 3）、破壊的変更に対応します（ステップ 5）。
• MSTest v2（NuGet パッケージ 1.x～2.x）：パッケージのバージョンを 3.x に更新し（ステップ 3）、破壊的変更に対応します（ステップ 5）。アセンブリ参照の削除は不要です。

どちらのパスもステップ 3 で合流します。開始時のバージョンにかかわらず、同じ v3 パッケージと破壊的変更が適用されます。

ワークフロー

ステップ 1：プロジェクトを評価する

1. まずプロジェクトの場所を特定します。作業ディレクトリ内で *.csproj、*.sln、 *.slnx、Directory.Build.props、Directory.Packages.props、および *.testsettings を glob で検索します。ユーザーに何かを尋ねる前にこれを行い、見つかった ファイルは、報告されたパスとまったく同じパスで開きます（「入力」の下の注記を参照）。
2. 1 回の調査で、プロジェクトファイルと中央構成ファイルをまとめて読み取り、影響を受ける API／設定を検索し、現在使用されている MSTest のバージョンを特定します。
   • アセンブリ参照：プロジェクト参照で Microsoft.VisualStudio.QualityTools.UnitTestFramework を検索します -> MSTest v1
   • NuGet パッケージ：MSTest.TestFramework と MSTest.TestAdapter のパッケージバージョンを確認します -> 1.x の場合は v1、2.x の場合は v2
3. 対象のフレームワークが v3 でサポート対象外になっていないか確認します（ステップ 4 を参照）。
4. 既存のテストコマンドを実行します。検出数、成功数、失敗数、スキップ数を記録し、移行前の比較基準にします。

ステップ 2：v1 のアセンブリ参照を削除する（該当する場合）

プロジェクトがアセンブリ参照経由で MSTest v1 を使用している場合：

1. Microsoft.VisualStudio.QualityTools.UnitTestFramework.dll への参照を削除します
   • SDK スタイルのプロジェクトでは、.csproj から <Reference> 要素を削除します
   • 非 SDK スタイルのプロジェクトでは、Visual Studio のソリューション エクスプローラーで「参照」を右クリックし、「削除」を選択します
2. プロジェクトファイルを保存します

ステップ 3：パッケージを MSTest v3 に更新する

パッケージのモデルは 1 つだけ使用し、重複したフレームワーク／アダプター参照を残さないでください。

デフォルト -- MSTest メタパッケージをインストールする：

個別の MSTest.TestFramework と MSTest.TestAdapter パッケージ参照を削除し、統合された MSTest メタパッケージに置き換えます：

<PackageReference Include="MSTest" Version="3.8.0" />

プロジェクトが VSTest を引き続き使用する場合は Microsoft.NET.Test.Sdk を残しますが、選択した MSTest リリースと互換性のあるバージョンに更新します。たとえば、MSTest 3.8.0 では Microsoft.NET.Test.Sdk 17.13.0 以降が必要です。古いバージョンを明示的に指定したままにすると、NU1605 が発生します。パッケージバージョンを中央で管理している場合は、インラインバージョンを追加するのではなく、Directory.Packages.props を更新します。

ユーザーからの要望がある場合、またはリポジトリですでに標準として採用されている場合に限り、MSTest.Sdk を使用します（SDK スタイルのプロジェクトのみ）：

<Project Sdk="Microsoft.NET.Sdk"> を <Project Sdk="MSTest.Sdk/3.8.0"> に変更します。MSTest.Sdk は MSTest フレームワーク、アダプター、アナライザーを自動的に提供します。

重要：MSTest.Sdk のデフォルトは Microsoft.Testing.Platform（MTP）です。 プロジェクト自体で VSTest を引き続き使用する必要がある場合は、 <UseVSTest>true</UseVSTest> を設定します。MSTest.Sdk v3 は MTP モードで Microsoft.NET.Test.Sdk も提供するため、移行期間中に vstest.console を呼び出すだけで、メインのランナーを変更する必要はありません。 フレームワークのアップグレードに伴う副次的な変更として、ランナーを切り替えないでください。

MSTest.Sdk に切り替える場合は、以下を削除します（SDK が自動的に提供します）：

• パッケージ：MSTest、MSTest.TestFramework、MSTest.TestAdapter、MSTest.Analyzers、Microsoft.NET.Test.Sdk
• プロパティ：<EnableMSTestRunner>、<OutputType>Exe</OutputType>、<IsPackable>false</IsPackable>、<IsTestProject>true</IsTestProject>

手順 4：必要に応じてターゲットフレームワークを更新する

MSTest v3 は、.NET 6 以降、.NET Core 3.1、.NET Framework 4.6.2 以降、.NET Standard 2.0、UWP 16299 以降、WinUI 18362 以降をサポートしています。.NET Core 3.1 はサポート終了となっていますが、MSTest v3 では引き続きサポートされます。このフレームワークのみの移行ではそのまま維持し、ランタイムのアップグレードは別途行うことを推奨します。プロジェクトが MSTest v3 でサポートされなくなったフレームワークバージョンをターゲットにしている場合は、サポート対象のものに更新してください。

削除されたフレームワーク	推奨される移行先
.NET 5	.NET 8.0（現在の LTS）または .NET 6 以降
.NET Framework < 4.6.2	.NET Framework 4.6.2
.NET Standard 1.0	.NET Standard 2.0
UWP < 16299	UWP 16299
WinUI < 18362	WinUI 18362

注：.NET 6、.NET 8、.NET 9 はすべて MSTest v3 でサポートされています。すでにサポートされている TFM は変更しないでください。

手順 5：ビルドエラーと破壊的変更を解決する

まず提供されたファイルを検索し、実際に存在する破壊的変更だけを修正してください。 ビルドが成功しても互換性があるとは限りません。一部の問題はアナライザーの警告や テスト実行時にのみ表面化します。

アサーションのオーバーロード -- MSTest v3 では、Assert.AreEqual(object, object) と AreNotEqual(object, object) が、ジェネリックな AreEqual<T>(T?, T?) に置き換えられました。これは、T を推論できなくなった場合に限り問題となり、コンパイラーは CS0411（または、引数の型が無関係な場合は CS1503）を報告します。

// Breaks -- string and int have no common inferred type:
Assert.AreEqual(referenceCode, numericId);   // CS0411
// Fix -- name the type argument explicitly:
Assert.AreEqual<object>(referenceCode, numericId);

object 型の引数が 2 つある場合も T = object と推論されるため、変更せずにコンパイルできます。また、Assert.AreEqual("A-3", order.Reference) のような通常の型付きアサーションもそのままコンパイルできます。**コンパイラーが拒否する呼び出し箇所だけを修正してください。**ファイル内のすべてのアサーションを <object> に拡張してもコンパイルはできます。そのため、問題は検出されませんが、v3 で追加された型チェックが失われます。これこそが、この変更の目的です。

DataRow の厳密な型一致 -- 引数の型はパラメーターの型と完全に一致する必要があります。これはコンパイルエラーではありません。行はビルドされ（MSTEST0014 が発生します）、実行時に「Test data doesn't match method parameters」というエラーで失敗します。

// Fails at run time: 1L (long) does not bind to an int parameter -> use 1
// Fails at run time: 1.0 (double) does not bind to a float parameter -> use 1.0f
// Still binds: 1 (int) to a long parameter -- widening conversions are accepted

独立した理由で誤りと判断できる場合を除き、メソッドのパラメーター型は維持してください。dotnet build は MSTEST0014 が発生していても成功する場合があります。各行がバインドされ実行されることを確認するため、テストを実行してください。

引数が 16 個を超える行 -- コンパイラーが実際に CS1729 を出力しない限り、そのままにしてください。上限があったのは 3.0.1／3.0.2 のみで（3.0.3 で撤廃）、余分な引数を object[] でラップしたり、object にキャストしたり、メソッドを分割したりするのは、正しいテストを書き換えるだけです。

タイムアウトの動作 -- .NET Core と .NET Framework で統一されています。[Timeout] の値が引き続き機能することを確認してください。

手順 6：.testsettings を .runsettings に置き換える

.testsettings ファイルと <LegacySettings> は MSTest v3 ではサポートされなくなりました。.testsettings ファイルを削除し、.runsettings ファイルを作成してください。両方を残さないでください。MSTest の設定はすべて 1 つの <MSTest> 要素にまとめ、<MSTestV2> セクションは作成しないでください。

主な対応関係：

.testsettings	.runsettings での対応
TestTimeout プロパティ	<MSTest><TestTimeout>30000</TestTimeout></MSTest>
デプロイ構成	<MSTest><DeploymentEnabled>true</DeploymentEnabled></MSTest> または削除
アセンブリ解決設定	削除 -- 最新の .NET では不要
データコレクター	<DataCollectionRunSettings><DataCollectors> セクション

重要：タイムアウトは <TestSessionTimeout>（セッション全体）ではなく、<MSTest><TestTimeout>（テストごと）に設定してください。<LegacySettings> はすべて削除してください。

古い .testsettings のパスを明示的に選択しているすべてのプロジェクト、CI コマンド、IDE 設定を、新しい .runsettings のパスを選択するように更新してください。VSTest プロジェクトで動作を維持する必要があり、従来のファイルが選択されていなかった場合は、RunSettingsFilePath を使って新しいファイルを有効にしてください。MTP では、VSTest の MSBuild プロパティが適用されると想定せず、フレームワークでサポートされている --settings パスまたは既存の MTP 設定を使用してください。

ステップ 7：検証

1. ベースラインで使用したものと同じテストコマンド、フィルター、構成を実行します。dotnet test は既定でビルドするため、コンパイルエラーを切り分ける場合にのみ、別途ビルドを実行します。
2. 検出数、成功数、失敗数、スキップ数を移行前のベースラインと比較します。
3. すべての件数の差異を調査します。テストやデータ行が気付かないうちに削除されている状態は許容しないでください。
4. QualityTools の参照、1.x／2.x の MSTest パッケージ、.testsettings、<LegacySettings> が残っていないことを確認します。

検証

• MSTest v3 パッケージ（または MSTest.Sdk）が正しく参照され、v1／v2 の参照が削除されている
• プロジェクトがエラーなしでビルドできる
• すべてのテストが成功する（dotnet test）。成功数／失敗数を移行前のベースラインと比較する
• .testsettings が .runsettings に置き換えられている（該当する場合）

次のステップ

v3 への移行後、MSTest v4 には migrate-mstest-v3-to-v4 を使用します。

よくある落とし穴

落とし穴	解決策
ワークスペースにすでにプロジェクトがあるのに「どのプロジェクトですか？」と返信する	*.csproj／*.sln／*.slnx を Glob で検索し、見つかったファイルを読み取ります
プロジェクトファイルが検索結果に表示された直後に「ディスク上にプロジェクトがありません」と判断する	パスがスキルのベースディレクトリ配下で再構成されています。検索結果に表示されたパスをそのまま使って再度開きます。代わりのプロジェクトを作成しないでください
16 個を超える引数を持つ DataRow を書き換える	3.0.3 以降では有効で、現行の 3.x はすべて該当します。拒否されていたのは 3.0.1／3.0.2 のみです
MSTest.Sdk 以外の VSTest プロジェクトに Microsoft.NET.Test.Sdk がない	VSTest による検出のため、パッケージ参照を追加します
MSTest.Sdk v3 プロジェクトで、VSTest をプライマリランナーとして使用する必要がある	<UseVSTest>true</UseVSTest> を設定します。一時的な vstest.console ジョブがあるという理由だけで、ランナーを切り替えないでください