BMAD-METHOD/bmad/bmm/workflows/testarch/atdd/atdd-checklist-template.md

ATDD Checklist - Epic {epic_num}, Story {story_num}: {story_title}

Date: {date} Author: {user_name} Primary Test Level: {primary_level}

---

Story Summary

{Brief 2-3 sentence summary of the user story}

As a {user_role} I want {feature_description} So that {business_value}

---

Acceptance Criteria

{List all testable acceptance criteria from the story}

1. {Acceptance criterion 1}
2. {Acceptance criterion 2}
3. {Acceptance criterion 3}

---

Failing Tests Created (RED Phase)

E2E Tests ({e2e_test_count} tests)

File: {e2e_test_file_path} ({line_count} lines)

{List each E2E test with its current status and expected failure reason}

• ✅ Test: {test_name}
  • Status: RED - {failure_reason}
  • Verifies: {what_this_test_validates}

API Tests ({api_test_count} tests)

File: {api_test_file_path} ({line_count} lines)

{List each API test with its current status and expected failure reason}

• ✅ Test: {test_name}
  • Status: RED - {failure_reason}
  • Verifies: {what_this_test_validates}

Component Tests ({component_test_count} tests)

File: {component_test_file_path} ({line_count} lines)

{List each component test with its current status and expected failure reason}

• ✅ Test: {test_name}
  • Status: RED - {failure_reason}
  • Verifies: {what_this_test_validates}

---

Data Factories Created

{List all data factory files created with their exports}

{Entity} Factory

File: tests/support/factories/{entity}.factory.ts

Exports:

• create{Entity}(overrides?) - Create single entity with optional overrides
• create{Entity}s(count) - Create array of entities

Example Usage:

const user = createUser({ email: 'specific@example.com' });
const users = createUsers(5); // Generate 5 random users

---

Fixtures Created

{List all test fixture files created with their fixture names and descriptions}

{Feature} Fixtures

File: tests/support/fixtures/{feature}.fixture.ts

Fixtures:

• {fixtureName} - {description_of_what_fixture_provides}
  • Setup: {what_setup_does}
  • Provides: {what_test_receives}
  • Cleanup: {what_cleanup_does}

Example Usage:

import { test } from './fixtures/{feature}.fixture';

test('should do something', async ({ {fixtureName} }) => {
  // {fixtureName} is ready to use with auto-cleanup
});

---

Mock Requirements

{Document external services that need mocking and their requirements}

{Service Name} Mock

Endpoint: {HTTP_METHOD} {endpoint_url}

Success Response:

{
  {success_response_example}
}

Failure Response:

{
  {failure_response_example}
}

Notes: {any_special_mock_requirements}

---

Required data-testid Attributes

{List all data-testid attributes required in UI implementation for test stability}

{Page or Component Name}

• {data-testid-name} - {description_of_element}
• {data-testid-name} - {description_of_element}

Implementation Example:

<button data-testid="login-button">Log In</button>
<input data-testid="email-input" type="email" />
<div data-testid="error-message">{errorText}</div>

---

Implementation Checklist

{Map each failing test to concrete implementation tasks that will make it pass}

Test: {test_name_1}

File: {test_file_path}

Tasks to make this test pass:

• {Implementation task 1}
• {Implementation task 2}
• {Implementation task 3}
• Add required data-testid attributes: {list_of_testids}
• Run test: {test_execution_command}
• ✅ Test passes (green phase)

Estimated Effort: {effort_estimate} hours

---

Test: {test_name_2}

File: {test_file_path}

Tasks to make this test pass:

• {Implementation task 1}
• {Implementation task 2}
• {Implementation task 3}
• Add required data-testid attributes: {list_of_testids}
• Run test: {test_execution_command}
• ✅ Test passes (green phase)

Estimated Effort: {effort_estimate} hours

---

Running Tests

# Run all failing tests for this story
{test_command_all}

# Run specific test file
{test_command_specific_file}

# Run tests in headed mode (see browser)
{test_command_headed}

# Debug specific test
{test_command_debug}

# Run tests with coverage
{test_command_coverage}

---

Red-Green-Refactor Workflow

RED Phase (Complete) ✅

TEA Agent Responsibilities:

• ✅ All tests written and failing
• ✅ Fixtures and factories created with auto-cleanup
• ✅ Mock requirements documented
• ✅ data-testid requirements listed
• ✅ Implementation checklist created

Verification:

• All tests run and fail as expected
• Failure messages are clear and actionable
• Tests fail due to missing implementation, not test bugs

---

GREEN Phase (DEV Team - Next Steps)

DEV Agent Responsibilities:

1. Pick one failing test from implementation checklist (start with highest priority)
2. Read the test to understand expected behavior
3. Implement minimal code to make that specific test pass
4. Run the test to verify it now passes (green)
5. Check off the task in implementation checklist
6. Move to next test and repeat

Key Principles:

• One test at a time (don't try to fix all at once)
• Minimal implementation (don't over-engineer)
• Run tests frequently (immediate feedback)
• Use implementation checklist as roadmap

Progress Tracking:

• Check off tasks as you complete them
• Share progress in daily standup
• Mark story as IN PROGRESS in bmm-workflow-status.md

---

REFACTOR Phase (DEV Team - After All Tests Pass)

DEV Agent Responsibilities:

1. Verify all tests pass (green phase complete)
2. Review code for quality (readability, maintainability, performance)
3. Extract duplications (DRY principle)
4. Optimize performance (if needed)
5. Ensure tests still pass after each refactor
6. Update documentation (if API contracts change)

Key Principles:

• Tests provide safety net (refactor with confidence)
• Make small refactors (easier to debug if tests fail)
• Run tests after each change
• Don't change test behavior (only implementation)

Completion:

• All tests pass
• Code quality meets team standards
• No duplications or code smells
• Ready for code review and story approval

---

Next Steps

1. Review this checklist with team in standup or planning
2. Run failing tests to confirm RED phase: {test_command_all}
3. Begin implementation using implementation checklist as guide
4. Work one test at a time (red → green for each)
5. Share progress in daily standup
6. When all tests pass, refactor code for quality
7. When refactoring complete, run bmad sm story-done to move story to DONE

---

Knowledge Base References Applied

This ATDD workflow consulted the following knowledge fragments:

• fixture-architecture.md - Test fixture patterns with setup/teardown and auto-cleanup using Playwright's test.extend()
• data-factories.md - Factory patterns using @faker-js/faker for random test data generation with overrides support
• component-tdd.md - Component test strategies using Playwright Component Testing
• network-first.md - Route interception patterns (intercept BEFORE navigation to prevent race conditions)
• test-quality.md - Test design principles (Given-When-Then, one assertion per test, determinism, isolation)
• test-levels-framework.md - Test level selection framework (E2E vs API vs Component vs Unit)

See tea-index.csv for complete knowledge fragment mapping.

---

Test Execution Evidence

Initial Test Run (RED Phase Verification)

Command: {test_command_all}

Results:

{paste_test_run_output_showing_all_tests_failing}

Summary:

• Total tests: {total_test_count}
• Passing: 0 (expected)
• Failing: {total_test_count} (expected)
• Status: ✅ RED phase verified

Expected Failure Messages: {list_expected_failure_messages_for_each_test}

---

Notes

{Any additional notes, context, or special considerations for this story}

• {Note 1}
• {Note 2}
• {Note 3}

---

Contact

Questions or Issues?

• Ask in team standup
• Tag @{tea_agent_username} in Slack/Discord
• Refer to testarch/README.md for workflow documentation
• Consult testarch/knowledge/ for testing best practices

---

Generated by BMad TEA Agent - {date}