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.

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().

• TypeMatcher<T>:

  • Prefer when defining top-level reusable matchers.
  • Use const: const isMyType = TypeMatcher<MyType>();
  • Chaining .having() works here too, but the resulting matcher is not const.

3. Object Properties (having)

Use .having() on isA<T>() or other TypeMatchers to check properties.

• Descriptive Names: Use meaningful parameter names in the closure (e.g., (e) => e.message) instead of generic ones like p0 to improve readability.

expect(person, isA<Person>()
    .having((p) => p.name, 'name', 'Alice')
    .having((p) => p.age, 'age', greaterThan(18)));

This provides detailed failure messages indicating exactly which property failed.