Test-Driven Development

Build features with strict red-green-refactor discipline using the /flutter-tdd skill. This playbook walks through a vertical-slice TDD cycle from start to finish.

Scenario

You need to add a new feature (e.g., a CartRepository with add, remove, and total calculation) and you want every line of implementation to be driven by a failing test first.

Prerequisites

• ACT Pro installed and verified (/act:help)
• A Flutter project with an existing test setup (flutter test runs successfully)
• Familiarity with the Workflow Overview

Why vertical-slice TDD matters

Left unchecked, LLMs default to writing all tests at once and then all implementation at once. This produces tests that pass by construction rather than by verification. The /flutter-tdd skill enforces one test at a time: write a single failing test, make it pass with the minimal implementation, refactor, then move to the next test.

Steps

1. Start the TDD skill

/flutter-tdd

The skill loads TDD rules and prompts you for context about the feature you want to build.

2. Describe the first behavior

Tell the AI what the first thin slice of behavior should be:

"CartRepository.addItem adds a single item to an empty cart"

The AI writes one failing test:

test('addItem adds a single item to an empty cart', () {
  final repo = CartRepository();
  repo.addItem(Item(id: '1', name: 'Widget', price: 9.99));
  expect(repo.items, hasLength(1));
});

3. Confirm the test fails (RED)

The AI runs flutter test and confirms the test fails because CartRepository does not exist yet. This is the red phase — the test must fail for the right reason.

4. Write the minimal implementation (GREEN)

The AI writes just enough code to make the test pass:

class CartRepository {
  final List<Item> _items = [];
  List<Item> get items => List.unmodifiable(_items);

  void addItem(Item item) {
    _items.add(item);
  }
}

It runs flutter test again and confirms the test passes.

5. Refactor if needed

With the test green, the AI evaluates whether the code needs cleanup. If so, it refactors while keeping the test green. If the code is already clean, it moves on.

6. Repeat for the next slice

Describe the next behavior:

"CartRepository.removeItem removes an item by ID"

The cycle repeats: one failing test, minimal implementation, refactor. Each cycle produces a commit in a working state.

7. Continue until the feature is complete

Typical slices for a cart feature might be:

1. Add a single item
2. Remove an item by ID
3. Calculate total price
4. Handle duplicate items (increment quantity)
5. Clear the cart

Each slice is a self-contained red-green-refactor cycle with its own commit.

Expected output

• One test file and one implementation file growing incrementally
• A sequence of small, passing commits (one per TDD cycle)
• flutter analyze and flutter test pass after every cycle
• A clear git history showing the progression from empty to complete

Common pitfalls

• Batching tests — If the AI tries to write multiple tests at once, remind it: “One test at a time. Follow /flutter-tdd discipline.”
• Writing implementation before the test — The test must fail before any production code is written. If the AI skips ahead, ask it to delete the implementation and start with the test.
• Over-engineering the minimal implementation — The green phase should be the simplest code that passes. Optimization belongs in the refactor phase.
• Skipping the red phase — If a test passes immediately, it is not testing new behavior. The AI should write a test that actually fails first.

Next steps

• Combine TDD with the Robot Testing playbook for user-journey-level tests
• Use /act:workflow:plan to generate a plan with TDD: task prefixes, then execute with /act:workflow:work
• Read the Add a Feature playbook for the full spec-plan-work cycle