К основному содержанию
скилл CX Codex

dart-matcher-best-practices — скилл для Claude Code: установка

Скилл dart-matcher-best-practices для Claude Code помогает писать проверки Dart через expect и package:matcher. Он подключается при создании тестов, разборе сбоев и замене ручных проверок.

Apache-2.0 269 установок ★ 149 обновлён 2026-10-17

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add kevmoo/dash_skills --skill dart-matcher-best-practices -a claude-code
Открыть на GitHub

Что делает dart-matcher-best-practices

Скилл предлагает подходящие матчеры для проверок коллекций, типов, свойств объектов и исключений. Например, он помогает заменить сравнение длины списка на hasLength, а проверку пары ключ-значение в Map — на containsPair.

Для асинхронных тестов он объясняет, когда использовать await expectLater и матчеры completion или throwsA. Также описывает поиск шаблонов проверок, которые можно упростить, и переход от try/catch к декларативной проверке исключений.

Скилл не меняет уже идиоматичные проверки и не переводит тесты с package:checks обратно на package:matcher. hasLength предназначен для Iterable, Map или String, а не для произвольного свойства .length.

Какие задачи решает

  • заменить ручную проверку длины коллекции на hasLength
  • проверить пару ключ-значение в Map через containsPair
  • переписать обработку ожидаемого исключения на throwsA
  • упорядочить асинхронную проверку с await expectLater

Примеры запросов агенту

  • Перепиши проверку длины списка на подходящий матчер.
  • Проверь эту пару в Map с помощью матчера.
  • Замени try/catch в тесте на проверку ожидаемого исключения.

Как установить dart-matcher-best-practices

1Через Skills CLI (Vercel)

npx skills add kevmoo/dash_skills --skill dart-matcher-best-practices -a claude-code

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/dart-matcher-best-practices/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о dart-matcher-best-practices

Как установить dart-matcher-best-practices в Claude Code?

Запусти npx skills add kevmoo/dash_skills --skill dart-matcher-best-practices -a claude-code. Файл скилла устанавливается по пути ~/.claude/skills/dart-matcher-best-practices/SKILL.md.

Что делает dart-matcher-best-practices?

Помогает выбирать матчеры package:matcher для тестов Dart и заменять ручные проверки на более выразительные утверждения. Охватывает коллекции, типы, свойства объектов, асинхронные результаты и исключения.

Когда скилл не меняет проверки?

Он оставляет уже идиоматичные матчеры без изменений и не заменяет package:checks на package:matcher. Также не предлагает hasLength для .length, если это свойство не коллекции.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Тесты и QA» →
dart-migrate-to-checks-package dart-lang Скилл dart-migrate-to-checks-package для Claude Code переводит тесты Dart с package:matcher на package:checks. Автоматизирует миграцию утверждений и улучшает диагностику ошибок. CX Codex +1 20 000установок dart-add-unit-test dart-lang Скилл dart-add-unit-test для Claude Code, Codex и других агентов пишет и организует юнит-тесты на package:test. Включается при добавлении логики или исправлении багов, чтобы избежать регрессий. CX Codex +1 21 400установок dart-use-path-package flutter Скилл dart-use-path-package учит агента работать с путями файлов в Dart через package:path, избегая строковых операций, которые ломаются на Windows. CX Codex +1 8 800установок flutter-dart-code-review affaan-m Скилл flutter-dart-code-review для Claude Code даёт чек-лист ревью Flutter/Dart-кода по виджетам, состоянию, идиомам, производительности и безопасности. CX Codex +1 6 600установок dart-3-updates Ivanna Kaceviča Скилл dart-3-updates для Claude Code и Codex учит ИИ писать switch-выражения, паттерны, records и modern Dart вместо старых if-else цепочек. Помогает при рефакторинге кода под Dart 3 и выборе между records и классами. CX Codex +1 ★ 674звёзд репо effective-dart Ivanna Kaceviča Скилл effective-dart задаёт правила чистого кода на Dart и Flutter: стиль имён, явные типы, оформление документации и структуру тестов. CX Codex +1 ★ 674звёзд репо

Из того же набора9

dart-best-practices Скилл dart-best-practices задаёт правила оформления кода на Dart при генерации и ревью. Помогает форматировать многострочные блоки и соблюдать лимит длины строки в 80 знаков. CX Codex +1 847установок dart-test-fundamentals Скилл dart-test-fundamentals для Claude Code и Codex задаёт стандарты работы с библиотекой package:test в Dart. Инструмент следит за структурой тестов, вызовами setUp и очисткой ресурсов через addTearDown. CX Codex +1 455установок dart-modern-features Скилл dart-modern-features обучает агента современному синтаксису Dart версий 3.0–3.10. Он помогает безопасно внедрять записи, extension types и модификаторы классов при рефакторинге. CX Codex +1 370установок dart-doc-validation Скилл dart-doc-validation учит агента проверять комментарии документации в Dart-коде командой dart doc и включать линт comment_references, чтобы ловить битые ссылки на классы, методы и макросы. CX Codex +1 291установок dart-package-maintenance Скилл dart-package-maintenance для Claude Code помогает вести Dart-пакеты: следить за версиями, синхронизировать CHANGELOG и управлять релизами. Описывает поддержку пакетов на pub.dev. CX Codex +1 285установок dart-test-coverage Скилл dart-test-coverage для Claude Code запускает сбор покрытия Dart-пакета, разбирает пропущенные строки и помогает наметить тесты. Помогает выявить непроверенный код в lib/. CX Codex +1 163установок dart-long-lines Скилл dart-long-lines для Claude Code помогает соблюдать лимит в 80 символов в строках Dart. Он подключается при написании и рефакторинге кода под lint lines_longer_than_80_chars. CX Codex +1 150установок dart-multiline-strings Скилл dart-multiline-strings для Claude Code учит переписывать цепочки print() и конкатенации в тройные кавычки. Запускается при рефакторинге CLI-вывода, шаблонных сообщений и многострочных блоков в Dart. CX Codex +1 116установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой