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:

  bashCopy code
  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:

     dartCopy code
     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:

     dartCopy code
     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:

  bashCopy code
  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:

  bashCopy code
  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).

  dartCopy code
  // 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:

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

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

  dartCopy code
  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:

  dartCopy code
  // 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):

  dartCopy code
  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:

  dartCopy code
  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>:

    dartCopy code
    // 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:

    dartCopy code
    // 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:

  dartCopy code
  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:

  dartCopy code
  // 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:

  dartCopy code
  // 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:

  dartCopy code
  // 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:

  dartCopy code
  // 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:

  dartCopy code
  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:

  dartCopy code
  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 (..):

  dartCopy code
  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:

dartCopy code
import 'package:checks/context.dart';

1. Simple Custom Expectations (using expect)

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

dartCopy code
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):

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

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

  dartCopy code
  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:

dartCopy code
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:

bashCopy code
# 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):

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

After (Checks):

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

Collection and Deep Equality

Before (Matcher):

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

After (Checks):

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

Chaining and Cascades

Before (Matcher):

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

After (Checks):

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

Complex Property Matching (has)

Before (Matcher):

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

After (Checks):

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

Asynchronous Futures

Before (Matcher):

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

After (Checks):

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

Asynchronous Streams

Before (Matcher):

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

After (Checks):

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