Analyze Codebase

When to use

• At the start of a Playwright testing session (before ingest-spec or plan-tests)
• When running as part of run-testing-session pipeline (Stage 1)
• When project context is stale and needs refresh

Important: Always Prompt, Never Skip

When invoked as part of the run-testing-session orchestrator (Stage 0):

• If project-context.md does NOT exist: Show user "No global project context found. Run analyze-codebase? (required to proceed)" → User must choose Yes or the orchestrator cancels
• If project-context.md EXISTS: Show user these options:
  • A) Use existing context (skip analyze-codebase)
  • B) Re-run analyze-codebase (project has grown or changed)
  • C) Cancel session

This ensures the user always controls when the codebase analysis happens, especially important when the repository has grown and context needs refresh.

When run standalone (outside the orchestrator): analyze-codebase always writes to docs/playwright-spec-testing/project-context.md without prompting. Users can run it manually anytime.

Inputs

• Project root directory path

What it does

Scan the project at the project root and produce a shared context document that all subsequent pipeline stages depend on. You are read-only — do not run the app or open a browser.

Phase 1: Playwright setup

Search the project root and common config locations for:

• playwright.config.ts or playwright.config.js — note: testDir, baseURL, use.browserName, reporter
• package.json — note the test script and any @playwright/test version
• Existing test files matching **/*.spec.ts, **/*.spec.js, **/*.test.ts, **/*.test.js

If no Playwright config exists, note this clearly.

Phase 2: Routing structure

Look for:

• app/ or pages/ directory → Next.js App Router or Pages Router
• src/routes/ → SvelteKit or React Router file-based routing
• router.ts or routes.ts → programmatic routing
• Top-level index.html → single-page app without file-based routing

List the top-level routes you find with their paths and likely purpose.

Phase 3: Existing specs

Search for:

• **/*.feature files — Gherkin specs
• Any file in specs/, test-cases/, or test-docs/ directories
• Any Markdown or text file whose name contains "test", "spec", "scenario", or "acceptance"

Phase 4: Tech stack

From package.json dependencies, identify:

• UI framework: React, Vue, Svelte, Angular, or vanilla
• Component library: shadcn/ui, MUI, Ant Design, Chakra, Radix, etc.
• CSS approach: Tailwind, CSS Modules, styled-components

Phase 5: Write context document

Save findings to docs/playwright-spec-testing/project-context.md (create directory if needed).

Use this exact structure:

# Project Context

_Generated by analyze-codebase on [DATE]_

## Playwright Config
- Config file: [path or "not found"]
- testDir: [value]
- baseURL: [value]
- Default browser: [value]

## Test File Conventions
- Existing test files: [list with paths]
- Naming pattern: [e.g., "*.spec.ts in tests/"]
- Output directory for new tests: [inferred from testDir, or "not yet determined — plan-tests will ask"]

## Routing Structure
- Framework: [Next.js App Router / Pages Router / React Router / SvelteKit / other]
- Top-level routes: [list]

## Existing Specs
- [path] — [Gherkin / plain English]

## Tech Stack
- UI framework: [name]
- Component library: [name or "none detected"]
- CSS approach: [name]

## Notes
[Any issues, warnings, or things to know]

Phase 6: Scan for reusable test infrastructure

After writing the main project-context.md, scan the project for reusable test infrastructure and append a new section to the same file.

What to scan for:

• Custom fixture files (fixtures/, *.fixtures.ts, any file containing test.extend()`)
• Page objects (page-objects/, pages/, any class whose constructor accepts a Playwright Page parameter)
• Auth helpers (functions named login*, auth*, signIn*)
• Shared beforeEach patterns in existing spec files

Append to project-context.md:

## Reusable Test Infrastructure

### Fixtures
- `tests/fixtures/auth.fixture.ts` — exports `authenticatedPage` (pre-logged-in page)
- `tests/fixtures/index.ts` — re-exports all fixtures via custom `test` object

### Page Objects
- `tests/pages/LoginPage.ts` — methods: `fill()`, `submit()`, `expectError()`
- `tests/pages/SettingsPage.ts` — methods: `openLicensesTab()`, `clickAssignUsers()`

### Auth Helpers
- `tests/helpers/login.ts` — `loginAs(page, role)` fills credentials and submits

### Notes
[None detected] OR [any caveats about partial coverage]

If nothing is found in any subcategory, omit that subsection and write instead: ### Notes — No reusable infrastructure detected

Global Output (Never Workspace-Scoped)

The output file docs/playwright-spec-testing/project-context.md is ALWAYS at the global root level, never inside a workspace directory. This file is shared across all sessions in the project. If running as part of a workspace session (from run-testing-session), the workspace will generate its own workspace-context.md from this global context, but analyze-codebase only writes the global file.

Key Rules

• Never invent information. If not found, write "not found" or "not detected."
• Do not run the app or open a browser.
• If Playwright is not installed, report BLOCKED.

Output

docs/playwright-spec-testing/project-context.md (includes ## Reusable Test Infrastructure section)

Report when done:

• Status: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
• Summary of what was found
• Path to output file
• Any concerns or missing information