dart-matcher-best-practices — Claude Code skill: install
dart-matcher-best-practices is a Claude Code skill for writing Dart tests with expect and package:matcher. It steps in when adding assertions, cleaning up manual checks, or investigating confusing test failures.
Apache-2.0 269 installs ★ 149 updated 2026-10-17
npx skills add kevmoo/dash_skills --skill dart-matcher-best-practices -a claude-codeWhat dart-matcher-best-practices does
The skill recommends matchers for collections, types, object properties, and exceptions. It shows how to replace a list-length comparison with hasLength, or check a map entry with containsPair instead of inspecting the lookup result yourself.
For asynchronous tests, it covers await expectLater with completion and throwsA. It also describes patterns to search for when reviewing assertions and ways to express expected exceptions without imperative try/catch logic.
It leaves idiomatic matcher assertions alone and does not convert tests from package:checks back to package:matcher. hasLength applies to an Iterable, Map, or String, not to an unrelated property named .length.
What it helps with
- replace a manual collection-length check with
hasLength - assert a map key-value pair with
containsPair - express an expected exception with
throwsA - sequence an asynchronous assertion with
await expectLater
Example prompts for the agent
- Rewrite this list-length assertion with a suitable matcher.
- Check this map entry with a matcher.
- Replace the test's
try/catchwith an expected-exception assertion.
How to install dart-matcher-best-practices
1Skills CLI (Vercel)
npx skills add kevmoo/dash_skills --skill dart-matcher-best-practices -a claude-code2Manually: put the files in place
~/.claude/skills/dart-matcher-best-practices/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/dart-matcher-best-practices/
1Skills CLI (Vercel)
npx skills add kevmoo/dash_skills --skill dart-matcher-best-practices -a codex2Manually: put the files in place
.agents/skills/dart-matcher-best-practices/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add kevmoo/dash_skills --skill dart-matcher-best-practices -a cursor2Manually: put the files in place
.cursor/skills/dart-matcher-best-practices/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install kevmoo/dash_skills skills/dart-matcher-best-practices2Manually: put the files in place
.github/skills/dart-matcher-best-practices/SKILL.md1Skills CLI (Vercel)
npx skills add kevmoo/dash_skills --skill dart-matcher-best-practices -a gemini-cli2Platform CLI
gemini skills install https://github.com/kevmoo/dash_skills --path skills/dart-matcher-best-practicesManually: put the files in place
.devin/skills/dart-matcher-best-practices/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add kevmoo/dash_skills --skill dart-matcher-best-practices -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about dart-matcher-best-practices
How do I install dart-matcher-best-practices in Claude Code?
Run npx skills add kevmoo/dash_skills --skill dart-matcher-best-practices -a claude-code. The skill file is installed at ~/.claude/skills/dart-matcher-best-practices/SKILL.md.
What does dart-matcher-best-practices do?
It helps select package:matcher assertions for Dart tests, covering collections, types, object properties, async results, and exceptions. It also points out manual checks that can be expressed with matchers.
When does the skill leave assertions unchanged?
It leaves idiomatic matcher assertions as they are and does not migrate package:checks tests to package:matcher. It also avoids applying hasLength to a non-collection property called .length.
Source text
SKILL.md · Apache-2.0
---
name: dart-matcher-best-practices
description: |-
Best practices for using `expect` and `package:matcher`.
Focuses on readable assertions, proper matcher selection, and avoiding
common pitfalls.
license: Apache-2.0
key_features:
- Package matcher assertions
- Readable test expectations
- Matcher selection & refactoring
---
# 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.
## 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()`.
- **`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.
```dart
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.
### 4. Async Assertions
- **`completion(matcher)`**:
- Wait for a future to complete and check its value.
- **Prefer `await expectLater(...)`** to ensure the future completes before
the test continues.
- `await expectLater(future, completion(equals(42)))`.
- **`throwsA(matcher)`**:
- Check that a future or function throws an exception.
- `await expectLater(future, throwsA(isA<StateError>()))`.
- `expect(() => function(), throwsA(isA<ArgumentError>()))` (synchronous
function throwing is fine with `expect`).
### 5. Exception Testing (Avoid `try/catch` with `fail()`)
- **Prefer `throwsA` over imperative `try/catch`**:
- Legacy tests often use
`try { fn(); fail('should throw'); } catch (e) { expect(e, isA<T>()); }`.
- Replace with declarative matchers:
```dart
// Synchronous:
expect(() => parseData('invalid'), throwsA(isA<FormatException>()));
// Asynchronous:
await expectLater(client.fetch('bad-url'), throwsA(isA<HttpException>()));
```
- Common built-in exception matchers include `throwsArgumentError`,
`throwsStateError`, `throwsRangeError`, `throwsFormatException`,
`throwsNoSuchMethodError`, and `throwsUnsupportedError`.
### 6. Using `expectLater`
Use `await expectLater(...)` when testing async behavior to ensure proper
sequencing.
```dart
// GOOD: Waits for future to complete before checking side effects
await expectLater(future, completion(equals(42)));
expect(sideEffectState, equals('done'));
// BAD: Side effect check might run before future completes
expect(future, completion(equals(42)));
expect(sideEffectState, equals('done')); // Race condition!
```
## Principles
1. **Readable Failures**: Choose matchers that produce clear error messages.
2. **Avoid Manual Logic**: Don't use `if` statements or `for` loops for
assertions; let matchers handle it.
3. **Specific Matchers**: Use the most specific matcher available (e.g.,
`containsPair` for maps instead of checking keys manually).
## Related Skills
- **[dart-test-fundamentals]**: Core concepts for structuring tests, lifecycles,
and configuration.
[dart-test-fundamentals]:
https://github.com/kevmoo/dash_skills/blob/main/skills/dart-test-fundamentals/SKILL.md
© kevmoo · Apache-2.0 · kevmoo/dash_skills