24 KiB

Raw Blame History

Playwright Utils Integration - Implementation Plan

Status: ✅ APPROVED - READY TO IMPLEMENT Version: 5.0 FINAL (Aligned) Last Review: 2025-01-20

Quick Reference

Files: 20 total (2 installer + 9 knowledge + 6 workflows + 3 docs) Timeline: 25-32 hours over 3 weeks Validation: npm run validate:schemas && npm run test:schemas

Overview

Add @seontechnologies/playwright-utils integration to TEA with:

Installation prompt (mirrors tea_use_mcp_enhancements)
8 lean fragments (keep bundles light)
5 priority workflows + 1 light mention
Minimal docs (small section in test-architecture.md)

Final Scope (Approved - Lean First Set)

11 Complete Fragments (ALL utilities included):

overview.md - Installation and design principles
api-request.md - HTTP client with schema validation
network-recorder.md - HAR record/playback
auth-session.md - Token persistence (very involved)
intercept-network-call.md - Network spy/stub
recurse.md - Polling patterns
log.md - Structured logging
file-utils.md - CSV/XLSX/PDF/ZIP
burn-in.md - Smart test selection (very important for CI)
network-error-monitor.md - HTTP error detection
fixtures-composition.md - mergeTests patterns

Naming convention: No -util suffix (standardized) Total: 32 fragments in tea-index.csv (21 + 11)

5 Priority Workflows + 1 light mention:

testarch/automate (CRITICAL)
testarch/framework
testarch/test-review
testarch/ci
testarch/atdd
testarch/test-design (light mention only)

Keep minimal: trace, nfr-assess (no changes for now)

Key Principles:

✅ Mirror config.tea_use_mcp_enhancements pattern
✅ Preserve current behavior when flag is false
✅ NO package.json auto-detection
✅ Lean fragments (150-250 lines each)
✅ Minimal doc updates
✅ Keep bundles light

Phase 1: Installation Enhancement

1.1 Add Installation Prompt

Files to modify:

src/modules/bmm/_module-installer/install-config.yaml - Add prompt (next to tea_use_mcp_enhancements)
src/modules/bmm/_module-installer/installer.js - Wire prompt to config write

Add prompt to install-config.yaml:

# Add next to existing tea_use_mcp_enhancements prompt
prompts:
  tea_use_mcp_enhancements:
    # ... existing MCP prompt ...

  tea_use_playwright_utils: # New prompt
    type: confirm
    name: usePlaywrightUtils
    message: 'Are you using @seontechnologies/playwright-utils in your project?'
    default: false

1.2 Wire to Config Write

In installer.js, ensure CLI writes use_playwright_utils into bmad/bmm/config.yaml.

Flag naming (matches tea_use_mcp_enhancements pattern):

Prompt key: usePlaywrightUtils (camelCase)
Stored key: use_playwright_utils (underscore)
Workflow reference: config.use_playwright_utils (mirrors config.tea_use_mcp_enhancements)

Generated config structure in bmad/bmm/config.yaml:

# Test Architect Configuration
test_architect:
  use_playwright_utils: false # Set based on user response
  tea_use_mcp_enhancements: false # Existing MCP flag for reference

1.3 Verification

Test the installation flow:

Run: npx bmad-method@alpha install
Select BMM module
Verify prompt appears after MCP prompt
Answer "Yes" → verify bmad/bmm/config.yaml has use_playwright_utils: true
Answer "No" → verify bmad/bmm/config.yaml has use_playwright_utils: false

Phase 2: Knowledge Base Expansion (10-12 hours)

2.1 Create 8 Lean Fragments (Keep Bundles Light)

Location: src/modules/bmm/testarch/knowledge/

Target: 150-250 lines each, action-focused, real examples from playwright-utils docs

Fragment	Lines	Description
`overview.md`	200	Installation, design principles, fixture pattern
`api-request.md`	250	Typed HTTP client, schema validation, retry
`network-recorder.md`	250	HAR record/playback, stateful CRUD detection
`auth-session.md`	250	Token persistence, multi-user, ephemeral
`intercept-network-call.md`	200	Network spy/stub, automatic JSON parsing
`recurse.md`	200	Cypress-style polling, async conditions
`log.md`	150	Test report integration, structured logging
`fixtures-composition.md`	200	mergeTests composition, integration patterns

Total: ~1,500 lines (lean, focused, light bundle)

Add later: file-utils, burn-in, network-error-monitor

2.2 Update TEA Index

File: src/modules/bmm/testarch/tea-index.csv

Schema: id,name,description,tags,fragment_file (keep tags short)

Add 8 rows:

overview,Playwright Utils Overview,"Installation, design principles, fixture patterns","playwright-utils,fixtures",knowledge/overview.md
api-request,API Request,"Typed HTTP client, schema validation","api,playwright-utils",knowledge/api-request.md
network-recorder,Network Recorder,"HAR record/playback, CRUD detection","network,playwright-utils",knowledge/network-recorder.md
auth-session,Auth Session,"Token persistence, multi-user","auth,playwright-utils",knowledge/auth-session.md
intercept-network-call,Intercept Network Call,"Network spy/stub, JSON parsing","network,playwright-utils",knowledge/intercept-network-call.md
recurse,Recurse Polling,"Async polling, condition waiting","polling,playwright-utils",knowledge/recurse.md
log,Log Utility,"Report logging, structured output","logging,playwright-utils",knowledge/log.md
fixtures-composition,Fixtures Composition,"mergeTests composition patterns","fixtures,playwright-utils",knowledge/fixtures-composition.md

Result: 29 total fragments (21 existing + 8 new)

Validation (run after changes):

npm run validate:schemas
npm run test:schemas

2.3 Fragment Structure Template

Each fragment should follow this structure:

# [Utility Name]

## Principle

[Core concept of the utility]

## Rationale

[Why this utility exists, what problems it solves]

## Pattern Examples

### Example 1: [Basic Usage Pattern]

**Context**: [When to use this pattern]

**Implementation**:

```typescript
// Code example from playwright-utils docs
```

Key Points:

Point 1
Point 2

Example 2: [Advanced Pattern]

Context: [When to use this pattern]

Implementation:

// Code example

Key Points:

Point 1
Point 2

Integration with Other Utilities

[How this utility works with other playwright-utils]

Anti-Patterns

[What NOT to do]

fragment-id-1 - Description
fragment-id-2 - Description


---

## Phase 3: Workflow Integration (8-10 hours)

### 3.1 Update 5 Priority Workflows + 1 Light Mention

**Preserve current behavior when flag is false**

| Workflow | Integration |
|----------|-------------|
| `testarch/automate` | Generate tests with playwright-utils (CRITICAL) |
| `testarch/framework` | Recommend installation, scaffold fixtures |
| `testarch/test-review` | Review against utility best practices |
| `testarch/ci` | CI workflow updates |
| `testarch/atdd` | ATDD with utility patterns |
| `testarch/test-design` | Light mention only |

**Keep minimal (no changes):** trace, nfr-assess

### 3.2 Workflow Modification Pattern

**Each workflow will follow this pattern:**

```markdown
## Step X: Load Knowledge Base

**Actions:**

1. Check playwright-utils flag from config:
   - Read `{config_source}` and check `config.use_playwright_utils`
   - (Pattern matches existing: `config.tea_use_mcp_enhancements`)

2. Load knowledge fragments based on flag:

   **If `config.use_playwright_utils: true`:**

   Load playwright-utils fragments:
   - overview.md
   - api-request.md
   - network-recorder.md
   - auth-session.md
   - intercept-network-call.md
   - recurse.md
   - log.md
   - fixtures-composition.md

   **If `config.use_playwright_utils: false`:**

   Load traditional pattern fragments (existing behavior preserved)

3. [Continue with existing step content]

Example workflow reference in instructions:

**Critical:** Check configuration flag.

Read `{config_source}` and check `config.use_playwright_utils`.

If true, load playwright-utils fragments. If false, load traditional pattern fragments.

This ensures backward compatibility and preserves existing behavior.

3.3 Example: `*automate` Workflow Enhancement

File: src/modules/bmm/workflows/testarch/automate/instructions.md

Current Step 2 (Load Knowledge Base):

## Step 2: Load Knowledge Base

**Critical:** Consult `{project-root}/{bmad_folder}/bmm/testarch/tea-index.csv` to load:

- `fixture-architecture.md` - Pure function → fixture pattern
- `network-first.md` - Intercept-before-navigate workflow
- `data-factories.md` - Factory functions with overrides

Enhanced Step 2 (With Playwright Utils Check):

## Step 2: Load Knowledge Base

**Critical:** Check configuration and load appropriate fragments.

1. **Read Configuration**
   - Load `{config_source}`
   - Check `test_architect.use_playwright_utils` flag

2. **Load Fragments Based on Configuration**

   **If `use_playwright_utils: true`:**

   Consult `{project-root}/{bmad_folder}/bmm/testarch/tea-index.csv` and load:
   - `playwright-utils-overview.md` - Installation and design principles
   - `api-request-util.md` - Typed HTTP client with schema validation
   - `network-recorder-util.md` - HAR record/playback for offline testing
   - `auth-session-util.md` - Token management and session persistence
   - `recurse-util.md` - Polling patterns for async operations
   - `intercept-network-util.md` - Enhanced network interception
   - `log-util.md` - Playwright report-integrated logging
   - `file-utils-util.md` - File reading and validation
   - `playwright-utils-fixtures.md` - Fixture composition patterns

   **If `use_playwright_utils: false`:**

   Consult `{project-root}/{bmad_folder}/bmm/testarch/tea-index.csv` and load:
   - `fixture-architecture.md` - Pure function → fixture pattern
   - `network-first.md` - Intercept-before-navigate workflow
   - `data-factories.md` - Factory functions with overrides
   - `component-tdd.md` - Component TDD loop

3.4 Code Generation Enhancement

In *automate workflow, modify test generation instructions:

## Step 4: Generate Test Code

**If `use_playwright_utils: true`:**

Generate tests using playwright-utils utilities:

```typescript
// Import from playwright-utils
import { test } from '@seontechnologies/playwright-utils/fixtures';
// Or merge with your fixtures:
import { test } from '../support/merged-fixtures';

test('should fetch user data', async ({ apiRequest, recurse }) => {
  // Use apiRequest utility
  const { status, body } = await apiRequest<User>({
    method: 'GET',
    path: '/api/users/123',
  });

  expect(status).toBe(200);

  // Use recurse for polling
  await recurse({
    command: () => apiRequest({ method: 'GET', path: `/api/users/${body.id}/status` }),
    predicate: (response) => response.body.ready === true,
    options: { timeout: 30000 },
  });
});
```

If use_playwright_utils: false:

Generate tests using traditional patterns:

test('should fetch user data', async ({ request }) => {
  const response = await request.get('/api/users/123');
  expect(response.ok()).toBeTruthy();
  const body = await response.json();

  // Manual polling
  await expect
    .poll(
      async () => {
        const statusResponse = await request.get(`/api/users/${body.id}/status`);
        const statusBody = await statusResponse.json();
        return statusBody.ready;
      },
      { timeout: 30000 },
    )
    .toBe(true);
});


---

## Phase 4: Testing & Validation (REVISED - Focused Scope)

### 4.1 Schema & Index Validation (PRIORITY)

**Run after tea-index.csv changes:**

```bash
npm run validate:schemas  # Validate YAML structure, tea-index.csv format
npm run test:schemas      # Ensure agent YAML compiles correctly

Verify:

tea-index.csv has correct column headers: id,name,description,tags,fragment_file
All 8 new fragment_file paths exist
Tags are short (3-4 max per fragment)
No duplicate IDs

4.2 Installation Testing

Test Cases:

New Installation - Playwright Utils Selected
- Run: npx bmad-method@alpha install
- Select BMM module
- Answer "Yes" to playwright-utils prompt
- Verify: bmad/bmm/config.yaml has use_playwright_utils: true
New Installation - Playwright Utils Not Selected
- Run installation
- Answer "No" to playwright-utils prompt
- Verify: bmad/bmm/config.yaml has use_playwright_utils: false

4.3 Workflow Testing (5 Priority Workflows)

Test Cases:

Automate Workflow - Flag True
- Set use_playwright_utils: true in config
- Run *automate
- Verify: Loads playwright-utils fragments (api-request-util, etc.)
- Verify: Generated code imports from @seontechnologies/playwright-utils
Automate Workflow - Flag False
- Set use_playwright_utils: false in config
- Run *automate
- Verify: Loads traditional fragments (fixture-architecture, etc.)
- Verify: Generated code uses vanilla Playwright patterns
Framework/Test-Review/CI/ATDD Workflows
- Test with both flag states
- Verify conditional behavior preserves existing functionality when flag is false

4.4 Knowledge Fragment Validation

Validation per fragment (8 total):

Fragment is 150-300 lines (action-focused, concise)
All code examples use working playwright-utils patterns
Related fragments cross-referenced
Tags accurate in tea-index.csv
No bloating of bundle size

Phase 5: Documentation Updates (REVISED - Concise Updates)

5.1 Update TEA Documentation

File: src/modules/bmm/docs/test-architecture.md

Add small "Playwright Utils Integration" section:

### Playwright Utils Integration

TEA optionally integrates with `@seontechnologies/playwright-utils`.

**Installation:**

```bash
npm install -D @seontechnologies/playwright-utils
```

Enable during BMAD installation by answering "Yes" when prompted.

Supported utilities: api-request, network-recorder, auth-session, intercept-network-call, recurse, log, fixtures-composition.

Workflows adapt: automate, framework, test-review, ci, atdd (+ light mention in test-design).


**Update knowledge base count:**

```markdown
TEA maintains 29 knowledge fragments (21 core + 8 playwright-utils).

5.2 Update README (Minimal)

File: README.md

Add one line to Test Architect section:

**Test Architect** - Optionally integrates with `@seontechnologies/playwright-utils` for fixture-based utility recommendations.

5.3 Update CHANGELOG

File: CHANGELOG.md

## [6.1.0] - 2025-XX-XX

### Added

- **Playwright Utils Integration**: TEA supports optional integration with `@seontechnologies/playwright-utils`
  - Installation-time prompt with `use_playwright_utils` configuration flag
  - 8 new concise knowledge fragments (~1,700-2,100 lines total)
  - Adaptive workflow recommendations in 5 priority workflows
  - 29 total knowledge fragments (21 core + 8 playwright-utils)

Implementation Checklist (REVISED - Focused Scope)

Phase 1: Installation Enhancement ✅

Locate and update src/modules/bmm/_module-installer/install-config.yaml
- Add prompt: usePlaywrightUtils (camelCase)
Wire prompt in tools/cli/installers/lib/install-steps.js (or equivalent)
Ensure flag writes to bmad/bmm/config.yaml as use_playwright_utils (underscore)
Test installation:
- Answer "Yes" → verify use_playwright_utils: true
- Answer "No" → verify use_playwright_utils: false

Phase 2: Knowledge Base Expansion 📚

Create 8 focused knowledge fragments (150-300 lines each):
- playwright-utils-overview.md
- api-request-util.md
- network-recorder-util.md
- auth-session-util.md
- intercept-network-util.md
- recurse-util.md
- log-util.md
- playwright-utils-fixtures.md
Update tea-index.csv with 8 new entries
- Verify column headers: id,name,description,tags,fragment_file
- Keep tags short (3-4 max)
Run schema validation:
- npm run validate:schemas
- npm run test:schemas

Phase 3: Workflow Integration 🔄

Update 5 priority workflows with flag checks:
- *automate (CRITICAL - test generation with utilities)
- *framework (recommend installation, scaffold fixtures)
- *test-review (check for utility best practices)
- *ci (mention burn-in/network-error-monitor)
- *atdd (recommend utility patterns)
Implement conditional fragment loading in each workflow
Preserve existing behavior when use_playwright_utils: false

Phase 4: Testing & Validation 🧪

Schema validation (PRIORITY):
- npm run validate:schemas
- npm run test:schemas
- Verify tea-index.csv format
Installation testing (2 scenarios)
Workflow testing (5 workflows × 2 flag states)
Fragment validation (8 fragments)
- 150-300 lines each
- Working code examples
- No bundle bloat

Phase 5: Documentation Updates 📝

Update test-architecture.md
- Add brief "Playwright Utils Integration" section
- Update knowledge base count (29 fragments)
Update README.md (one line addition)
Update CHANGELOG.md (concise entry)

Phase 6: Quality Assurance 🎯

Run npm run validate:schemas (final check)
Run npm run test:schemas (final check)
Test installation end-to-end
Test one workflow with both flag states
Optional: npm run bundle if bundling for web

Success Criteria

Installation

✅ User is prompted about playwright-utils during BMM installation
✅ Flag is correctly stored in bmad/bmm/config.yaml
✅ Installation completes successfully with both "Yes" and "No" responses

Knowledge Base

✅ All 11 new fragments created and indexed
✅ tea-index.csv has 32 total entries
✅ All code examples are tested and functional
✅ Fragments follow consistent template structure

Workflow Integration

✅ All 8 TEA workflows check for playwright-utils flag
✅ Workflows load appropriate fragments based on flag
✅ Generated code uses playwright-utils when flag is true
✅ Generated code uses vanilla Playwright when flag is false

Documentation

✅ test-architecture.md includes playwright-utils integration section
✅ README.md references playwright-utils
✅ CHANGELOG.md documents changes
✅ All documentation is accurate and complete

Testing

✅ All schema validation passes
✅ All agent tests pass
✅ Installation tests pass
✅ Workflow tests pass
✅ Bundle generation succeeds

Timeline Estimate (REVISED - Complete Scope)

Phase	Estimated Time	Dependencies
Phase 1: Installation	3-4 hours	None
Phase 2: Knowledge Base (11 fragments)	16-20 hours	Phase 1
Phase 3: Workflow Integration (8 workflows)	12-16 hours	Phase 2
Phase 4: Testing & Validation	6-8 hours	Phase 3
Phase 5: Documentation	3-4 hours	Phase 4
Phase 6: QA	3-4 hours	Phase 5
Total	43-56 hours	Sequential

Recommended approach:

Week 1-2: Phases 1-2 (Installation + All 11 fragments)
Week 3: Phase 3 (All 8 workflows)
Week 4: Phases 4-6 (Testing, Docs, QA)

Risk Assessment

Risk	Impact	Likelihood	Mitigation
Knowledge fragments too verbose	Medium	Medium	Follow existing fragment size patterns
Workflow conditionals add complexity	Medium	High	Clear documentation, extensive testing
Breaking changes to existing workflows	High	Low	Preserve existing behavior when flag is false
Installation prompt not intuitive	Low	Medium	User testing, clear prompt wording
Schema validation failures	High	Low	Validate early and often
Bundle size increases significantly	Low	High	Monitor bundle sizes, optimize if needed

Future Enhancements

Post-v6.1 Considerations:

Auto-detection: Automatically detect if @seontechnologies/playwright-utils is in package.json
Version compatibility: Check playwright-utils version and recommend upgrade if needed
Utility-specific knowledge: Add more granular fragments for specific utility patterns
Interactive examples: Link to live examples in playwright-utils repo
Migration guide: Create workflow to help migrate from vanilla Playwright to playwright-utils
Performance metrics: Track how playwright-utils affects test execution time
Community contributions: Allow users to contribute playwright-utils patterns

Notes

This integration maintains backward compatibility - existing installations work unchanged
The flag is opt-in, preserving TEA's original pattern-based approach
All code examples in fragments should be tested in the playwright-utils repository
This enhancement positions BMAD as the premier framework for modern Playwright testing
Opens door for future integrations with other utility libraries

Questions for Discussion

Should we auto-detect playwright-utils in package.json instead of prompting?
Should we create a migration workflow for projects moving to playwright-utils?
Should we bundle sample fixtures that integrate playwright-utils?
Should we create a separate "quick start" guide for playwright-utils + BMAD?
Should we add telemetry to track playwright-utils adoption?

Summary of Changes from Initial Plan

Scope Adjustments (Final):

Fragment count: ALL 11 utilities included (non-negotiable)
Fragment size: 150-300 lines (concise, action-focused)
Total lines: ~2,250-2,850 lines
Workflow count: ALL 8 TEA workflows updated (non-negotiable)
Timeline: 43-56 hours (complete coverage)
tea-index.csv: 32 total fragments (21 existing + 11 new)
NO package.json auto-detection (repos may not be TypeScript/Node.js)

Key Improvements:

File locations aligned with actual repo structure
Consistent kebab-case naming (use_playwright_utils)
Short tags in tea-index.csv (max 3 tags)
Context-aware fragment loading (UI/API/CI-CD)
Schema validation prioritized throughout
Preserve existing behavior when flag is false
Utility context mapping for smart recommendations

Document Version: 3.0 (FINAL - Ready for Implementation) Created: 2025-01-20 Last Updated: 2025-01-20 Owner: Test Architect Enhancement Team

Implementation-Ready Checklist

Before starting implementation, verify these concrete file locations exist:

src/modules/bmm/_module-installer/install-config.yaml - For adding prompt
src/modules/bmm/_module-installer/installer.js - For wiring to config write
src/modules/bmm/testarch/tea-index.csv - Verify columns: id,name,description,tags,fragment_file
src/modules/bmm/testarch/knowledge/ - Directory for new fragments
src/modules/bmm/workflows/testarch/automate/instructions.md - Priority workflow
src/modules/bmm/workflows/testarch/framework/instructions.md - Priority workflow
src/modules/bmm/workflows/testarch/test-review/instructions.md - Priority workflow
src/modules/bmm/workflows/testarch/ci/instructions.md - Priority workflow
src/modules/bmm/workflows/testarch/atdd/instructions.md - Priority workflow

Validation commands to run:

npm run validate:schemas  # After tea-index.csv changes
npm run test:schemas      # After agent YAML changes

24 KiB Raw Blame History Unescape Escape