Dart Migrate To Checks PackageSAFE

An agent skill published by flutter.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: dart-migrate-to-checks-package
description: |-
  Replace the usage of `expect` and similar functions from `package:matcher`
  to `package:checks` equivalents.
metadata:
  model: models/gemini-3.1-pro-preview
  last_modified: Tue, 09 Jun 2026 19:30:00 GMT
---
# 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`:
  ```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).

### 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:
     ```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](#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:
  ```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.

---

## 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)`.
  ```dart
  // 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`:
  ```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();
  ```

### 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:
  ```dart
  // 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)`:
  ```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

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Dart Migrate To Checks Package](https://modelsatlas.com/skills/flutter/dart-migrate-to-checks-package/badge.svg)](https://modelsatlas.com/skills/flutter/dart-migrate-to-checks-package/)

Not your listing, or something out of date? Claim or update your listing.