Back to Details

dart-migrate-to-checks-package

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Migrating Dart Tests to Package Checks

将Dart测试迁移至Package Checks

Contents

目录

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.
使用Dart Tooling MCP Server的
pub
工具或标准CLI命令管理依赖。
  • 通过
    dart pub add dev:checks
    将
    package:checks
    添加为开发依赖。
  • 如果
    pubspec.yaml
    中显式列出了
    package:matcher
    ，则将其移除（注意：它通常会被
    package:test
    间接引入，这种情况无需处理）。
  • 在所有待迁移的测试文件中导入
    package:checks/checks.dart
    。

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.
将测试断言从
package:matcher
语法转换为
package:checks
提供的易读API。
  • 基础相等性检查： 将
    expect(actual, equals(expected))
    或
    expect(actual, expected)
    替换为
    check(actual).equals(expected)
    。
  • 类型检查： 将
    expect(actual, isA<Type>())
    替换为
    check(actual).isA<Type>()
    。
  • 属性提取： 将
    expect(actual.property, expected)
    替换为
    check(actual).has((a) => a.property, 'property name').equals(expected)
    。
  • 多检查链式调用： 使用Dart的级联运算符(
    ..
    )对同一对象链式调用多个断言。
  • 异步断言：
    • 如果检查
      Future
      ，需
      await
      对应的
      check
      调用：
      await check(someFuture).completes((r) => r.equals(expected));
      。
    • 如果检查
      Stream
      ，可将其包装在
      StreamQueue
      中进行多检查，或使用
      .withQueue
      进行单次/广播流检查。

Utilizing Dart MCP Tools

使用Dart MCP工具

Leverage the Dart MCP Server tools to automate and validate the migration process.
  • 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.
借助Dart MCP Server工具自动化并验证迁移流程。
  • 使用
    pub
    执行
    dart pub get
    或
    dart pub add
    命令。
  • 使用
    analyze_files
    对项目或指定路径进行静态分析。
  • 使用
    run_tests
    以Agent为中心的用户体验执行Dart或Flutter测试。请务必使用该工具替代
    dart test
    等shell命令。
  • 若适用，使用
    dart_fix
    应用自动修复。

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
      ).
复制并使用以下清单跟踪测试套件的迁移进度：
  • 任务进度
    • 将
      package:checks
      添加为开发依赖。
    • 识别所有使用
      package:matcher
      （含
      expect
      调用）的测试文件。
    • 在目标测试文件中导入
      package:checks/checks.dart
      。
    • 将所有
      expect(...)
      语句改写为
      check(...)
      语句。
    • 运行静态分析器(
      analyze_files
      )。
    • 运行测试(
      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.
  1. 在修改后的测试目录上运行
    analyze_files
    工具。
  2. 查看所有静态分析警告或错误（例如：缺失导入、
    isA
    上的泛型类型错误、未等待的Future）。
  3. 修复警告。
  4. 重复操作直至分析器返回零问题。

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.
  1. 运行
    run_tests
    工具。
  2. 如果测试失败，查看失败输出。
    package:checks
    会提供详细上下文（例如：
    Which: has length of <2>
    ）。
  3. 调整
    check()
    断言或底层代码以解决失败问题。
  4. 重复操作直至所有测试通过。

Examples

示例

Basic Assertions

基础断言

Input (
matcher
):
dart
expect(someList.length, 1);
expect(someString, startsWith('a'));
expect(someObject, isA<Map>());
Output (
checks
):
dart
check(someList).length.equals(1);
check(someString).startsWith('a');
check(someObject).isA<Map>();
输入（
matcher
）：
dart
expect(someList.length, 1);
expect(someString, startsWith('a'));
expect(someObject, isA<Map>());
输出（
checks
）：
dart
check(someList).length.equals(1);
check(someString).startsWith('a');
check(someObject).isA<Map>();

Composed Expectations

组合断言

Input (
matcher
):
dart
expect('foo,bar,baz', allOf([
  contains('foo'),
  isNot(startsWith('bar')),
  endsWith('baz')
]));
Output (
checks
):
dart
check('foo,bar,baz')
  ..contains('foo')
  ..not((s) => s.startsWith('bar'))
  ..endsWith('baz');
输入（
matcher
）：
dart
expect('foo,bar,baz', allOf([
  contains('foo'),
  isNot(startsWith('bar')),
  endsWith('baz')
]));
输出（
checks
）：
dart
check('foo,bar,baz')
  ..contains('foo')
  ..not((s) => s.startsWith('bar'))
  ..endsWith('baz');

Asynchronous Futures

异步Future

Input (
matcher
):
dart
expect(Future.value(10), completion(equals(10)));
expect(Future.error('oh no'), throwsA(equals('oh no')));
Output (
checks
):
dart
await check(Future.value(10)).completes((it) => it.equals(10));
await check(Future.error('oh no')).throws<String>().equals('oh no');
输入（
matcher
）：
dart
expect(Future.value(10), completion(equals(10)));
expect(Future.error('oh no'), throwsA(equals('oh no')));
输出（
checks
）：
dart
await check(Future.value(10)).completes((it) => it.equals(10));
await check(Future.error('oh no')).throws<String>().equals('oh no');

Asynchronous Streams

异步Stream

Input (
matcher
):
dart
var stdout = StreamQueue(Stream.fromIterable(['Ready', 'Go']));
await expectLater(stdout, emitsThrough('Ready'));
Output (
checks
):
dart
var stdout = StreamQueue(Stream.fromIterable(['Ready', 'Go']));
await check(stdout).emitsThrough((it) => it.equals('Ready'));
输入（
matcher
）：
dart
var stdout = StreamQueue(Stream.fromIterable(['Ready', 'Go']));
await expectLater(stdout, emitsThrough('Ready'));
输出（
checks
）：
dart
var stdout = StreamQueue(Stream.fromIterable(['Ready', 'Go']));
await check(stdout).emitsThrough((it) => it.equals('Ready'));