Migrating Dart Tests to Package Checks

Contents

• Dependency Management
• Syntax Migration Guidelines
• Utilizing Dart MCP Tools
• Migration Workflow
• Examples

Dependency Management

pub

• Add

  package:checks

  as a

  dev_dependency

  using

  dart pub add dev:checks

  .
• Remove

  package:matcher

  if it is explicitly listed in the

  pubspec.yaml

  (note: it is often transitively included by

  package:test

  , which is fine).
• Import

  package:checks/checks.dart

  in all test files undergoing migration.

Syntax Migration Guidelines

package:matcher

package:checks

• Basic Equality: Replace

  expect(actual, equals(expected))

  or

  expect(actual, expected)

  with

  check(actual).equals(expected)

  .
• Type Checking: Replace

  expect(actual, isA<Type>())

  with

  check(actual).isA<Type>()

  .
• Property Extraction: Replace

  expect(actual.property, expected)

  with

  check(actual).has((a) => a.property, 'property name').equals(expected)

  .
• Cascades for Multiple Checks: Use Dart's cascade operator (

  ..

  ) to chain multiple expectations on a single subject.
• Asynchronous Expectations:
  • If checking a

    Future

    ,

    await

    the

    check

    call:

    await check(someFuture).completes((r) => r.equals(expected));

    .
  • If checking a

    Stream

    , wrap it in a

    StreamQueue

    for multiple checks, or use

    .withQueue

    for single/broadcast checks.

Utilizing Dart MCP Tools

• Use

  pub

  to run

  dart pub get

  or

  dart pub add

  .
• Use

  analyze_files

  to run static analysis on the project or specific paths.
• Use

  run_tests

  to execute Dart or Flutter tests with an agent-centric UX. ALWAYS use this instead of shell commands like

  dart test

  .
• Use

  dart_fix

  to apply automated fixes if applicable.

Migration Workflow

• Task Progress
  • Add

    package:checks

    as a dev dependency.
  • Identify all test files using

    package:matcher

    (

    expect

    calls).
  • Import

    package:checks/checks.dart

    in target test files.
  • Rewrite all

    expect(...)

    statements to

    check(...)

    statements.
  • Run static analyzer (

    analyze_files

    ).
  • Run tests (

    run_tests

    ).

Feedback Loop: Static Analysis

1. Run the

   analyze_files

   tool on the modified test directories.
2. Review any static analysis warnings or errors (e.g., missing imports, incorrect generic types on

   isA

   , unawaited futures).
3. Fix the warnings.
4. Repeat until the analyzer returns zero issues.

Feedback Loop: Test Validation

1. Run the

   run_tests

   tool.
2. If tests fail, review the failure output.

   package:checks

   provides detailed context (e.g.,

   Which: has length of <2>

   ).
3. Adjust the

   check()

   expectations or the underlying code to resolve the failure.
4. Repeat until all tests pass.

Examples

Basic Assertions

matcher

expect(someList.length, 1);
expect(someString, startsWith('a'));
expect(someObject, isA<Map>());

checks

check(someList).length.equals(1);
check(someString).startsWith('a');
check(someObject).isA<Map>();

Composed Expectations

matcher

expect('foo,bar,baz', allOf([
  contains('foo'),
  isNot(startsWith('bar')),
  endsWith('baz')
]));

checks

check('foo,bar,baz')
  ..contains('foo')
  ..not((s) => s.startsWith('bar'))
  ..endsWith('baz');

Asynchronous Futures

matcher

expect(Future.value(10), completion(equals(10)));
expect(Future.error('oh no'), throwsA(equals('oh no')));

checks

await check(Future.value(10)).completes((it) => it.equals(10));
await check(Future.error('oh no')).throws<String>().equals('oh no');

Asynchronous Streams

matcher

var stdout = StreamQueue(Stream.fromIterable(['Ready', 'Go']));
await expectLater(stdout, emitsThrough('Ready'));

checks

var stdout = StreamQueue(Stream.fromIterable(['Ready', 'Go']));
await check(stdout).emitsThrough((it) => it.equals('Ready'));