matcher-to-checks

When to use this skill

In a Dart or Flutter project. When a user asks to migrate to package:checks or just “checks”.

The Workflow

1. Analysis:
   • Use grep to identify files using expect or package:matcher.
   • Review custom matchers; these may require manual migration.
2. Tools & Dependencies:
   • Ensure dev_dependencies includes checks.
   • Run dart pub add --dev checks if missing.
3. Discovery:
   • Use the Strategies for Discovery below to find candidates.
4. Replacement:
   • Add import 'package:checks/checks.dart';.
   • Apply the Common Patterns below.
   • Final Step: Replace import 'package:test/test.dart'; with import 'package:test/scaffolding.dart'; ONLY after all expect calls are replaced. This ensures incremental progress.
5. Verification:
   • Ensure the code analyzes cleanly.
   • Ensure tests pass.
   • Prefer using the Dart MCP server (vs the dart command line) if available.

Strategies for Discovery

Use these commands to find migration candidates:

• Find usages of expect: grep -r "expect(" test/
• Find usages of expectLater: grep -r "expectLater(" test/
• Find specific matchers (e.g. isTrue): grep -r "isTrue" test/

Common Patterns

Async & Futures (CRITICAL)

• Checking async functions: check(() => asyncFunc()).throws<T>() causes FALSE POSITIVES because the closure returns a Future, which is a value, so it “completes normally” (as a Future). Correct Usage:

  await check(asyncFunc()).throws<T>();
  

• Chaining on void returns: Many async check methods (like throws) return Future<void>. You cannot chain directly on them. Use cascades or callbacks. Wrong:

  await check(future).throws<Error>().has((e) => e.message, 'message').equals('foo');
  

  Correct:

  await check(future).throws<Error>((it) => it.has((e) => e.message, 'message').equals('foo'));
  

Complex Examples:

Deep Verification with isA and having:

Legacy:

expect(() => foo(), throwsA(isA<ArgumentError>()
    .having((e) => e.message, 'message', contains('MSG'))));

Modern:

check(() => foo())
    .throws<ArgumentError>()
    .has((e) => e.message, 'message')
    .contains('MSG');

Every Element:

Legacy:

expect(list, everyElement(isA<int>().having((e) => e.isEven, 'isEven', isTrue)));

Modern:

check(list).every((e) => e.isA<int>()
    .has((v) => v.isEven, 'isEven').isTrue());

Property Extraction:

Legacy:

expect(obj.prop, equals(value)); // When checking multiple props

Modern:

check(obj)
  ..has((e) => e.prop, 'prop').equals(value)
  ..has((e) => e.other, 'other').equals(otherValue);

One-line Cascades: Since checks often return void, use cascades for multiple assertions on the same subject.

check(it)..isGreaterThan(10)..isLessThan(20);

Constraints

• Scope: Only modify files in test/ (and pubspec.yaml).
• Correctness: One failing test is unacceptable. If a test fails after migration and you cannot fix it immediately, REVERT that specific change.
• Type Safety: package:checks is stricter about types than matcher. You may need to add explicit as T casts or isA<T>() checks in the chain.