skills.rest
Wishtohear
WishtohearCOMMUNITY
Explore all skills by this author →
GitHub

dart-matcher-best-practices

Guides readable test assertions using expect and package:matcher in Dart.

1|Updated Apr 30, 2026
Search Tags:#unit tests#testing#flutter#dart#assertions#matcher#expect
One-click install
npx skills add https://github.com/Wishtohear/bucket-water-oms --skill dart-matcher-best-practices-wishtohear
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: dart-matcher-best-practices
Source: https://github.com/Wishtohear/bucket-water-oms/tree/main/bucket-water-oms-admin-mobile/tool/dart_skills_lint/.agents/skills/dart-matcher-best-practices
Command: npx skills add https://github.com/Wishtohear/bucket-water-oms --skill dart-matcher-best-practices-wishtohear

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Writing Dart tests with manual boolean checks produces confusing failure messages and hard-to-maintain assertions. This Skill provides best practices for using expect and package:matcher so test failures clearly show what went wrong. ## Core Features & Use Cases - Matcher Selection Guidance: Recommends the most specific matcher for each scenario, such as hasLength, containsPair, unorderedEquals, and isA<T>, instead of manual property checks. - Property Assertions with .having(): Shows how to chain .having() on type matchers to verify object properties with descriptive failure output. - Async Assertion Patterns: Covers completion, throwsA, and expectLater to avoid race conditions when testing futures and streams. - Use Case: When a test like expect(list.isEmpty, true) fails with an unhelpful message, apply this Skill to rewrite it as expect(list, isEmpty) and get a failure message showing the actual list contents. ## Quick Start Review my Dart test file and rewrite the assertions to use proper package:matcher matchers with clearer failure messages.

Frequently Asked Questions about dart-matcher-best-practices

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write better assertions with package:matcher in Dart?▼

Use the most specific matcher available instead of manual boolean checks. For example, write expect(list, hasLength(3)) instead of expect(list.length, 3), and expect(map, containsPair('key', value)) instead of checking keys individually, so failures show actual content.

How do I test that a Future throws an exception in Dart?▼

Use await expectLater(future, throwsA(isA<StateError>())) to verify a future completes with an error. For synchronous functions, expect(() => fn(), throwsA(isA<ArgumentError>())) works directly with expect.

What is the difference between isA and TypeMatcher in Dart tests?▼

isA<T>() is preferred for concise inline assertions and supports chaining .having() for property checks. TypeMatcher<T> is better for reusable top-level matchers, which can be declared as const for performance.

Why does my async Dart test check side effects before the future completes?▼

Using expect instead of await expectLater lets the test continue before the future finishes, causing race conditions. Always await expectLater(future, completion(...)) before asserting on side effects.

When should I migrate from package:matcher to package:checks?▼

Consider migrating when starting new test suites that benefit from the modern checks API. For existing matcher-based tests, follow the dart-checks-migration guidance referenced in the related skills section.

Related Skills

Explore More Software Engineering Skills→
kevmookevmoo
139

dart-test-fundamentals

Teach Dart package:test fundamentals including test, group, and lifecycle methods.

Community
Basic
flutterflutter
178.3k

dart-log-failure-parser

Parse Dart and Flutter test logs to detect and summarize failure patterns.

Official
Intermediate
yash-gargyash-garg

dart-migrate-to-checks-package

Migrate Dart test assertions from package:matcher to package:checks syntax.

Community
Advanced
elbwalkerelbwalker
342

walkeros-understanding-sources

Explain how walkerOS sources capture events from browser, dataLayer, and server.

Official
Basic