bmad-method 6.0.0-alpha.2 → 6.0.0-alpha.20

package/src/modules/bmm/workflows/testarch/framework/README.md

@@ -1,340 +0,0 @@
-# Test Framework Setup Workflow
-
-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
-
-```bash
-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:**
-
-1. **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)
-
-2. **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.
-
-3. **Environment Configuration**
-   - `.env.example` with `TEST_ENV`, `BASE_URL`, `API_URL`, auth credentials
-   - `.nvmrc` with Node version (LTS)
-
-4. **Test Infrastructure**
-   - Fixture architecture using `mergeTests` pattern
-   - Data factories with auto-cleanup (faker-based)
-   - Sample tests demonstrating best practices
-   - Helper utilities for common operations
-
-5. **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:
-
-```markdown
-## 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**
-
-```bash
-# 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**
-
-```bash
-# 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)**
-
-```bash
-# 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
-
-## Related Workflows
-
-- **ci**: Scaffold CI/CD pipeline → [ci/README.md](../ci/README.md)
-- **test-design**: Plan test coverage → [test-design/README.md](../test-design/README.md)
-- **atdd**: Generate acceptance tests → [atdd/README.md](../atdd/README.md)
-- **automate**: Expand regression suite → [automate/README.md](../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