Dart Matcher Best Practices

This one helps you write cleaner test assertions in Dart by moving from manual checks to proper matchers from package:matcher. It shows you how to replace things like expect(list.length, 3) with expect(list, hasLength(3)), or manual map lookups with containsPair. The regex patterns are handy for finding code to improve in your codebase. The having() examples for chaining property checks are solid, and the async section clears up a common gotcha with expectLater timing. If you've got tests that feel clunky or produce confusing failure messages, this gives you the patterns to fix them.

skills.sh installs: 269
GitHub stars: 148
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add kevmoo/dash_skills --skill dart-matcher-best-practices --agent claude-code

Installs into .claude/skills of the current project.

Files

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.

When NOT to use (Abstention Guardrails)

Do NOT apply this skill or refactor assertions when:

Non-Collection Properties: The property happens to be named .length but belongs to a non-collection class (e.g. geometric scalar magnitude on a Vector, duration on a buffer, or line segment distance). hasLength(n) expects an int on an Iterable, Map, or String.
Custom Domain Booleans: The boolean check tests an arbitrary domain property (e.g. expect(switch.isEnabled, isTrue)). Do not invent non-existent matchers.
Alternative Assertion Frameworks: The package has adopted package:checks (check(x)...). Do not revert checks back to package:matcher.
Already Idiomatic Assertions: Tests already use declarative matchers (hasLength, isEmpty, isNotEmpty, contains, containsPair, isA, throwsA). Abstain and make zero modifications.