dart-migrate-to-checks-package

Migrating Dart Tests to Package Checks

Use this skill when you need to migrate a Dart test suite from the legacy package:matcher (which is exported by default from package:test/test.dart) to the modern, type-safe, and literate package:checks assertion library.

Contents

• When to Use This Skill
• How to Use This Skill (The Workflow)
• Key Syntax Differences and Pitfalls
• Matcher-to-Checks Mapping Table
• Matchers with No Direct Replacements
• Strategies for Discovery
• Examples

---

When to Use This Skill

• When asked to "migrate tests to checks", "use package:checks", or "modernize test assertions".
• When updating legacy test suites where static type safety, better autocomplete in IDEs, and highly detailed failure diagnostics are desired.

---

How to Use This Skill (The Workflow)

Follow this structured workflow to safely and systematically migrate a test suite:

1. Dependency Setup

• Add package:checks as a dev_dependency in pubspec.yaml:

  dart pub add dev:checks
  

• Remove package:matcher if it is explicitly listed under dev_dependencies (it is typically transitively included by package:test, which is fine).

2. Identify and Plan Target Files

• Use the grep patterns in Strategies for Discovery to locate all test files containing legacy expect or expectLater calls.
• Decide whether to migrate files fully or incrementally.

3. Migrating a File (Incremental or Full)

For any target test file:

1. Update Imports:
   • Replace the generic import 'package:test/test.dart'; with:

     import 'package:test/scaffolding.dart';
     import 'package:checks/checks.dart';
     

   • For Incremental Migration: If you only want to migrate some test cases in the file, or want to migrate one step at a time, add:

     import 'package:test/expect.dart'; // Temporarily allows legacy expect()
     

2. Translate Assertions: Rewrite legacy expect and expectLater calls to check syntax following the Key Syntax Differences and Pitfalls and the Matcher-to-Checks Mapping Table.
3. Verify via Compiler: If migrating fully, remove the import 'package:test/expect.dart'; line. Any remaining un-migrated expect calls will immediately surface as compiler errors, making them easy to find and fix.

4. Verification and Feedback Loops

• Static Analysis: Run static analysis on the target package:

  dart analyze
  

  Pay close attention to generic type parameters on .isA<Type>() and ensure asynchronous expectations are properly awaited (check for unawaited_futures warnings).
• Run Tests: Execute the tests to verify both behavior and correct assertion runtime logic:

  dart test
  

  If a test fails, review the extremely detailed failure output of package:checks to diagnose if the test is genuinely failing or if the expectation was translated incorrectly.

---

Key Syntax Differences and Pitfalls

[!IMPORTANT] A line-for-line translation can sometimes introduce subtle bugs or false passes. Always review these key differences carefully:

1. Collection Equality Pitfall (equals vs deepEquals)

• Legacy Matcher: expect(actual, expected) or expect(actual, equals(expected)) performed a deep equality check if the arguments were collections (Lists, Maps, Sets).
• Package Checks: .equals(expected) corresponds strictly to operator ==. Since Dart collections do not override operator == for element-wise comparison, using .equals on a collection will check for identity and almost certainly fail at runtime.
• Remediation: You must replace collection equality assertions with .deepEquals(expected).

  // BEFORE (Matcher)
  expect(myList, [1, 2, 3]);
  
  // AFTER (Checks)
  check(myList).deepEquals([1, 2, 3]);
  

2. The reason Parameter is now because

• Legacy Matcher: The explanation was passed as a trailing named argument reason to expect:

  expect(actual, expectation, reason: 'Explanation');
  

• Package Checks: The explanation is passed as the named argument because to the check function before the actual subject:

  check(because: 'Explanation', actual).expectation();
  

3. Regular Expression Matching (matches vs matchesPattern)

• Legacy Matcher: The matches(pattern) matcher automatically converted a String argument into a RegExp (e.g., matches(r'\d') matched '1').
• Package Checks: .matchesPattern(pattern) treats a String argument as a literal string pattern.
• Remediation: To match using a regular expression, you must explicitly pass a RegExp object:

  // BEFORE (Matcher)
  expect(someString, matches(r'\d+'));
  
  // AFTER (Checks)
  check(someString).matchesPattern(RegExp(r'\d+'));
  

4. Property Extraction (TypeMatcher.having vs .has)

• Legacy Matcher: Chained field/property expectations used TypeMatcher.having(feature, description, matcher):

  expect(actual, isA<Person>().having((p) => p.name, 'name', startsWith('A')));
  

• Package Checks: The .has(feature, description) extension is available on all Subjects, takes one fewer argument, and returns a new Subject representing that property. You chain expectations directly off it:

  check(actual).isA<Person>().has((p) => p.name, 'name').startsWith('A');
  

5. Synchronous vs. Asynchronous throws

• Legacy Matcher: In package:matcher, throwsA behaved similarly for both synchronous closures and asynchronous futures when wrapped in expect or expectLater.
• Package Checks: The .throws<E>() expectation behaves differently and has different return types depending on whether the subject is synchronous or asynchronous:
  • Synchronous (Subject<T Function()>): .throws<E>() returns a Subject<E> synchronously. This does not accept a callback argument! You chain or cascade expectations directly off the returned Subject<E>:

    // YES (Synchronous chaining)
    check(() => triggerSyncError()).throws<ArgumentError>()
      ..has((e) => e.message, 'message').equals('invalid input');
    
    // NO (Passing a callback to sync throws will cause a compiler error!)
    check(() => triggerSync").throws<ArgumentError>((it) => ...); // ERROR!
    

  • Asynchronous (Subject<Future<T>>): .throws<E>() returns Future<void>. Because you cannot chain directly off a Future<void>, this requires an inspection callback:

    // YES (Asynchronous callback)
    await check(triggerAsyncError()).throws<ArgumentError>((it) => it
      ..has((e) => e.message, 'message').equals('invalid input'));
    

  • Crucial Pitfall: Trying to chain expectations directly after an awaited asynchronous .throws<E>() (e.g., await check(future).throws<E>().equals(...)) will fail to compile because it returns Future<void>.

6. RegExp / Pattern Equality

• Legacy Matcher: In package:matcher, expect(myPattern, equals(RegExp('Hello'))) worked because the matcher comparison rules handled RegExp instances.
• Package Checks: .equals() uses strict Dart == equality. Since separate RegExp instances do not satisfy ==, using .equals() will fail at runtime.
• Remediation: Use .isA<RegExp>() type refinement along with cascades to assert on the properties of the RegExp object explicitly:

  check(myPattern).isA<RegExp>()
    ..has((r) => r.pattern, 'pattern').equals('Hello')
    ..has((r) => r.isMultiLine, 'isMultiLine').isTrue();
  

7. Strict Nullable Boolean Safety (bool? fields)

• Legacy Matcher: Statically, isTrue and isFalse performed loose dynamic checks at runtime, which silently accepted nullable booleans (bool?).
• Package Checks: .isTrue() and .isFalse() are defined strictly on Subject<bool> (non-nullable). They are not available on Subject<bool?>.
• Remediation: For fields declared as bool?, you must either refine the subject (e.g., .isNotNull().isTrue()) or simply use .equals(true) and .equals(false) which are generic and work on all types:

  // If options.flagOutdated is a bool?
  check(options.flagOutdated).equals(true);
  check(options.flagOutdated).equals(false);
  

8. Map Key Containment (containsKey vs contains)

• Legacy Matcher: In package:matcher, contains(key) was used to assert that a Map contained a specific key.
• Package Checks: Calling .contains(...) on a Subject<Map> is not defined and will fail compilation.
• Remediation: Use the map-specific .containsKey(key) matcher instead:

  // BEFORE (Matcher)
  expect(myMap, contains('my_key'));
  
  // AFTER (Checks)
  check(myMap).containsKey('my_key');
  

9. Explicit Generic Parameters for Extension Types

• Legacy Matcher: expect(extensionTypeConst, 3) compiled because of loose dynamic equality.
• Package Checks: If QrEciValue is an extension type representation of int (e.g., extension type const QrEciValue(int value) implements int), calling .equals(3) on a Subject<QrEciValue> fails because 3 (an int) is not assignable to QrEciValue. Casting with as int will trigger an "Unnecessary cast" static analysis warning because QrEciValue statically implements int.
• Remediation: Explicitly specify the generic type parameter on the check function to force checks to treat it as the primitive type:

  // YES (Type-safe and warning-free)
  check<int>(QrEciValue.iso8859_1).equals(3);
  

10. Dynamic Map / JSON Lookup Casting

• Legacy Matcher: Loose dynamic typing allowed comparing nested json lookups statically typed as dynamic directly against lists or maps.
• Package Checks: Strict type safety rejects the implicit assignment of dynamic to Iterable<Object?> in .deepEquals(...).
• Remediation: Statically cast the dynamic lookup result to a List or Map:

  // YES (Explicit cast to List)
  check(myIterable).deepEquals(json['data']['items'] as List);
  

---

Matcher-to-Checks Mapping Table

Use this table as a quick reference for direct matcher replacements:

Legacy Matcher	Package Checks Equivalent	Notes
expect(actual, expected)	check(actual).equals(expected)	Use .deepEquals for collections!
expect(actual, equals(expected))	check(actual).equals(expected)	Use .deepEquals for collections!
isA<T>()	check(actual).isA<T>()	Chaining is supported directly
same(expected)	check(actual).identicalTo(expected)	Verifies identity
anyElement(matcher)	check(iterable).any(conditionCallback)	E.g. check(list).any((e) => e.equals(1))
everyElement(matcher)	check(iterable).every(conditionCallback)	E.g. check(list).every((e) => e.isGreaterThan(0))
hasLength(expected)	check(actual).length.equals(expected)	Works on String, Map, Iterable, etc.
isNot(matcher)	check(actual).not(conditionCallback)	E.g. check(val).not((it) => it.equals(5))
contains(element)	check(actual).contains(element)	Works on String, Iterable (use containsKey for Map!)
contains(key) (on a Map)	check(map).containsKey(key)	Map key containment
startsWith(prefix)	check(string).startsWith(prefix)	String only
endsWith(suffix)	check(string).endsWith(suffix)	String only
isEmpty	check(actual).isEmpty()	Works on String, Map, Iterable
isNotEmpty	check(actual).isNotEmpty()	Works on String, Map, Iterable
isNull	check(actual).isNull()
isNotNull	check(actual).isNotNull()
isTrue / true	check(actual).isTrue()	Works on non-nullable bool only
isFalse / false	check(actual).isFalse()	Works on non-nullable bool only
completion(matcher)	await check(future).completes(conditionCallback)	Must be awaited!
throwsA(matcher)	await check(future).throws<Type>()	Must be awaited!
emits(value)	await check(streamQueue).emits(conditionCallback)	Must be awaited!
emitsThrough(value)	await check(streamQueue).emitsThrough(conditionCallback)	Must be awaited!
stringContainsInOrder(list)	check(string).containsInOrder(list)	String only
pairwiseCompare(...)	check(actual).pairwiseMatches(...)

---

Matchers with No Direct Replacements

Some legacy matchers do not have a one-to-one equivalent in package:checks due to API cleanup. Use these standard workarounds:

1. Specific Error Matchers

• Legacy: throwsArgumentError, throwsStateError, throwsUnsupportedError, etc.
• Checks: Use .throws<T>() with the specific error type:

  await check(triggerError()).throws<ArgumentError>();
  

2. The anything Matcher

• Legacy: expect(actual, anything)
• Checks: Pass an empty condition callback (_) {} when a condition is syntactically required:

  await check(someFuture).completes((_) {});
  

3. Specific Numeric Toggles

• Legacy: isPositive, isNegative, isZero, isNonPositive, isNonNegative, isNonZero
• Checks: Use explicit comparative expectations:
  • isPositive $\rightarrow$ isGreaterThan(0)
  • isNegative $\rightarrow$ isLessThan(0)
  • isZero $\rightarrow$ equals(0)
  • isNonNegative $\rightarrow$ isGreaterOrEqual(0)

4. Numeric Ranges

• Legacy: inClosedOpenRange(min, max), inInclusiveRange(min, max), etc.
• Checks: Chain the boundaries using the cascade operator (..):

  check(actualValue)
    ..isGreaterOrEqual(min)
    ..isLessThan(max);
  

---

Writing Custom Expectations (Replacing Custom Matchers)

When migrating from a legacy codebase, you may encounter custom Matcher subclasses. In package:checks, custom assertions are implemented as extension methods on Subject<T>.

To write custom expectations, you must import the checks context API:

import 'package:checks/context.dart';

1. Simple Custom Expectations (using expect)

Use context.expect to check a property and return a Rejection on failure:

extension CustomPersonChecks on Subject<Person> {
  void isAdult() {
    context.expect(
      () => ['is an adult (age >= 18)'],
      (actual) {
        if (actual.age >= 18) return null; // Pass
        return Rejection(
          which: ['is only ${actual.age} years old'],
        );
      },
    );
  }
}

2. Nested Property Extraction (using nest or has)

To extract a property and allow further chained checks, use nest or the simpler has helper:

• Using has (Recommended for simple, non-failing field access):

  extension CustomPersonChecks on Subject<Person> {
    Subject<Address> get address => has((p) => p.address, 'address');
  }
  

• Using nest (For property extraction that can fail or reject):

  extension CustomPersonChecks on Subject<Person> {
    Subject<String> get ssn => context.nest(
      'has a valid SSN',
      (actual) {
        final ssnValue = actual.ssn;
        if (ssnValue == null) {
          return Extracted.rejection(which: ['has no SSN']);
        }
        return Extracted.value(ssnValue);
      },
    );
  }
  

3. Asynchronous Custom Expectations

If the expectation is asynchronous (e.g. checking a Future or Stream), use context.expectAsync or context.nestAsync and return the resulting Future:

extension CustomFutureChecks<T> on Subject<Future<T>> {
  Future<void> completesNormally() {
    return context.expectAsync(
      () => ['completes without throwing'],
      (actual) async {
        try {
          await actual;
          return null; // Pass
        } catch (e) {
          return Rejection(which: ['threw $e']);
        }
      },
    );
  }
}

---

Strategies for Discovery

Execute these commands in the terminal to identify legacy matchers and files requiring migration:

# 1. Find all test files containing legacy expect() or expectLater()
grep -rn "expect(" test/
grep -rn "expectLater(" test/

# 2. Find potential collection equality pitfalls (literal lists or maps)
grep -rn "expect(.*, \[" test/
grep -rn "expect(.*, {" test/

# 3. Find matches() calls (need conversion to RegExp + matchesPattern)
grep -rn "matches(" test/

# 4. Find legacy TypeMatcher.having() calls (which need conversion to .has())
grep -rn "having(" test/

---

Examples

Basic Assertions

Before (Matcher):

expect(someValue, isNotNull);
expect(result, isTrue, reason: 'should be successful');
expect(myString, startsWith('hello'));

After (Checks):

check(someValue).isNotNull();
check(because: 'should be successful', result).isTrue();
check(myString).startsWith('hello');

Collection and Deep Equality

Before (Matcher):

expect(items, [1, 2, 3]);
expect(configMap, equals({'port': 8080}));

After (Checks):

check(items).deepEquals([1, 2, 3]);
check(configMap).deepEquals({'port': 8080});

Chaining and Cascades

Before (Matcher):

expect(someString, allOf([
  startsWith('a'),
  contains('b'),
  endsWith('c'),
]));

After (Checks):

check(someString)
  ..startsWith('a')
  ..contains('b')
  ..endsWith('c');

Complex Property Matching (has)

Before (Matcher):

expect(response, isA<Response>()
    .having((r) => r.statusCode, 'statusCode', 200)
    .having((r) => r.body, 'body', contains('success')));

After (Checks):

check(response).isA<Response>()
  ..has((r) => r.statusCode, 'statusCode').equals(200)
  ..has((r) => r.body, 'body').contains('success');

Asynchronous Futures

Before (Matcher):

expect(fetchData(), completes);
expect(fetchData(), completion(equals('data')));
expect(failingCall(), throwsA(isA<StateError>()));

After (Checks):

await check(fetchData()).completes();
await check(fetchData()).completes((it) => it.equals('data'));
await check(failingCall()).throws<StateError>();

Asynchronous Streams

Before (Matcher):

var queue = StreamQueue(Stream.fromIterable([1, 2, 3]));
await expectLater(queue, emitsInOrder([1, 2, 3]));

After (Checks):

var queue = StreamQueue(Stream.fromIterable([1, 2, 3]));
await check(queue).inOrder([
  (s) => s.emits((e) => e.equals(1)),
  (s) => s.emits((e) => e.equals(2)),
  (s) => s.emits((e) => e.equals(3)),
]);