Getting Started with Test Architect

Test Architect (TEA) Lite is the smallest useful slice of TEA: one workflow, automate, generating tests for features that already exist.

What You’ll Build

By the end of this 30-minute tutorial, you’ll have:

• A working Playwright test framework
• Your first risk-based test plan
• Passing tests for an existing demo app feature

Prerequisites

• Node.js installed (v20 or later)
• 30 minutes of focused time
• We’ll use TodoMVC (https://todomvc.com/examples/react/dist/) as our demo app

Quick Path

Load TEA (/bmad-tea or $bmad-tea) → scaffold framework (/bmad-testarch-framework) → create test plan (/bmad-testarch-test-design) → generate tests (/bmad-testarch-automate) → run with npx playwright test.

TEA Approaches Explained

There are three ways to use TEA:

• TEA Lite (this tutorial): just the automate workflow, to test existing features
• TEA Solo: TEA standalone, without full BMad Method integration
• TEA Integrated: full BMad Method with all TEA workflows across phases

Step 0: Setup (2 minutes)

We’ll test TodoMVC, a standard demo app used across testing documentation.

Demo App: https://todomvc.com/examples/react/dist/

TodoMVC runs in your browser with no installation. Open the link above and:

1. Add a few todos (type and press Enter)
2. Mark some as complete (click checkbox)
3. Try the “All”, “Active”, “Completed” filters

Those are the features you’ll test.

Step 1: Install BMad and Scaffold Framework (10 minutes)

Install BMad Method

npx bmad-method install

When prompted:

• Select modules: Choose “BMM: BMad Method” and “TEA: BMad Test Architect” (press Space on each, then Enter)
• Project name: Keep default or enter your project name
• Experience level: Choose “beginner” for this tutorial
• Planning artifacts folder: Keep default
• Implementation artifacts folder: Keep default
• Project knowledge folder: Keep default
• Enable TEA Playwright Model Context Protocol (MCP) enhancements? Choose “No” for now (we’ll explore this later)
• Using playwright-utils? Choose “No” for now (we’ll explore this later)

You’ll see a _bmad/ folder in your project.

Load TEA Agent

Start a new chat with your AI assistant and load the agent:

• Claude Code / Cursor / Windsurf: /bmad-tea
• Codex: $bmad-tea

This loads the Test Architect agent and displays TEA’s menu with available workflows.

Scaffold Test Framework

Run the framework setup workflow:

• Claude Code / Cursor / Windsurf: /bmad-testarch-framework
• Codex: $bmad-testarch-framework
• Inside a /bmad-tea chat: TF

TEA will ask you questions:

Q: What’s your tech stack? A: “We’re testing a React web application (TodoMVC)”

Q: Which test framework? A: “Playwright”

Q: Testing scope? A: “End-to-end (E2E) testing for a web application”

Q: Continuous integration/continuous deployment (CI/CD) platform? A: “GitHub Actions” (or your preference)

TEA will generate:

• tests/ directory with Playwright config
• playwright.config.ts with base configuration
• Sample test structure
• .env.example for environment variables
• .nvmrc for Node version

Verify the setup:

npm install
npx playwright install

You now have a production-ready test framework.

Step 2: Your First Test Design (5 minutes)

Test design is risk-based planning before any test is written.

Run Test Design

Run the test design workflow:

• Claude Code / Cursor / Windsurf: /bmad-testarch-test-design
• Codex: $bmad-testarch-test-design
• Inside a /bmad-tea chat: TD

Q: System-level or epic-level? A: “Epic-level - I want to test TodoMVC’s basic functionality”

Q: What feature are you testing? A: “TodoMVC’s core operations - creating, completing, and deleting todos”

Q: Any specific risks or concerns? A: “We want to ensure the filter buttons (All, Active, Completed) work correctly”

TEA will analyze and create test-design-epic-1.md with:

1. Risk Assessment

   • Probability × Impact scoring
   • Risk categories (TECH, SEC, PERF, DATA, BUS, OPS)
   • High-risk areas identified

2. Test Priorities

   • P0: Critical path (creating and displaying todos)
   • P1: High value (completing todos, filters)
   • P2: Medium value (deleting todos)
   • P3: Low value (edge cases)

3. Coverage Strategy

   • E2E tests for user workflows
   • Which scenarios need testing
   • Suggested test structure

Review the test design file. It records what needs testing and why, before any code is generated.

Step 3: Generate Tests for Existing Features (5 minutes)

TEA now generates tests based on your test design.

Run Automate

Run the automation workflow:

• Claude Code / Cursor / Windsurf: /bmad-testarch-automate
• Codex: $bmad-testarch-automate
• Inside a /bmad-tea chat: TA

Q: What are you testing? A: “TodoMVC React app at https://todomvc.com/examples/react/dist/ - focus on the test design we just created”

Q: Reference existing docs? A: “Yes, use test-design-epic-1.md”

Q: Any specific test scenarios? A: “Cover the P0 and P1 scenarios from the test design”

TEA will generate:

tests/e2e/todomvc.spec.ts with tests like:

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

test.describe('TodoMVC - Core Functionality', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('https://todomvc.com/examples/react/dist/');
  });

  test('should create a new todo', async ({ page }) => {
    // TodoMVC ships data-testid on every interactive element.
    const todoInput = page.getByTestId('text-input');
    await todoInput.fill('Buy groceries');
    await todoInput.press('Enter');

    await expect(page.getByTestId('todo-item')).toHaveText('Buy groceries');
  });

  test('should mark todo as complete', async ({ page }) => {
    const todoInput = page.getByTestId('text-input');
    await todoInput.fill('Complete tutorial');
    await todoInput.press('Enter');

    // todo-item-toggle is the checkbox. Assert its checked state, never a CSS class:
    // a class name is styling, and styling changes without the behavior changing.
    const toggle = page.getByTestId('todo-item-toggle');
    await toggle.check();

    await expect(toggle).toBeChecked();
  });

  test('should filter todos by status', async ({ page }) => {
    const todoInput = page.getByTestId('text-input');
    await todoInput.fill('Buy groceries');
    await todoInput.press('Enter');
    await todoInput.fill('Write tests');
    await todoInput.press('Enter');

    await page.getByTestId('todo-item-toggle').first().check();

    // The filters are real links, so getByRole survives markup changes.
    await page.getByRole('link', { name: 'Active' }).click();
    await expect(page.getByTestId('todo-item')).toHaveText(['Write tests']);

    await page.getByRole('link', { name: 'Completed' }).click();
    await expect(page.getByTestId('todo-item')).toHaveText(['Buy groceries']);
  });
});

TEA also creates:

• tests/README.md - How to run tests, project conventions
• Definition of Done summary - What makes a test “good”

With Playwright Utils (Optional Enhancement)

If you have tea_use_playwright_utils: true in your config, TEA generates tests using production-ready utilities:

Vanilla Playwright:

test('should mark todo as complete', async ({ page, request }) => {
  // Manual API call
  const response = await request.post('/api/todos', {
    data: { title: 'Complete tutorial' },
  });
  const todo = await response.json();

  await page.goto('/');
  const toggle = page.getByTestId('todo-item').filter({ hasText: todo.title }).getByTestId('todo-item-toggle');
  await toggle.check();
  await expect(toggle).toBeChecked();
});

With Playwright Utils:

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

test('should mark todo as complete', async ({ page, apiRequest }) => {
  // Typed API call with cleaner syntax
  const { status, body: todo } = await apiRequest({
    method: 'POST',
    path: '/api/todos',
    body: { title: 'Complete tutorial' },
  });

  expect(status).toBe(201);
  await page.goto('/');
  const toggle = page.getByTestId('todo-item').filter({ hasText: todo.title }).getByTestId('todo-item-toggle');
  await toggle.check();
  await expect(toggle).toBeChecked();
});

Benefits:

• Type-safe API responses ({ status, body })
• Automatic retry for 5xx errors
• Built-in schema validation
• Cleaner, more maintainable code

See Integrate Playwright Utils to enable this.

Step 4: Run and Validate (5 minutes)

Run the Tests

npx playwright test

You should see:

Running 3 tests using 1 worker

  ✓  1 [chromium] › tests/e2e/todomvc.spec.ts:8:7 › TodoMVC - Core Functionality › should create a new todo (648ms)
  ✓  2 [chromium] › tests/e2e/todomvc.spec.ts:17:7 › TodoMVC - Core Functionality › should mark todo as complete (295ms)
  ✓  3 [chromium] › tests/e2e/todomvc.spec.ts:30:7 › TodoMVC - Core Functionality › should filter todos by status (377ms)

  3 passed (1.9s)

The tests pass against the live TodoMVC app.

View Test Report

npx playwright show-report

The HTML report shows:

• Test execution timeline
• Screenshots (if any failures)
• Trace viewer for debugging

What Just Happened?

You used TEA Lite to:

1. Scaffold a production-ready test framework (/bmad-testarch-framework)
2. Create a risk-based test plan (/bmad-testarch-test-design)
3. Generate comprehensive tests (/bmad-testarch-automate)
4. Run tests against an existing application

What You Learned

Quick Reference

Action / Workflow	Claude Code / Cursor / Windsurf	Codex	Inside a /bmad-tea chat
Load TEA Agent	/bmad-tea	$bmad-tea	n/a
Scaffold Framework	/bmad-testarch-framework	$bmad-testarch-framework	TF
Test Design	/bmad-testarch-test-design	$bmad-testarch-test-design	TD
Automate (Generate Tests)	/bmad-testarch-automate	$bmad-testarch-automate	TA

TEA Principles

• Risk-based testing: depth scales with impact (P0 vs P3)
• Test design first: plan before generating
• Network-first patterns: tests wait for actual responses, with no hard waits
• Production-ready from day one: real patterns, not toy examples

Key Takeaway

TEA Lite (just automate) is perfect for beginners learning TEA fundamentals, testing existing applications, quick test coverage expansion, and teams wanting fast results.

Understanding ATDD vs Automate

This tutorial used the automate workflow to generate tests for existing features (tests pass immediately).

When to use automate:

• Feature already exists
• Want to add test coverage
• Tests should pass on first run

When to use atdd (Acceptance Test-Driven Development):

• Feature doesn’t exist yet (Test-Driven Development workflow)
• Want failing tests BEFORE implementation
• Following red → green → refactor cycle

See How to Run ATDD for the test-drive development (TDD) approach.

Next Steps

Level Up Your TEA Skills

How-To Guides (task-oriented):

• How to Run Test Design - Deep dive into risk assessment
• How to Run ATDD - Generate failing tests first (TDD)
• How to Set Up CI Pipeline - Automate test execution
• How to Review Test Quality - Audit test quality

Explanation (understanding-oriented):

• TEA Overview - Complete TEA capabilities
• Testing as Engineering - Why TEA exists (problem + solution)
• Risk-Based Testing - How risk scoring works

Reference (quick lookup):

• TEA Command Reference - All 9 TEA workflows
• TEA Configuration - Config options
• Glossary - TEA terminology

Try TEA Solo

Ready for standalone usage without full BMad Method? Use TEA Solo:

• Run any TEA workflow independently
• Bring your own requirements
• Use on non-BMad projects

See TEA Overview for engagement models.

Go Full TEA Integrated

Want the complete quality operating model? Try TEA Integrated with BMad Method:

• Phase 2: Planning with non-functional requirements (NFR) assessment
• Phase 3: Architecture testability review
• Phase 4: Per-epic test design → atdd → automate
• Release Gate: Coverage traceability and gate decisions

See BMad Method Documentation for the full workflow.

Common Questions

• Why can’t my tests find elements?
• How do I fix network timeouts?

Why can’t my tests find elements?

Most likely you reached for a CSS class. TodoMVC ships a data-testid on every interactive element, and test-review scores CSS-class selectors down for exactly this reason: a class is styling, and styling changes without behavior changing.

The full set TodoMVC exposes:

page.getByTestId('header'); // Header region
page.getByTestId('text-input'); // New-todo input, and the edit input
page.getByTestId('main'); // Main region
page.getByTestId('toggle-all'); // Complete-all checkbox
page.getByTestId('todo-list'); // The list
page.getByTestId('todo-item'); // One todo row
page.getByTestId('todo-item-toggle'); // Its complete checkbox
page.getByTestId('todo-item-label'); // Its text label
page.getByTestId('todo-item-button'); // Its delete button
page.getByTestId('footer'); // Footer region
page.getByTestId('footer-navigation'); // All / Active / Completed links

Where an element has a real accessible role, prefer that. The three filters are links, so page.getByRole('link', { name: 'Active' }) reads better than drilling into footer-navigation.

For your own app, the same order applies: getByRole and getByLabel first, getByTestId when there is no meaningful role, CSS classes never.

How do I fix network timeouts?

Increase timeout in playwright.config.ts:

use: {
  timeout: 30000, // 30 seconds
}

Getting Help

• Documentation: https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/
• GitHub Issues: https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/issues
• Discord: Join the BMAD community