Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add kevmoo/dash_skills --skill dart-matcher-best-practices -a claude-code
Open on GitHub

What 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/catch with 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-code

2Manually: put the files in place

~/.claude/skills/dart-matcher-best-practices/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/dart-matcher-best-practices/

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

Similar skills

All skills for Testing and QA →

From the same set9

dart-best-practices dart-best-practices enforces idiomatic Dart code style and formatting during generation and review. Focuses on clean multi-line string literals and strict 80-character line wrapping. CX Codex +1 847installs dart-test-fundamentals dart-test-fundamentals — a skill for Claude Code and Codex that enforces best practices for Dart's package:test. It structures test suites, configures dart_test.yaml, and handles teardowns. CX Codex +1 455installs dart-modern-features dart-modern-features guides coding agents on modern Dart 3.0 to 3.10 features. It helps adopt records, extension types, class modifiers, and null-aware elements during refactoring. CX Codex +1 370installs dart-doc-validation The dart-doc-validation skill for Claude Code validates Dart documentation comments with dart doc and the comment_references lint, catching broken links. CX Codex +1 291installs dart-package-maintenance dart-package-maintenance — a skill for maintaining Dart packages per Dart team standards: manage semantic versioning, keep CHANGELOG in sync, and prepare releases. Essential if you publish packages to pub.dev. CX Codex +1 285installs dart-test-coverage Run Dart test coverage, inspect missed lines, and identify code that needs tests. Useful when checking which parts of a package remain untested. CX Codex +1 163installs dart-long-lines dart-long-lines is a Claude Code skill for keeping Dart lines within 80 columns. It applies while writing code or fixing the lines_longer_than_80_chars lint. CX Codex +1 150installs dart-multiline-strings dart-multiline-strings — a skill for Claude Code, Codex, Cursor and other agents that teaches rewriting consecutive print() calls and string concatenations into triple-quoted literals (''' or """). CX Codex +1 116installs

Project sponsors

Companies that keep this analytics open