Initializes a production-ready test framework architecture (Playwright or Cypress) with fixtures, helpers, configuration, and industry best practices. This workflow scaffolds the complete testing infrastructure for modern web applications, providing a robust foundation for test automation.

Usage

bmad tea *framework

The TEA agent runs this workflow when:

Starting a new project that needs test infrastructure
Migrating from an older testing approach
Setting up testing from scratch
Standardizing test architecture across teams

Inputs

Required Context Files:

package.json: Project dependencies and scripts to detect project type and bundler

Optional Context Files:

Architecture docs (architecture.md, tech-spec.md): Informs framework configuration decisions
Existing tests: Detects current framework to avoid conflicts

Workflow Variables:

test_framework: Auto-detected (playwright/cypress) or manually specified
project_type: Auto-detected from package.json (react/vue/angular/next/node)
bundler: Auto-detected from package.json (vite/webpack/rollup/esbuild)
test_dir: Root test directory (default: {project-root}/tests)
use_typescript: Prefer TypeScript configuration (default: true)
framework_preference: Auto-detection or force specific framework (default: "auto")

Outputs

Primary Deliverables:

Configuration File
- playwright.config.ts or cypress.config.ts with production-ready settings
- Timeouts: action 15s, navigation 30s, test 60s
- Reporters: HTML + JUnit XML
- Failure-only artifacts (traces, screenshots, videos)

Directory Structure

tests/
├── e2e/                          # Test files (organize as needed)
├── support/                      # Framework infrastructure (key pattern)
│   ├── fixtures/                 # Test fixtures with auto-cleanup
│   │   ├── index.ts             # Fixture merging
│   │   └── factories/           # Data factories (faker-based)
│   ├── helpers/                 # Utility functions
│   └── page-objects/            # Page object models (optional)
└── README.md                    # Setup and usage guide

Note: Test organization (e2e/, api/, integration/, etc.) is flexible. The support/ folder contains reusable fixtures, helpers, and factories - the core framework pattern.

Environment Configuration
- .env.example with TEST_ENV, BASE_URL, API_URL, auth credentials
- .nvmrc with Node version (LTS)
Test Infrastructure
- Fixture architecture using mergeTests pattern
- Data factories with auto-cleanup (faker-based)
- Sample tests demonstrating best practices
- Helper utilities for common operations
Documentation
- tests/README.md with comprehensive setup instructions
- Inline comments explaining configuration choices
- References to TEA knowledge base

Secondary Deliverables:

Updated package.json with minimal test script (test:e2e)
Sample test demonstrating fixture usage
Network-first testing patterns
Selector strategy guidance (data-testid)

Validation Safeguards:

✅ No existing framework detected (prevents conflicts)
✅ package.json exists and is valid
✅ Framework auto-detection successful or explicit choice provided
✅ Sample test runs successfully
✅ All generated files are syntactically correct

Key Features

Smart Framework Selection

Auto-detection logic based on project characteristics:
- Playwright recommended for: Large repos (100+ files), performance-critical apps, multi-browser support, complex debugging needs
- Cypress recommended for: Small teams prioritizing DX, component testing focus, real-time test development
Falls back to Playwright as default if uncertain

Production-Ready Patterns

Fixture Architecture: Pure function → fixture → mergeTests composition pattern
Auto-Cleanup: Fixtures automatically clean up test data in teardown
Network-First: Route interception before navigation to prevent race conditions
Failure-Only Artifacts: Screenshots/videos/traces only captured on failure to reduce storage
Parallel Execution: Configured for optimal CI performance

Industry Best Practices

Selector Strategy: Prescriptive guidance on data-testid attributes
Data Factories: Faker-based factories for realistic test data
Contract Testing: Recommends Pact for microservices architectures
Error Handling: Comprehensive timeout and retry configuration
Reporting: Multiple reporter formats (HTML, JUnit, console)

Knowledge Base Integration

Automatically consults TEA knowledge base:

fixture-architecture.md - Pure function → fixture → mergeTests pattern
data-factories.md - Faker-based factories with auto-cleanup
network-first.md - Network interception before navigation
playwright-config.md - Playwright-specific best practices
test-config.md - General configuration guidelines

Integration with Other Workflows

Before framework:

prd (Phase 2): Determines project scope and testing needs
workflow-status: Verifies project readiness

After framework:

ci: Scaffold CI/CD pipeline using framework configuration
test-design: Plan test coverage strategy for the project
atdd: Generate failing acceptance tests using the framework

Coordinates with:

architecture (Phase 3): Aligns test structure with system architecture
tech-spec: Uses technical specifications to inform test configuration

Updates:

bmm-workflow-status.md: Adds framework initialization to Quality & Testing Progress section

Important Notes

Preflight Checks

Critical requirements verified before scaffolding:

package.json exists in project root
No modern E2E framework already configured
Architecture/stack context available

If any check fails, workflow HALTS and notifies user.

Framework-Specific Guidance

Playwright Advantages:

Worker parallelism (significantly faster for large suites)
Trace viewer (powerful debugging with screenshots, network, console logs)
Multi-language support (TypeScript, JavaScript, Python, C#, Java)
Built-in API testing capabilities
Better handling of multiple browser contexts

Cypress Advantages:

Superior developer experience (real-time reloading)
Excellent for component testing
Simpler setup for small teams
Better suited for watch mode during development

Avoid Cypress when:

API chains are heavy and complex
Multi-tab/window scenarios are common
Worker parallelism is critical for CI performance

Selector Strategy

Always recommend:

data-testid attributes for UI elements (framework-agnostic)
data-cy attributes if Cypress is chosen (Cypress-specific)
Avoid brittle CSS selectors or XPath

Standalone Operation

This workflow operates independently:

No story required: Can be run at project initialization
No epic context needed: Works for greenfield and brownfield projects
Autonomous: Auto-detects configuration and proceeds without user input

Output Summary Format

After completion, provides structured summary:

## Framework Scaffold Complete

**Framework Selected**: Playwright (or Cypress)

**Artifacts Created**:

- ✅ Configuration file: playwright.config.ts
- ✅ Directory structure: tests/e2e/, tests/support/
- ✅ Environment config: .env.example
- ✅ Node version: .nvmrc
- ✅ Fixture architecture: tests/support/fixtures/
- ✅ Data factories: tests/support/fixtures/factories/
- ✅ Sample tests: tests/e2e/example.spec.ts
- ✅ Documentation: tests/README.md

**Next Steps**:

1. Copy .env.example to .env and fill in environment variables
2. Run npm install to install test dependencies
3. Run npm run test:e2e to execute sample tests
4. Review tests/README.md for detailed setup instructions

**Knowledge Base References Applied**:

- Fixture architecture pattern (pure functions + mergeTests)
- Data factories with auto-cleanup (faker-based)
- Network-first testing safeguards
- Failure-only artifact capture

Validation Checklist

After workflow completion, verify:

Configuration file created and syntactically valid
Directory structure exists with all folders
Environment configuration generated (.env.example, .nvmrc)
Sample tests run successfully (npm run test:e2e)
Documentation complete and accurate (tests/README.md)
No errors or warnings during scaffold
package.json scripts updated correctly
Fixtures and factories follow patterns from knowledge base

Refer to checklist.md for comprehensive validation criteria.

Example Execution

Scenario 1: New React + Vite project

# User runs framework workflow
bmad tea *framework

# TEA detects:
# - React project (from package.json)
# - Vite bundler
# - No existing test framework
# - 150+ files (recommends Playwright)

# TEA scaffolds:
# - playwright.config.ts with Vite detection
# - Component testing configuration
# - React Testing Library helpers
# - Sample component + E2E tests

Scenario 2: Existing Node.js API project

# User runs framework workflow
bmad tea *framework

# TEA detects:
# - Node.js backend (no frontend framework)
# - Express framework
# - Small project (50 files)
# - API endpoints in routes/

# TEA scaffolds:
# - playwright.config.ts focused on API testing
# - tests/api/ directory structure
# - API helper utilities
# - Sample API tests with auth

Scenario 3: Cypress preferred (explicit)

# User sets framework preference
# (in workflow config: framework_preference: "cypress")

bmad tea *framework

# TEA scaffolds:
# - cypress.config.ts
# - tests/e2e/ with Cypress patterns
# - Cypress-specific commands
# - data-cy selector strategy

Troubleshooting

Issue: "Existing test framework detected"

Cause: playwright.config._ or cypress.config._ already exists
Solution: Use upgrade-framework workflow (TBD) or manually remove existing config

Issue: "Cannot detect project type"

Cause: package.json missing or malformed
Solution: Ensure package.json exists and has valid dependencies

Issue: "Sample test fails to run"

Cause: Missing dependencies or incorrect BASE_URL
Solution: Run npm install and configure .env with correct URLs

Issue: "TypeScript compilation errors"

Cause: Missing @types packages or tsconfig misconfiguration
Solution: Ensure TypeScript and type definitions are installed

ci: Scaffold CI/CD pipeline → ci/README.md
test-design: Plan test coverage → test-design/README.md
atdd: Generate acceptance tests → atdd/README.md
automate: Expand regression suite → automate/README.md

Version History

v4.0 (BMad v6): Pure markdown instructions, enhanced workflow.yaml, comprehensive README
v3.x: XML format instructions
v2.x: Legacy task-based approach

README.md

Test Framework Setup Workflow