prefer_test_matchers

v0.4.0 Warning Testing Rules

Flags expect() and expectLater() calls where the second argument is a raw literal value instead of a Matcher subclass. Using raw literals like expect(x, 1) produces less informative failure messages than using matchers like expect(x, equals(1)).

Why use this rule

When a test fails, matchers provide descriptive output such as “Expected: has length of 3 / Actual: [1, 2]” instead of just “Expected: 3 / Actual: 2”. This makes debugging faster. Using matchers also enables richer assertions like hasLength(), contains(), and isA<T>() that raw values cannot express.

See also: test package - Matchers

Don’t

expect(scores.length, 1);
expect(value, 'hello');
expect(true, true);
expect(scores, [7, 8, 9]);
expect(maybeNull, null);
expectLater(scores.length, 1);

Do

expect(scores, hasLength(1));
expect(value, equals('hello'));
expect(true, isTrue);
expect(scores, equals([7, 8, 9]));
expect(maybeNull, isNull);
expect(value, isA<String>());
expectLater(scores, hasLength(3));

Configuration

This rule is in the opinionated preset, so it is on with preset: opinionated, or by name:

many_lints.yaml

rules:
  prefer_test_matchers: true

To turn it off again:

many_lints.yaml

rules:
  prefer_test_matchers: 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_expect_later — Use ‘expectLater’ instead of ‘expect’ when testing Futures.
• format_test_name — Hold test descriptions to a house pattern.
• prefer_correct_test_file_name — Name test files so the runner actually runs them.