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:

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)),
]);