How to Run ATDD with TEA

How to Run ATDD with TEA

Use TEA’s atdd workflow to generate red-phase acceptance test scaffolds BEFORE implementation. TEA currently emits these scaffolds with test.skip() so they can be reviewed, linked into the story, and activated task-by-task during implementation.

When to Use This

• You’re about to implement a NEW feature (feature doesn’t exist yet)
• You want to follow TDD workflow (red → green → refactor)
• You want tests to guide your implementation
• You’re practicing acceptance test-driven development

Don’t use this if:

• Feature already exists (use automate instead)
• You want tests that pass immediately

Prerequisites

• BMad Method installed
• TEA agent available
• Test framework setup complete (run framework if needed)
• Story or feature defined with acceptance criteria

Note: This guide uses Playwright examples. If using Cypress, commands and syntax will differ (e.g., cy.get() instead of page.locator()).

Steps

1. Load TEA Agent

Start a fresh chat and load TEA:

tea

2. Run the ATDD Workflow

atdd

3. Provide Context

TEA will ask for:

Story/Feature Details:

We're adding a user profile page where users can:
- View their profile information
- Edit their name and email
- Upload a profile picture
- Save changes with validation

Acceptance Criteria:

Given I'm logged in
When I navigate to /profile
Then I see my current name and email

Given I'm on the profile page
When I click "Edit Profile"
Then I can modify my name and email

Given I've edited my profile
When I click "Save"
Then my changes are persisted
And I see a success message

Given I upload an invalid file type
When I try to save
Then I see an error message
And changes are not saved

Reference Documents (optional):

• Point to your story file
• Reference PRD or tech spec
• Link to test design (if you ran test-design first)

4. Specify Test Levels

TEA will ask what test levels to generate:

Options:

• E2E tests (browser-based, full user journey)
• API tests (backend only, faster)
• Component tests (UI components in isolation)
• Mix of levels (see API Tests First, E2E Later tip)

Component Testing by Framework

TEA generates component tests using framework-appropriate tools:

Your Framework	Component Testing Tool
Cypress	Cypress Component Testing (*.cy.tsx)
Playwright	Vitest + React Testing Library (*.test.tsx)

Example response:

Generate:
- API tests for profile CRUD operations
- E2E tests for the complete profile editing flow
- Component tests for ProfileForm validation (if using Cypress or Vitest)
- Focus on P0 and P1 scenarios

5. Review Generated Tests

TEA generates red-phase test scaffolds in appropriate directories:

API Tests (tests/api/profile.spec.ts):

Vanilla Playwright:

import { test, expect } from '@playwright/test';

test.describe('Profile API', () => {
  test.skip('should fetch user profile', async ({ request }) => {
    const response = await request.get('/api/profile');

    expect(response.status()).toBe(200);
    const profile = await response.json();
    expect(profile).toHaveProperty('name');
    expect(profile).toHaveProperty('email');
    expect(profile).toHaveProperty('avatarUrl');
  });

  test.skip('should update user profile', async ({ request }) => {
    const response = await request.patch('/api/profile', {
      data: {
        name: 'Updated Name',
        email: 'updated@example.com',
      },
    });

    expect(response.status()).toBe(200);
    const updated = await response.json();
    expect(updated.name).toBe('Updated Name');
    expect(updated.email).toBe('updated@example.com');
  });

  test.skip('should validate email format', async ({ request }) => {
    const response = await request.patch('/api/profile', {
      data: {
        email: 'invalid-email',
      },
    });

    expect(response.status()).toBe(400);
    const error = await response.json();
    expect(error.message).toContain('Invalid email format');
  });
});

With Playwright Utils:

import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
import { expect } from '@playwright/test';
import { z } from 'zod';

const ProfileSchema = z.object({
  name: z.string(),
  email: z.string().email(),
  avatarUrl: z.string().url(),
});

test.describe('Profile API', () => {
  test.skip('should fetch user profile', async ({ apiRequest }) => {
    const { status, body } = await apiRequest({
      method: 'GET',
      path: '/api/profile',
    }).validateSchema(ProfileSchema); // Chained validation

    expect(status).toBe(200);
    // Schema already validated, type-safe access
    expect(body.name).toBeDefined();
    expect(body.email).toContain('@');
  });

  test.skip('should update user profile', async ({ apiRequest }) => {
    const { status, body } = await apiRequest({
      method: 'PATCH',
      path: '/api/profile',
      body: {
        name: 'Updated Name',
        email: 'updated@example.com',
      },
    }).validateSchema(ProfileSchema); // Chained validation

    expect(status).toBe(200);
    expect(body.name).toBe('Updated Name');
    expect(body.email).toBe('updated@example.com');
  });

  test.skip('should validate email format', async ({ apiRequest }) => {
    const { status, body } = await apiRequest({
      method: 'PATCH',
      path: '/api/profile',
      body: { email: 'invalid-email' },
    });

    expect(status).toBe(400);
    expect(body.message).toContain('Invalid email format');
  });
});

Key Benefits:

• Returns { status, body } (cleaner than response.status() + await response.json())
• Automatic schema validation with Zod
• Type-safe response bodies
• Automatic retry for 5xx errors
• Less boilerplate

E2E Tests (tests/e2e/profile.spec.ts):

import { test, expect } from '@playwright/test';

test.skip('should edit and save profile', async ({ page }) => {
  // Login first
  await page.goto('/login');
  await page.getByLabel('Email').fill('test@example.com');
  await page.getByLabel('Password').fill('password123');
  await page.getByRole('button', { name: 'Sign in' }).click();

  // Navigate to profile
  await page.goto('/profile');

  // Edit profile
  await page.getByRole('button', { name: 'Edit Profile' }).click();
  await page.getByLabel('Name').fill('Updated Name');
  await page.getByRole('button', { name: 'Save' }).click();

  // Verify success
  await expect(page.getByText('Profile updated')).toBeVisible();
});

TEA generates additional E2E tests for display, validation errors, etc. based on acceptance criteria.

Implementation Checklist

TEA also provides an implementation checklist:

## Implementation Checklist

### Backend

- [ ] Create `GET /api/profile` endpoint
- [ ] Create `PATCH /api/profile` endpoint
- [ ] Add email validation middleware
- [ ] Add profile picture upload handling
- [ ] Write API unit tests

### Frontend

- [ ] Create ProfilePage component
- [ ] Implement profile form with validation
- [ ] Add file upload for avatar
- [ ] Handle API errors gracefully
- [ ] Add loading states

### Tests

- [x] API test scaffolds generated (`test.skip()`)
- [x] E2E test scaffolds generated (`test.skip()`)
- [ ] Activate and run tests during implementation (should fail before code changes, then pass)

6. Verify Red-Phase Scaffolds

This is the TDD red phase, but TEA keeps generated tests in test.skip() until you’re ready to work on a task. Review the generated files, then remove test.skip() for the current task and confirm that the newly activated test fails before you implement the feature.

For Playwright:

npx playwright test

For Cypress:

npx cypress run

Initial output with scaffolds still skipped:

Running 6 tests using 1 worker

  - tests/api/profile.spec.ts:3:3 › should fetch user profile
  - tests/api/profile.spec.ts:15:3 › should update user profile
  - tests/e2e/profile.spec.ts:10:3 › should edit and save profile

  6 skipped

After you remove test.skip() from the task you are implementing, that activated test should fail first. This confirms:

• Feature doesn’t exist yet
• Tests will guide implementation
• You have clear success criteria

7. Implement the Feature

Now implement the feature following the test guidance:

1. Start with API tests (backend first)
2. Remove test.skip() from the first API test and confirm RED
3. Implement until that test passes
4. Move to the next API or E2E test and repeat
5. Refactor with confidence (tests protect you)

8. Verify Tests Pass

After implementation, run your test suite.

For Playwright:

npx playwright test

For Cypress:

npx cypress run

Expected output:

Running 6 tests using 1 worker

  ✓ tests/api/profile.spec.ts:3:3 › should fetch user profile (850ms)
  ✓ tests/api/profile.spec.ts:15:3 › should update user profile (1.2s)
  ✓ tests/api/profile.spec.ts:30:3 › should validate email format (650ms)
  ✓ tests/e2e/profile.spec.ts:10:3 › should display current profile (2.1s)
  ✓ tests/e2e/profile.spec.ts:18:3 › should edit and save profile (3.2s)
  ✓ tests/e2e/profile.spec.ts:35:3 › should show validation error (1.8s)

  6 passed (9.8s)

Green! You’ve completed the active red → green → refactor cycle for the generated scaffolds.

What You Get

Red-Phase Test Scaffolds

• API tests for backend endpoints
• E2E tests for user workflows
• Component tests (if requested)
• Generated with test.skip() until you activate them task-by-task

Implementation Guidance

• Clear checklist of what to build
• Acceptance criteria translated to assertions
• Edge cases and error scenarios identified

TDD Workflow Support

• Activated tests guide implementation
• Confidence to refactor
• Living documentation of features

Tips

Start with Test Design

Run test-design before atdd for better results:

test-design   # Risk assessment and priorities
atdd          # Generate tests based on design

Browser Automation (Optional)

If browser automation is configured (tea_browser_automation: "auto" or "cli" or "mcp"), TEA can verify selectors against live browsers during atdd.

• CLI mode: Takes snapshots to verify element names and roles before generating selectors
• MCP mode: Full browser automation for complex UI interactions
• Auto mode: Uses CLI for simple verification, MCP for complex flows

Note: ATDD is for features that don’t exist yet, so browser verification only applies if you have skeleton/mockup UI already implemented. For typical ATDD (no UI yet), TEA infers selectors from best practices.

See Configure Browser Automation for setup.

Focus on P0/P1 Scenarios

Don’t generate tests for everything at once:

Generate tests for:
- P0: Critical path (happy path)
- P1: High value (validation, errors)

Skip P2/P3 for now - add later with automate

API Tests First, E2E Later

Recommended order:

1. Generate API tests with atdd
2. Implement backend (make API tests pass)
3. Generate E2E tests with atdd (or automate)
4. Implement frontend (make E2E tests pass)

This “outside-in” approach is faster and more reliable.

Keep Tests Deterministic

TEA generates deterministic tests by default:

• No hard waits (waitForTimeout)
• Network-first patterns (wait for responses)
• Explicit assertions (no conditionals)

Don’t modify these patterns - they prevent flakiness!

Related Guides

• How to Run Test Design - Plan before generating
• How to Run Automate - Tests for existing features
• How to Set Up Test Framework - Initial setup

Understanding the Concepts

• Testing as Engineering - Why TEA generates quality tests (foundational)
• Risk-Based Testing - Why P0 vs P3 matters
• Test Quality Standards - What makes tests good
• Network-First Patterns - Avoiding flakiness

Reference

• Command: *atdd - Full command reference
• TEA Configuration - MCP and Playwright Utils options

---

Generated with BMad Method - TEA (Test Engineering Architect)