dart-migrate-to-checks-package

Popular

Replace the usage of `expect` and similar functions from `package:matcher` to `package:checks` equivalents.

392stars

25forks

Updated 7/10/2026

Get Skill Source Code

Related Skills

content-research-writer68K

music-to-video32K

writing-guidelines29K

SKILL.md

readonlyread-only

name

dart-migrate-to-checks-package

description

Replace the usage of `expect` and similar functions from `package:matcher` to `package:checks` equivalents.

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

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

article-writing

230Kwriting-content

Write articles, guides, blog posts, tutorials, newsletter issues, and other long-form content in a distinctive voice derived from supplied examples or brand guidance. Use when the user wants polished written content longer than a paragraph, especially when voice consistency, structure, and credibility matter.

affaan-m

Get

internal-comms

153Kwriting-content

A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal communications (status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.).

anthropics

Get

mkdocs-translations

37Kwriting-content

Generate a language translation for a mkdocs documentation stack.

github

Get

Continue Exploring

Browse writing-content Popular Skills Recently Updated

dart-migrate-to-checks-package

Related Skills

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

You Might Also Like

article-writing

internal-comms

mkdocs-translations

Continue Exploring

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