prefer_expect_later

v0.4.0 Warning Fix Testing Rules

Flags expect() calls where the first argument is a Future. Passing a Future to expect() instead of expectLater() means the assertion completes before the asynchronous operation finishes, causing the test to silently pass regardless of the actual result.

Why use this rule

Using expect() with a Future is almost always a bug. The test framework cannot await a synchronous expect() call, so the assertion is evaluated against the Future object itself rather than its resolved value. Switching to await expectLater() ensures the Future completes before the matcher runs.

See also: test package - expectLater

Don’t

Future<void> bad() async {
  expect(Future.value(1), completion);

  final future = Future.value(42);
  expect(future, completion);

  expect(fetchData(), completion);
}

Do

Future<void> good() async {
  await expectLater(Future.value(1), completion);

  final future = Future.value(42);
  await expectLater(future, completion);

  // expect with non-Future values is fine:
  expect(42, completion);
  expect('hello', completion);
}

Configuration

This rule is in the core preset, so it is on with preset: core, preset: recommended or preset: opinionated.

To turn it off:

many_lints.yaml

rules:
  prefer_expect_later: false

To keep the rule on but skip certain paths, use per-rule exclude.

Related rules

• avoid_misused_test_matchers — Detect test matchers used with incompatible value types.
• prefer_test_matchers — Prefer using a Matcher instead of a literal value in expect().
• avoid_focused_tests — Detect tests focused with solo:, which silences their siblings.
• avoid_skipped_tests — Detect tests, groups and libraries switched off in place.