format_test_name

v1.0.0WarningConfigurableTesting Rules

Holds every test(...) and testWidgets(...) description to a regular expression you choose.

A test name is read without the code beside it — in CI output, in a failure report, in a bisect log — so it has to carry the expectation on its own.

This rule is in no preset and reports nothing until you set pattern:. There is no defensible default house style, so every example below shows the configuration that produces it.

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

rules:
  format_test_name:
    pattern: 'should .*'

pattern must match the whole description, not merely appear in it.

Examples

The `should ...` style

pattern: 'should .*'

// Don't
test('caches the user', () {});
test('Should load a user', () {});  // capital S is not `should`

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

Given / when / then

pattern: 'given .+ when .+ then .+'

// Don't
test('offline load fails', () {});

// Do
test('given no network when loading then it throws', () {});

Allow either of two styles

pattern is a plain Dart regular expression, so alternation works:

pattern: '(should|must) .*'

// Don't
test('returns the cached user', () {});

// Do
test('should return the cached user', () {});
test('must reject an expired token', () {});

Groups are exempt by default

A group names a subject, not an expectation, so it is not held to the pattern unless you ask:

pattern: 'should .*'
check_groups: false      # the default

group('UserRepository', () {
  test('should return the cached user', () {});
});

Holding groups to a pattern too

pattern: '(should|when|given) .*'
check_groups: true

// Don't
group('UserRepository', () {          // now reported
  test('should return the cached user', () {});
});

// Do
group('when the cache is warm', () {
  test('should return the cached user', () {});
});

Scoping the pattern to part of the tree

exclude takes globs, so a legacy suite can keep its old names while new code is held to the convention:

analysis_options.yaml
many_lints.yaml

many_lints:
  rules:
    format_test_name:
      pattern: 'should .*'
      exclude:
        - 'test/legacy/**'

rules:
  format_test_name:
    pattern: 'should .*'
    exclude:
      - 'test/legacy/**'

Options

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

Known limitations

Only string literals are checked. An interpolated or computed description — test('should load $name', ...), test(kCacheCase, ...) — is never reported, because it cannot be read without evaluating it. That keeps parameterised tests silent.

Only test, testWidgets and (opt-in) group. A description passed to a custom helper of your own is not checked.

An invalid pattern is ignored, not reported. A plugin cannot report against a YAML file, so a pattern that is not valid regex leaves the rule silent rather than failing loudly.

Turning this rule off

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.