dart-test-fundamentals

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.

  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.