git:20261016.29932fe to git:20261017.ce6cdbd

---

name: dart-test-fundamentals

description: |-

Core concepts and best practices for `package:test`.

Covers `test`, `group`, lifecycle methods (`setUp`, `tearDown`), and

configuration (`dart_test.yaml`).

license: Apache-2.0

key_features:

- Package test core concepts

- Test lifecycle (setUp, tearDown)

- dart_test.yaml configuration

---

# Dart Test Fundamentals

## When to use this skill

Use this skill when:

- Writing new test files.

- Structuring test suites with `group`.

- Configuring test execution via `dart_test.yaml`.

- Understanding test lifecycle methods.

### When NOT to use (Abstention Guardrails)

Do NOT apply this skill or refactor existing tests when:

- **Legacy Single-Group Churn**: Do NOT remove or reformat existing `group`

hierarchies in untouched existing tests unless explicitly asked, as this

causes unwanted diff churn.

- **Alternative Assertion Frameworks**: The package has migrated to

`package:checks` or a specialized testing framework; do not revert tests back

to legacy `package:matcher` idioms.

- **Trivial Tests with Zero Setup**: Simple standalone tests with no shared

state or resources do not need `group`, `setUp`, or `addTearDown`. Do not add

ceremonial wrapper boilerplate.

## Discovery

To find candidates for improving test structure:

### `try-finally` Cleanup

Search for tests that use `try-finally` for cleanup instead of `addTearDown`:

- **Regex**: `\bfinally\s*\{` (Check if this is used for resource cleanup inside

a test).

## Core Concepts

### 1. Test Structure (`test` and `group`)

- **`test`**: The fundamental unit of testing.

```dart

test('description', () {

// assertions

});

```

- **`group`**: Used to organize tests into logical blocks.

- Groups can be nested.

- Descriptions are concatenated (e.g., "Group Description Test Description").

- Helps scope `setUp` and `tearDown` calls.

- **Naming**: Use `PascalCase` for groups that correspond to a class name

(e.g., `group('MyClient', ...)`).

- **Avoid Single Groups**: Do not wrap all tests in a file with a single

`group` call if it's the only one.

- **NOTE**: DO NOT remove groups when doing a cleanup on existing code you

didn't create unless explicitly asked to. This can cause a LOT of churn in

the DIFF that most engineers won't want!

- **Naming Tests** `test('test name here',`:

- Avoid redundant "test" prefixes. Use `group` instead.

- Include the expected behavior or outcome in the description (e.g.,

`'throws StateError'` or `'adds API key to URL'`).

- Descriptions should read well when concatenated with their group name.

- **Named Parameters Placement**:

- For `test` and `group` calls, place named parameters (e.g., `testOn`,

`timeout`, `skip`) immediately after the description string, before the

callback closure. This improves readability by keeping the test logic last.

```dart

test('description', testOn: 'vm', () {

// assertions

});

```

### 2. Lifecycle Methods (`setUp`, `tearDown`)

- **`setUp`**: Runs _before_ every `test` in the current `group` (and nested

groups).

- **`tearDown`**: Runs _after_ every `test` in the current `group`.

- **`setUpAll`**: Runs _once_ before any test in the group.

- **`tearDownAll`**: Runs _once_ after all tests in the group.

**Best Practice:**

- Use `setUp` for resetting state to ensure test isolation.

- Avoid sharing mutable state between tests without resetting it.

### 3. Cleaning Up Resources

- To clean up resources created WITHIN the `test` body, consider using

`addTearDown` instead of a `try-finally` block.

**Avoid:**

```dart

test('can create and delete a file', () {

final file = File('temp.txt');

try {

file.writeAsStringSync('hello');

expect(file.readAsStringSync(), 'hello');

} finally {

if (file.existsSync()) file.deleteSync();

}

});

```

**Prefer:**

```dart

test('can create and delete a file', () {

final file = File('temp.txt');

// Register teardown immediately after resource creation intent

addTearDown(() {

if (file.existsSync()) file.deleteSync();

});

file.writeAsStringSync('hello');

expect(file.readAsStringSync(), 'hello');

});

```

### 4. Configuration (`dart_test.yaml`)

The `dart_test.yaml` file configures the test runner. Common configurations

include:

#### Platforms

Define where tests run (vm, chrome, node).

```yaml

platforms:

- vm

- chrome

```

#### Tags

Categorize tests to run specific subsets.

```yaml

tags:

integration:

timeout: 2x

```

Usage in code:

```dart

@Tags(['integration'])

import 'package:test/test.dart';

```

Running tags: `dart test --tags integration`

#### Timeouts

Set default timeouts for tests.

```yaml

timeouts:

2x # Double the default timeout

```

### 5. File Naming

- Test files **must** end in `_test.dart` to be picked up by the test runner.

- Place tests in the `test/` directory.

### 6. Test Design, Seams & Real Test Doubles

- **Behavioral, Structural & Relational Assertions (No Change-Detector Tests)**:

testing live catalogs, JSON datasets, registries, or canonical templates

that evolve independently of logic, assert **structural validity and

## Common commands

- `dart test`: Run all tests.

- `dart test test/path/to/file_test.dart`: Run a specific file.

- `dart test --name "substring"`: Run tests matching a description.

## Related Skills

`dart-test-fundamentals` is the core skill for structuring and configuring

tests. For writing assertions within those tests, refer to:

- **[dart-matcher-best-practices]**: Use this if the project sticks with the

traditional `package:matcher` (`expect` calls).

[dart-matcher-best-practices]:

https://github.com/kevmoo/dash_skills/blob/main/skills/dart-matcher-best-practices/SKILL.md