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.

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

pubspec.yaml

bash

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:

Update Imports:

Replace the generic

import 'package:test/test.dart';

with:

dart

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:
dart
```
import 'package:test/expect.dart'; // Temporarily allows legacy expect()
```

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.
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:
bash
```
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:
bash
```
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

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)

dart

// 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
```
:
dart
```
expect(actual, expectation, reason: 'Explanation');
```
Package Checks: The explanation is passed as the named argument
```
because
```
to the
```
check
```
function before the actual subject:
dart
```
check(because: 'Explanation', actual).expectation();
```

3. Regular Expression Matching (

matches

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:

dart

// BEFORE (Matcher)
expect(someString, matches(r'\d+'));

// AFTER (Checks)
check(someString).matchesPattern(RegExp(r'\d+'));

4. Property Extraction (

TypeMatcher.having

.has

)

Legacy Matcher: Chained field/property expectations used

TypeMatcher.having(feature, description, matcher)

dart

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

Package Checks: The
```
.has(feature, description)
```
extension is available on all
```
Subject
```
s, takes one fewer argument, and returns a new
```
Subject
```
representing that property. You chain expectations directly off it:
dart
```
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>

dart

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

dart

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

dart

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:

dart

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

8. Map Key Containment (

containsKey

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:

dart

// 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:
dart
```
// 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

Map

dart

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

dart

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:
dart
```
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 (

..

dart

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:

dart

import 'package:checks/context.dart';

1. Simple Custom Expectations (using

expect

)

Use

context.expect

to check a property and return a

Rejection

on failure:

dart

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

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

dart

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

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

dart

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

context.nestAsync

and return the resulting

Future

dart

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:

bash

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

dart

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

After (Checks):

dart

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

Collection and Deep Equality

Before (Matcher):

dart

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

After (Checks):

dart

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

Chaining and Cascades

Before (Matcher):

dart

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

After (Checks):

dart

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

Complex Property Matching (has)

Before (Matcher):

dart

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

After (Checks):

dart

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

Asynchronous Futures

Before (Matcher):

dart

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

After (Checks):

dart

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

Asynchronous Streams

Before (Matcher):

dart

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

After (Checks):

dart

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

dart-migrate-to-checks-package

NPX Install

Tags

SKILL.md Content

Migrating Dart Tests to Package Checks

Contents

When to Use This Skill

How to Use This Skill (The Workflow)

1. Dependency Setup

2. Identify and Plan Target Files

3. Migrating a File (Incremental or Full)

4. Verification and Feedback Loops

Key Syntax Differences and Pitfalls

1. Collection Equality Pitfall (equals vs deepEquals)

2. The reason Parameter is now because

3. Regular Expression Matching (matches vs matchesPattern)

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

5. Synchronous vs. Asynchronous throws

6. RegExp / Pattern Equality

7. Strict Nullable Boolean Safety (bool? fields)

8. Map Key Containment (containsKey vs contains)

9. Explicit Generic Parameters for Extension Types

10. Dynamic Map / JSON Lookup Casting

Matcher-to-Checks Mapping Table

Matchers with No Direct Replacements

1. Specific Error Matchers

2. The anything Matcher

3. Specific Numeric Toggles

4. Numeric Ranges

Writing Custom Expectations (Replacing Custom Matchers)

1. Simple Custom Expectations (using expect)

2. Nested Property Extraction (using nest or has)

3. Asynchronous Custom Expectations

Strategies for Discovery

Examples

Basic Assertions

Collection and Deep Equality

Chaining and Cascades

Complex Property Matching (has)

Asynchronous Futures

Asynchronous Streams

1. Collection Equality Pitfall (
`equals`
vs
`deepEquals`
)

2. The
`reason`
Parameter is now
`because`

3. Regular Expression Matching (
`matches`
vs
`matchesPattern`
)

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

5. Synchronous vs. Asynchronous
`throws`

7. Strict Nullable Boolean Safety (
`bool?`
fields)

8. Map Key Containment (
`containsKey`
vs
`contains`
)

2. The
`anything`
Matcher

1. Simple Custom Expectations (using
`expect`
)

2. Nested Property Extraction (using
`nest`
or
`has`
)