bmad-template/.workbuddy/skills/bmad-testarch-atdd/atdd-checklist-template.md

---
stepsCompleted: []
lastStep: ''
lastSaved: ''
workflowType: 'testarch-atdd'
storyId: '{story_id}'
storyKey: '{story_key}'
storyFile: '{story_file}'
atddChecklistPath: '{test_artifacts}/atdd-checklist-{story_key}.md'
generatedTestFiles:
  - '{api_test_file_path}'
  - '{e2e_test_file_path}'
  - '{component_test_file_path}'
inputDocuments: []
---

# 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}

---

## Story Integration Metadata

- **Story ID:** `{story_id}`
- **Story Key:** `{story_key}`
- **Story File:** `{story_file}`
- **Checklist Path:** `{test_artifacts}/atdd-checklist-{story_key}.md`
- **Generated Test Files:** `{e2e_test_file_path}`, `{api_test_file_path}`, `{component_test_file_path}`

If this story came from BMM `create-story`, mirror these artifact paths into the story's `Dev Notes` so `dev-story` can discover and activate the red-phase scaffolds.

---

## Red-Phase Test Scaffolds Created

### 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:**

```typescript
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:**

```typescript
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:**

```json
{
  {success_response_example}
}
```

**Failure Response:**

```json
{
  {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:**

```tsx
<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 scaffolded 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

```bash
# Run all activated 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 as red-phase scaffolds with `test.skip()`
- ✅ Fixtures and factories created with auto-cleanup
- ✅ Mock requirements documented
- ✅ data-testid requirements listed
- ✅ Implementation checklist created

**Verification:**

- All generated tests are present and marked with `test.skip()`
- Activation guidance is clear and actionable
- Any activated test fails due to missing implementation, not test bugs

---

### GREEN Phase (DEV Team - Next Steps)

**DEV Agent Responsibilities:**

1. **Pick one scaffolded test** from implementation checklist (start with highest priority)
2. **Remove `test.skip()`** for that test and confirm it fails first
3. **Read the test** to understand expected behavior
4. **Implement minimal code** to make that specific test pass
5. **Run the test** to verify it now passes (green)
6. **Check off the task** in implementation checklist
7. **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

---

### 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. **Link this checklist and generated tests** into the story file `Dev Notes` / `ATDD Artifacts` section when a writable story file is available
2. **If the story file cannot be updated automatically**, share this checklist and generated tests with the dev workflow as a manual handoff
3. **Review this checklist** with team in standup or planning
4. **Begin implementation** using implementation checklist as guide
5. **Activate one scaffold at a time** by removing `test.skip()` for the current task, then confirm it fails before implementing
6. **Work one activated test at a time** (red → green for each)
7. **Share progress** in daily standup
8. **When all activated tests pass**, refactor code for quality
9. **When refactoring complete**, manually update story status to 'done' in sprint-status.yaml

---

## 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 Scaffold Review / RED Verification

**Command:** `{test_command_all}` (or a narrower command after removing `test.skip()` for the current task)

**Results:**

```
{paste_test_run_output_showing_scaffolds_skipped_or_activated_tests_failing}
```

**Summary:**

- Total tests: {total_test_count}
- Skipped: {total_test_count} (expected before activation)
- Activated RED tests: {activated_test_count} (expected after activation, before implementation)
- Passing: 0 before implementation (expected for activated tests)
- Status: ✅ Red-phase scaffolds verified

**Expected Failure Messages:**
{list_expected_skip_or_failure_states_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 `./bmm/docs/tea-README.md` for workflow documentation
- Consult `./resources/knowledge` for testing best practices

---

**Generated by BMad TEA Agent** - {date}