format_test_name

v1.0.0WarningConfigurableTesting Rules

This rule flags a test description that does not match the configured pattern.

This rule is in no preset, and reports nothing until you set a pattern — the right one is a house style with no defensible default.

Why use this rule

A test name is read far more often than it is written: in CI output, in a failure report, in a bisect log. It is read without the code beside it, so it has to carry the expectation on its own. A house pattern (should ..., given ... when ... then ...) makes that output scannable, and makes a test whose name no longer describes its body visible in review.

group(...) names are exempt by default. A group names a subject (UserRepository, when offline) rather than an expectation, so holding it to the same sentence pattern fights the convention it is meant to enforce. Set check_groups: true to include them.

A non-literal description — an interpolation, a constant, a variable — is never reported, since it cannot be read without evaluating it. That keeps parameterised tests silent.

See also: package:test, Effective Dart: testing

Don’t

// With pattern 'should .*'
test('works fine', () {});

Do

test('should load a user from the cache', () {});

// A group names a subject, so it is exempt by default.
group('UserRepository', () {});

Enabling this rule

This rule reports nothing until you set a pattern:

rules:
  format_test_name:
    pattern: 'should .*'

many_lints:
  rules:
    format_test_name:
      pattern: 'should .*'
      check_groups: false

rules:
  format_test_name:
    pattern: 'should .*'
    check_groups: false

Option	Type	Default	Description
`pattern`	string	`—`	A regular expression the whole description must match. Unset means the rule is silent
`check_groups`	bool	`false`	Also hold `group(...)` names to the pattern

Turning this rule off

To disable this rule:

rules:
  format_test_name: false

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

prefer_correct_test_file_name — Name test files so the runner actually runs them.
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().
require_mirror_test — Detect libraries under lib/ with no matching test file.