Dart テストを Package Checks に移行する

目次

• 依存関係の管理
• 構文移行ガイドライン
• Dart MCP ツールの活用
• 移行ワークフロー
• 例

依存関係の管理

Dart Tooling MCP Server の pub ツールまたは標準 CLI コマンドを使用して依存関係を管理します。

• dart pub add dev:checks を使用して package:checks を dev_dependency として追加します。
• pubspec.yaml で明示的にリストされている場合は package:matcher を削除します（注：package:test によって推移的に含まれることが多いため、その場合は問題ありません）。
• 移行対象のすべてのテストファイルで package:checks/checks.dart をインポートします。

構文移行ガイドライン

テストアサーションを package:matcher 構文から package:checks が提供する自然な API に移行します。

• 基本的な等価性比較: expect(actual, equals(expected)) または expect(actual, expected) を check(actual).equals(expected) に置き換えます。
• 型チェック: expect(actual, isA<Type>()) を check(actual).isA<Type>() に置き換えます。
• プロパティ抽出: expect(actual.property, expected) を check(actual).has((a) => a.property, 'property name').equals(expected) に置き換えます。
• 複数チェックのカスケード: Dart のカスケード演算子（..）を使用して、単一の対象に対する複数の期待値をチェーンします。
• 非同期期待値:
  • Future をチェックする場合は、check 呼び出しを await します：await check(someFuture).completes((r) => r.equals(expected));。
  • Stream をチェックする場合は、StreamQueue でラップして複数回のチェックを行うか、単一/ブロードキャストチェックの場合は .withQueue を使用します。

Dart MCP ツールの活用

Dart MCP Server ツールを活用して、移行プロセスを自動化し検証します。

• pub を使用して dart pub get または dart pub add を実行します。
• analyze_files を使用して、プロジェクトまたは特定パスで静的解析を実行します。
• run_tests を使用して、Dart または Flutter テストをエージェント中心の UX で実行します。dart test などのシェルコマンドの代わりに、常にこれを使用してください。
• dart_fix を使用して、該当する場合は自動修正を適用します。

移行ワークフロー

テストスイートを移行する際の進捗状況を追跡するために、以下のチェックリストをコピーして使用します。

• タスク進捗
  • package:checks を dev dependency として追加します。
  • package:matcher を使用しているすべてのテストファイル（expect 呼び出し）を特定します。
  • ターゲットテストファイルで package:checks/checks.dart をインポートします。
  • すべての expect(...) ステートメントを check(...) ステートメントに書き直します。
  • 静的解析機を実行します（analyze_files）。
  • テストを実行します（run_tests）。

フィードバックループ：静的解析

1. 修正されたテストディレクトリで analyze_files ツールを実行します。
2. 静的解析の警告またはエラー（例：インポートの欠落、isA の不正なジェネリック型、待機されていない Future）をレビューします。
3. 警告を修正します。
4. アナライザーが 0 個の問題を返すまで繰り返します。

フィードバックループ：テスト検証

1. run_tests ツールを実行します。
2. テストが失敗した場合は、失敗出力をレビューします。package:checks は詳細なコンテキストを提供します（例：Which: has length of <2>）。
3. check() の期待値または基になるコードを調整して失敗を解決します。
4. すべてのテストがパスするまで繰り返します。

例

基本的なアサーション

入力（matcher）:

expect(someList.length, 1);
expect(someString, startsWith('a'));
expect(someObject, isA<Map>());

出力（checks）:

check(someList).length.equals(1);
check(someString).startsWith('a');
check(someObject).isA<Map>();

合成期待値

入力（matcher）:

expect('foo,bar,baz', allOf([
  contains('foo'),
  isNot(startsWith('bar')),
  endsWith('baz')
]));

出力（checks）:

check('foo,bar,baz')
  ..contains('foo')
  ..not((s) => s.startsWith('bar'))
  ..endsWith('baz');

非同期 Future

入力（matcher）:

expect(Future.value(10), completion(equals(10)));
expect(Future.error('oh no'), throwsA(equals('oh no')));

出力（checks）:

await check(Future.value(10)).completes((it) => it.equals(10));
await check(Future.error('oh no')).throws<String>().equals('oh no');

非同期 Stream

入力（matcher）:

var stdout = StreamQueue(Stream.fromIterable(['Ready', 'Go']));
await expectLater(stdout, emitsThrough('Ready'));

出力（checks）:

var stdout = StreamQueue(Stream.fromIterable(['Ready', 'Go']));
await check(stdout).emitsThrough((it) => it.equals('Ready'));