test-best-practices

When to use this skill

Workflow

1. Search: Use the grep commands below to identify candidates.
2. Analyze: Check if the code violates the best practices defined below.
3. Apply: Refactor the code to use the recommended matchers.
4. Verify: Run tests (

   dart test

   ) to ensure no regressions.

Search Strategies

• .length

  :

  grep -r "\.length,\s*equals\(" test/

• Boolean properties:

  grep -rE "expect\(.*\.(is(Empty|NotEmpty)),\s*(isTrue|true|isFalse|false)" test/

• Manual loops:

  grep -r "for (var .* in .*)" test/

  (manual review required)

Best Practice Patterns

Collections

Use

hasLength

expect(list, hasLength(n))

expect(list.length, n)

Iterable

Map

String

Use

isEmpty

/

isNotEmpty

expect(list, isEmpty)

expect(list.isEmpty, true)

expect(list, isNotEmpty)

expect(list.isNotEmpty, true)

expect(list, isNot(isEmpty))

Iterable

Map

String

Declarative Verification

expect(list, everyElement(matcher))

List Equality

expect(actualList, expectedList)

package:test

Maps

Use

containsPair

expect(map, containsPair(key, value))

expect(map[key], value)

expect(map, isNot(contains(key)))

Strict Equality

expect(map, {'k': 'v'})

containsPair

Types & Objects

Declarative Type Checks

expect(obj, isA<T>())

expect(obj is T, isTrue)

Grouped Assertions

having

isA<T>

expect(obj, isA<MyType>()
  .having((o) => o.prop1, 'prop1', a)
  .having((o) => o.prop2, 'prop2', b));

Constraints

• Verify Types: Ensure subject is strictly

  Iterable

  /

  Map

  before applying collection matchers. Some custom classes (e.g.

  PriorityQueue

  ) may have

  .length

  but don't implement

  Iterable

  .
• Do NOT migrate to package:checks: Unless explicitly requested. This skill focuses on

  package:test

  matchers.
• Preserve Behavior: Ensure refactorings do not change strictness.