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.

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.

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