dart-matcher-best-practices

Dart Matcher Best Practices

When to use this skill

Use this skill when:

• Writing assertions using expect and package:matcher.
• Migrating legacy manual checks to cleaner matchers.
• Debugging confusing test failures.

Discovery

To find candidates for improving matcher usage, search for suboptimal patterns:

Suboptimal Length Checks

Search for length checks that should use hasLength:

• Regex: expect\([^,]+.length,\s*

Suboptimal Boolean Checks

Search for checks on boolean properties that have specific matchers:

• Regex: expect\([^,]+.isEmpty,\s*(true|equals\(true\))
• Regex: expect\([^,]+.isNotEmpty,\s*(true|equals\(true\))
• Regex: expect\([^,]+.contains\(.*\),\s*(true|equals\(true\))

Suboptimal Map Lookups

Search for manual map lookups instead of containsPair:

• Regex: expect\([^,]+\[.*\],\s*

Core Matchers

1. Collections (hasLength, contains, isEmpty, unorderedEquals, containsPair)

• hasLength(n):

  • Prefer expect(list, hasLength(n)) over expect(list.length, n).
  • Gives better error messages on failure (shows actual list content).

• isEmpty / isNotEmpty:

  • Prefer expect(list, isEmpty) over expect(list.isEmpty, true).
  • Prefer expect(list, isNotEmpty) over expect(list.isNotEmpty, true).

• contains(item):

  • Verify existence without manual iteration.
  • Prefer over expect(list.contains(item), true).

• unorderedEquals(items):

  • Verify contents regardless of order.
  • Prefer over expect(list, containsAll(items)).

• containsPair(key, value):

  • Verify a map contains a specific key-value pair.
  • Prefer over checking expect(map[key], value) or expect(map.containsKey(key), true).

2. Type Checks (isA<T> and TypeMatcher<T>)

• isA<T>():
  • Prefer for inline assertions: expect(obj, isA<Type>()).
  • More concise and readable than TypeMatcher<Type>().
  • Allows chaining constraints using .having().