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.

Core Concepts

1. Test Structure (

test

and

group

)

• test

  : The fundamental unit of testing.

  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.

    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:

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:

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).

platforms:
  - vm
  - chrome

Tags

Categorize tests to run specific subsets.

tags:
  integration:
    timeout: 2x

Usage in code:

@Tags(['integration'])
import 'package:test/test.dart';

Running tags:

dart test --tags integration

Timeouts

Set default timeouts for tests.

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.

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-checks-migration: Use this if the project is migrating to the modern

  package:checks

  (

  check

  calls).