dart-migrate-to-checks-package
Replace the usage of `expect` and similar functions from `package:matcher` to `package:checks` equivalents.
By flutter · 7,837 installs
npx skills add flutter/agent-plugins --skill dart-migrate-to-checks-package
Source repository · Upstream listing
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]( when to use this skill)
[How to Use This Skill (The Workflow)]( how to use this skill the workflow)
[Key Syntax Differences and Pitfalls]( key syntax differences and pitfalls)
[Matcher to Checks Mapping Table]( matcher to checks mapping table)
[Matchers with No Direct Replacements]( matchers with no direct replacements)
[Strategies for Discovery]( strategies for discovery)
[Examples]( 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 :
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]( 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:
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:
2. Translate Assertions : Rewrite legacy expect and expectLater calls
to check syntax following the [Key Syntax Differences and
Pitfalls]( key syntax differences and pitfalls) and the
[Matcher to Checks Mapping Table]( 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:
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:
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) .
2. The reason Parameter is now because
Legacy Matcher : The explanation was passed as a trailing named
argument reason to expect :
Package Checks : The explanation is passed as the named argument
because to the check function before the actual subject:
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:
4. Property Extraction ( TypeMatcher.having vs .has )
Legacy Matcher : Chained field/property expectations used
TypeMatcher.having(feature, description, matcher) :
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:
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 :
Asynchronous ( Subject<Future<T ): .throws<E () returns
Future<void . Because you cannot chain directly off a Future<void , this
requires an inspection callback:
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:
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:
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:
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:
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 :
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:
2. The anything Matcher
Legacy : expect(actual, anything)
Checks : Pass an empty condition callback ( ) {} when a condition is
syntactically required:
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 ( .. ):
Writing Custom Expectations (Replacing Custom Matchers)
When migrating from a legacy codebase, you may encounter custom Matcher
subclasses. In