Using TEA with Existing Tests (Brownfield)

Using TEA with Existing Tests (Brownfield)

Use TEA on brownfield projects (existing codebases with legacy tests) to establish coverage baselines, identify gaps, and improve test quality without starting from scratch.

When to Use This

• Existing codebase with some tests already written
• Legacy test suite needs quality improvement
• Adding features to existing application
• Need to understand current test coverage
• Want to prevent regression as you add features

Prerequisites

• Existing codebase with tests (even if incomplete or low quality)
• Tests run successfully (or at least can be executed)

Note: If your codebase is completely undocumented, run document-project first to create baseline documentation. It is a BMM workflow that ships with the BMad Method module, not with TEA.

Brownfield Strategy

Phase 1: Establish Baseline

Understand what you have before changing anything.

Step 1: Baseline Coverage with trace

Run the trace workflow and select Phase 1 (Requirements Traceability):

/bmad-testarch-trace

Provide:

• Existing requirements docs (PRD, user stories, feature specs)
• Test location (tests/ or wherever tests live)
• Focus areas (specific features if large codebase)

Output: traceability-matrix.md showing:

• Which requirements have tests
• Which requirements lack coverage
• Coverage classification (FULL/PARTIAL/NONE)
• Gap prioritization

Example Baseline:

# Baseline Coverage (Before Improvements)

**Total Requirements:** 50
**Full Coverage:** 15 (30%)
**Partial Coverage:** 20 (40%)
**No Coverage:** 15 (30%)

**By Priority:**

- P0: 50% coverage (5/10) ❌ Critical gap
- P1: 40% coverage (8/20) ⚠️ Needs improvement
- P2: 20% coverage (2/10) ✅ Acceptable

This baseline becomes your improvement target.

Step 2: Quality Audit with test-review

Run the test review workflow and answer tests/ when it asks for scope:

/bmad-testarch-test-review

Output: test-review.md with quality score and issues.

Common Brownfield Issues:

• Hard waits everywhere (page.waitForTimeout(5000))
• Fragile CSS selectors (.class > div:nth-child(3))
• No test isolation (tests depend on execution order)
• Try-catch for flow control
• Tests don’t clean up (leave test data in DB)

Example Baseline Quality:

# Quality Score: 55/100

**Critical Issues:** 12

- 8 hard waits
- 4 conditional flow control

**Recommendations:** 25

- Extract fixtures
- Improve selectors
- Add network assertions

This shows where to focus improvement efforts.

Phase 2: Prioritize Improvements

Don’t try to fix everything at once.

Focus on Critical Path First

Priority 1: P0 Requirements. Goal: P0 coverage at 100%.

1. Identify P0 requirements with no tests (from the trace matrix)
2. Run /bmad-testarch-automate to generate tests for the missing P0 scenarios
3. Fix the critical quality issues those tests carry (from the test-review report)

Priority 2: Fix Flaky Tests. Goal: eliminate flakiness.

1. Identify tests with hard waits (from the test-review report)
2. Replace them with network-first patterns
3. Run burn-in loops to verify stability

Example Modernization:

Before (Flaky - Hard Waits):

test('checkout completes', async ({ page }) => {
  await page.click('button[name="checkout"]');
  await page.waitForTimeout(5000); // ❌ Flaky
  await expect(page.locator('.confirmation')).toBeVisible();
});

After (Network-First - Vanilla):

test('checkout completes', async ({ page }) => {
  const checkoutPromise = page.waitForResponse((resp) => resp.url().includes('/api/checkout') && resp.ok());
  await page.click('button[name="checkout"]');
  await checkoutPromise; // ✅ Deterministic
  await expect(page.locator('.confirmation')).toBeVisible();
});

After (With Playwright Utils - Cleaner API):

import { test } from '@seontechnologies/playwright-utils/intercept-network-call/fixtures';
import { expect } from '@playwright/test';

test('checkout completes', async ({ page, interceptNetworkCall }) => {
  // Use interceptNetworkCall for cleaner network interception
  const checkoutCall = interceptNetworkCall({
    method: 'POST',
    url: '**/api/checkout',
  });

  await page.click('button[name="checkout"]');

  // Wait for response (automatic JSON parsing)
  const { status, responseJson: order } = await checkoutCall;

  // Validate API response
  expect(status).toBe(200);
  expect(order.status).toBe('confirmed');

  // Validate UI
  await expect(page.locator('.confirmation')).toBeVisible();
});

Playwright Utils Benefits:

• interceptNetworkCall for cleaner network interception
• Automatic JSON parsing (responseJson ready to use)
• No manual await response.json()
• Glob pattern matching (**/api/checkout)
• Cleaner, more maintainable code

For automatic error detection, use network-error-monitor fixture separately. See Integrate Playwright Utils.

Priority 3: P1 Requirements. Goal: P1 coverage at 80% or above.

1. Generate tests for the highest-risk P1 gaps
2. Improve test quality incrementally

Create Improvement Roadmap

# Test Improvement Roadmap

## Week 1: Critical Path (P0)

- [ ] Add 5 missing P0 tests (Epic 1: Auth)
- [ ] Fix 8 hard waits in auth tests
- [ ] Verify P0 coverage = 100%

## Week 2: Flakiness

- [ ] Replace all hard waits with network-first
- [ ] Fix conditional flow control
- [ ] Run burn-in loops (target: 0 failures in 10 runs)

## Week 3: High-Value Coverage (P1)

- [ ] Add 10 missing P1 tests
- [ ] Improve selector resilience
- [ ] P1 coverage target: 80%

## Week 4: Quality Polish

- [ ] Extract fixtures for common patterns
- [ ] Add network assertions
- [ ] Quality score target: 75+

Phase 3: Incremental Improvement

Apply TEA workflows to new work while improving legacy tests.

For New Features (Greenfield Within Brownfield)

Use the full TEA workflow:

1. /bmad-testarch-test-design (epic-level) to plan tests for the new feature
2. /bmad-testarch-atdd to generate failing tests first
3. Implement the feature
4. /bmad-testarch-automate to expand coverage
5. /bmad-testarch-test-review to check quality

Benefits:

• New code has high-quality tests from day one
• Gradually raises overall quality
• Team learns good patterns

For Bug Fixes (Regression Prevention)

Add regression tests:

1. Reproduce the bug with a failing test
2. Fix the bug
3. Verify the test passes
4. Run /bmad-testarch-test-review on the regression test
5. Add it to the regression suite

For Refactoring (Regression Safety)

Before refactoring:

1. Run /bmad-testarch-trace for a baseline and note the coverage percentage
2. Refactor the code
3. Run /bmad-testarch-trace again; no priority’s coverage should have decreased

Phase 4: Continuous Improvement

Track improvement over time.

Quarterly Quality Audits

Quarter	Coverage	Quality score	Flakiness
Q1 (baseline)	30%	55/100	15% fail rate
Q2 target	50% (focus on P0)	65/100	5%
Q3 target	70%	75/100	1%
Q4 target	85%	85/100	<0.5%

Brownfield-Specific Tips

Don’t Rewrite Everything

Common mistake: “Our tests are bad, let’s delete them all and start over.”

Better approach: a rewrite risks losing coverage you already have. Instead:

1. Keep tests that work, even imperfect ones
2. Fix critical quality issues incrementally
3. Add tests for the gaps
4. Improve gradually

Use Regression Hotspots

Identify regression-prone areas:

## Regression Hotspots

**Based on:**

- Bug reports (last 6 months)
- Customer complaints
- Code complexity (cyclomatic complexity >10)
- Frequent changes (git log analysis)

**High-Risk Areas:**

1. Authentication flow (12 bugs in 6 months)
2. Checkout process (8 bugs)
3. Payment integration (6 bugs)

**Test Priority:**

- Add regression tests for these areas FIRST
- Ensure P0 coverage before touching code

Quarantine Flaky Tests

Don’t let flaky tests block improvement:

// Mark flaky tests with .skip temporarily
test.skip('flaky test - needs fixing', async ({ page }) => {
  // TODO: Fix hard wait on line 45
  // TODO: Add network-first pattern
});

Track quarantined tests:

# Quarantined Tests

| Test                | Reason                     | Owner    | Target Fix Date |
| ------------------- | -------------------------- | -------- | --------------- |
| checkout.spec.ts:45 | Hard wait causes flakiness | QA Team  | 2026-01-20      |
| profile.spec.ts:28  | Conditional flow control   | Dev Team | 2026-01-25      |

Fix systematically:

• Don’t accumulate quarantined tests
• Set deadlines for fixes
• Review quarantine list weekly

Migrate One Directory at a Time

Large test suite? Improve incrementally:

Take one directory per week (tests/auth/, then tests/api/, then tests/e2e/), running the same loop on each:

1. Run /bmad-testarch-test-review and give that directory as the scope
2. Fix the critical issues
3. Re-review
4. Mark the directory as “modernized”

Benefits:

• Focused improvement
• Visible progress
• Team learns patterns
• Lower risk

Document Migration Status

Track which tests are modernized:

# Test Suite Status

| Directory          | Tests | Quality Score | Status         | Notes          |
| ------------------ | ----- | ------------- | -------------- | -------------- |
| tests/auth/        | 15    | 85/100        | ✅ Modernized  | Week 1 cleanup |
| tests/api/         | 32    | 78/100        | ⚠️ In Progress | Week 2         |
| tests/e2e/         | 28    | 62/100        | ❌ Legacy      | Week 3 planned |
| tests/integration/ | 12    | 45/100        | ❌ Legacy      | Week 4 planned |

**Legend:**

- ✅ Modernized: Quality >80, no critical issues
- ⚠️ In Progress: Active improvement
- ❌ Legacy: Untouched

Common Brownfield Challenges

”We Don’t Know What Tests Cover”

Problem: No documentation, unclear what tests do.

Solution:

1. Run /bmad-testarch-trace; TEA analyzes the tests and maps them to requirements
2. Review the traceability matrix
3. Document the findings
4. Use it as your improvement baseline

TEA reverse-engineers test coverage even without documentation.

”Tests Are Too Brittle to Touch”

Problem: Afraid to modify tests (might break them).

Solution: small changes carry small risk.

1. Run the tests and capture current behavior as the baseline
2. Make one small improvement, such as removing a single hard wait
3. Run the tests again
4. If they still pass, continue; if they fail, investigate before going further

”No One Knows How to Run Tests”

Problem: Test documentation is outdated or missing.

Solution:

1. Document manually, or ask TEA to analyze the test structure for you
2. Create tests/README.md covering how to install dependencies, how to run the tests (npx playwright test, npm test, or whatever your runner is), what each test directory contains, and common troubleshooting
3. Commit it for the team

Note: framework scaffolds a new test setup. For brownfield, document what you already have instead.

”Tests Take Hours to Run”

Problem: Full test suite takes 4+ hours.

Solution: sharding plus selective testing takes a 4-hour sequential suite to about 15 minutes.

1. Configure parallel execution (shard tests across workers)
2. Add selective testing so PRs run only affected tests
3. Run the full suite nightly only
4. Optimize slow tests by removing hard waits and improving selectors

How ci helps:

• Scaffolds CI configuration with parallel sharding examples
• Provides selective testing script templates
• Documents burn-in and optimization strategies
• But YOU configure workers, test selection, and optimization

With Playwright Utils burn-in:

• Smart selective testing based on git diff
• Volume control (run percentage of affected tests)
• See Integrate Playwright Utils

”We Have Tests But They Always Fail”

Problem: Tests are so flaky they’re ignored.

Solution:

1. Run /bmad-testarch-test-review to identify the flakiness patterns
2. Fix the top 5 flaky tests, which carry most of the impact
3. Quarantine the rest
4. Re-enable them as you fix them

Brownfield TEA Workflow

Recommended Sequence

document-project, prd, and architecture are BMM workflows that ship with the BMad Method module, not with TEA. Every /bmad-testarch-* command below is TEA. On Codex, swap the leading / for $.

Stage	Command	Purpose
1. Documentation (if needed)	document-project (BMM)	Baseline docs for an undocumented codebase
2. Baseline (Phase 2)	/bmad-testarch-trace, Phase 1	Coverage baseline
2. Baseline (Phase 2)	/bmad-testarch-test-review	Quality baseline
3. Planning (Phase 2-3)	prd, architecture (BMM)	Document requirements and architecture if missing
3. Planning (Phase 2-3)	/bmad-testarch-test-design, system-level	Testability review
4. Infrastructure (Phase 3)	/bmad-testarch-framework	Modernize the test framework, if needed
4. Infrastructure (Phase 3)	/bmad-testarch-ci	Set up or improve CI/CD
5. Per epic (Phase 4)	/bmad-testarch-test-design, epic-level	Focus on regression hotspots
5. Per epic (Phase 4)	/bmad-testarch-automate	Add the missing tests
5. Per epic (Phase 4)	/bmad-testarch-test-review	Check quality
5. Per epic (Phase 4)	/bmad-testarch-trace, Phase 1	Refresh coverage
6. Release gate	/bmad-testarch-nfr	Audit NFR evidence, where evidence exists
6. Release gate	/bmad-testarch-trace, Phase 2	Gate decision

Related Guides

Workflow Guides:

• How to Run Trace - Baseline coverage analysis
• How to Run Test Review - Quality audit
• How to Run Automate - Fill coverage gaps
• How to Run Test Design - Risk assessment

Customization:

• Integrate Playwright Utils - Modernize tests with utilities

Understanding the Concepts

• Engagement Models - Brownfield model explained
• Test Quality Standards - What makes tests good
• Network-First Patterns - Fix flakiness
• Risk-Based Testing - Prioritize improvements

Reference

• TEA Command Reference - All 9 workflows
• TEA Configuration - Config options
• Knowledge Base Index - Testing patterns
• Glossary - TEA terminology