agentleFS
RodotDevRodotDev/arb_ai/.agents/skills/dart-migrate-to-checks-package/SKILL.md

dart-migrate-to-checks-package

Skill1 starsChanged 6 months agoBSD-3-ClauseView on GitHub

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

4 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

9 rules. 0 are common, 0 are distinctive, and 9 are very specific to this project.

  • 0

    Common

    Most of the 4 edited versions we read keep these.

  • 0

    Distinctive

    This author's own choices. Worth a look.

  • 9

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Add package:checks as a dev_dependency using dart pub add dev:checks.

    line 20
  2. Very specific:

    Remove package:matcher if it is explicitly listed in the pubspec.yaml (note: it is often transitively included by package:test, which is …

    line 21
  3. Very specific:

    Import package:checks/checks.dart in all test files undergoing migration.

    line 22
  4. Very specific:

    Cascades for Multiple Checks: Use Dart's cascade operator (..) to chain multiple expectations on a single subject.

    line 30
  5. Very specific:

    If checking a Future, await the check call: await check(someFuture).completes((r) => r.equals(expected));.

    line 32
  6. Very specific:

    If checking a Stream, wrap it in a StreamQueue for multiple checks, or use .withQueue for single/broadcast checks.

    line 33
  7. Very specific:

    Run the analyze_files tool on the modified test directories.

    line 48
  8. Very specific:

    Run the run_tests tool.

    line 54
  9. Very specific:

    If tests fail, review the failure output.

    line 55

“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Migrating Dart Tests to Package Checks

Contents

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

Dependency Management

Manage dependencies using the Dart Tooling MCP Server pub tool or standard CLI commands.

  • 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

Transition test assertions from the package:matcher syntax to the literate API provided by 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.

Migration Workflow

Copy and use the following checklist to track progress when migrating a test suite:

  • 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

Input (matcher):

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

Output (checks):

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

Composed Expectations

Input (matcher):

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

Output (checks):

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

Asynchronous Futures

Input (matcher):

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

Output (checks):

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

Asynchronous Streams

Input (matcher):

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

Output (checks):

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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.