• 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 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.

• Add

  package:checks

  as a

  dev_dependency

  in

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

• 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.

1. 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()

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.

• 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.

[!IMPORTANT] A line-for-line translation can sometimes introduce subtle bugs or false passes. Always review these key differences carefully:

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

• 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();

• 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+'));

• 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');

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

    .

• 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();

• 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);

• 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');

• 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);

• 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

  :
  dart

  // YES (Explicit cast to List)
  check(myIterable).deepEquals(json['data']['items'] as List);

• Legacy:

  throwsArgumentError

  ,

  throwsStateError

  ,

  throwsUnsupportedError

  , etc.
• Checks: Use

  .throws<T>()

  with the specific error type:
  dart

  await check(triggerError()).throws<ArgumentError>();

• Legacy:

  expect(actual, anything)

• Checks: Pass an empty condition callback

  (_) {}

  when a condition is syntactically required:
  dart

  await check(someFuture).completes((_) {});

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

• Legacy:

  inClosedOpenRange(min, max)

  ,

  inInclusiveRange(min, max)

  , etc.
• Checks: Chain the boundaries using the cascade operator (

  ..

  ):
  dart

  check(actualValue)
    ..isGreaterOrEqual(min)
    ..isLessThan(max);

nest

has

• 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);
      },
    );
  }