Pre-Requisites: Discover the Application and Produce Customization Artifacts

Why this chapter exists

Do not start a real Playwright automation repo from a generic harness template alone.

A generic template is useful only as a starting architecture. Before Claude Code creates folders, files, agents, page objects, API clients, and starter tests, it needs application-specific truth. That truth must be written into a small set of predictable artifacts.

This chapter is the discovery and customization phase.

Its job is to turn:

generic harness principles

into:

application-specific scaffolding inputs

Only after this chapter is complete should you move to the scaffolding chapter.

Set up Claude Code for discovery

Before you explore the application, configure Claude Code so it works safely and efficiently during the discovery phase.

Start in Plan Mode

Discovery is a read-only activity. You are learning, not building. Start Claude Code in Plan Mode so it can read files, run shell commands, and explore — but cannot edit your source code:

claude --permission-mode plan

You can also press Shift+Tab twice during an existing session to switch into Plan Mode. The status bar shows ⏸ plan mode on when active.

Plan Mode is ideal here because:

Claude can navigate the running application, read its source, and explore routes without accidentally creating files
you stay in control: Claude proposes a plan, and you approve before any changes happen
if discovery spans multiple sessions, you can resume with claude --continue

Name the session

Give this session a descriptive name so you can resume it later:

claude --permission-mode plan -n discovery

Or during the session:

/rename discovery

If you close the terminal and need to come back, run:

claude --resume discovery

Let auto memory work for you

Claude Code has auto memory enabled by default. As you explore the application and correct Claude's assumptions, it saves notes for itself (build commands, architecture observations, naming patterns) in ~/.claude/projects/<project>/memory/. These notes persist across sessions.

You do not need to configure this. Just be aware that Claude is already learning from your corrections during discovery. If it misnames a feature area and you correct it, it will remember the correction next session.

End state of this chapter

By the end of this chapter, you must have these files:

docs/specs/product-under-test.md
docs/specs/ui-journeys.md
docs/specs/api-endpoints.md
playwright-scaffolding.md

These files are not optional. They are the minimum durable handoff from discovery into scaffolding.

Core rule

The application is the source of truth.
The generic template is only the starting shape.

If the application structure conflicts with the generic template, keep the architectural principles, but replace the placeholders with the application's real structure.

Discovery priority order

When learning a product, use the richest source you have. In most cases, use this order:

Site Map page
Header navigation
Footer links
Authenticated navigation after login
Product docs, help center, onboarding flows
API docs, Postman collections, OpenAPI specs
Frontend route config or source code, if accessible
Exploratory traversal of the running app

You do not need every source. Use the best available sources and combine them where helpful.

What Claude Code should learn during discovery

Before any repo is scaffolded, Claude Code should extract:

real page names
route names or route patterns
feature areas
user roles
auth/session model
critical business flows
API domain groupings
endpoint families
main data entities
smoke-critical journeys
risky or brittle areas worth prioritizing

This is what turns a generic harness into a project-specific one.

Step 1 — Create a discovery workspace

Before exploring the application, create the following folders locally in your future repo or in a scratch project folder:

docs/specs/
docs/discovery/

The docs/discovery/ folder is temporary or semi-temporary working space.
The docs/specs/ folder is durable project memory.

Suggested discovery files:

docs/discovery/site-map-notes.md
docs/discovery/navigation-notes.md
docs/discovery/api-notes.md
docs/discovery/auth-notes.md
docs/discovery/open-questions.md

You may later merge or archive these, but during discovery they help keep findings explicit.

Step 2 — Inspect the Site Map, if one exists

If the application has a visible Site Map page, start there. This is often the fastest way to capture the product’s real information architecture.

A Site Map page may appear as:

Site Map
All Pages
Browse All
Documentation Index
Footer link directory
Admin navigation tree
Help center directory

What to extract from the Site Map

Capture:

page titles
hierarchy
grouping by section
naming conventions
likely user-facing vs admin-facing areas
repeated patterns such as /account/*, /settings/*, /orders/*

Copy-paste prompt for Claude Code

Traverse the Site Map page and extract the real application structure.

Capture:
- all visible pages
- page hierarchy
- section names
- naming conventions
- route patterns if visible

Group the pages into logical product domains.

Write findings into:
- docs/discovery/site-map-notes.md
- docs/specs/product-under-test.md

Do not scaffold code yet.

What to do manually if Claude Code misses context

Review the generated notes and correct:

duplicate pages
public vs authenticated distinctions
pages that are present but not test-worthy
pages that exist only as support/legal content
internal/admin areas that should be isolated into separate domains

Step 3 — If there is no Site Map, traverse the app deliberately

If no Site Map exists, discover structure from navigation and exploratory traversal.

Traverse these areas in order

landing page
primary nav
footer nav
auth entry points
post-login landing page
settings/account/admin menus
search/browse/detail pages
transaction flows
error or empty states that appear during use

Capture as you go

For each page or route, note:

page name
route or URL pattern
purpose
domain/feature area
whether it belongs in smoke, regression, or low-priority coverage
whether it is public, authenticated, or role-restricted

Copy-paste prompt for Claude Code

Explore the running application and infer its real structure.

From navigation, pages, and visible flows, extract:
- top-level pages
- nested pages
- route patterns
- major user journeys
- public vs authenticated areas
- likely role-specific areas

Write structured notes into:
- docs/discovery/navigation-notes.md
- docs/specs/product-under-test.md

Do not scaffold code yet.

Step 4 — Discover authentication and session behavior

A Playwright harness becomes much better when auth behavior is understood before scaffolding.

Determine the auth model

Capture:

login page or entry point
auth type: session cookies, token, OAuth, SSO, magic link, MFA, etc.
logout mechanism
session persistence expectations
whether storageState is likely to help
whether API and UI share auth context
whether different roles need different saved states

Document edge cases

Note anything that affects automation, such as:

CAPTCHA in lower environments
MFA bypass in test environments
login redirects
region-specific or tenant-specific login pages
expired sessions causing flake
rate limits on auth endpoints

Copy-paste prompt for Claude Code

Inspect the authentication model of the application.

Document:
- login entry points
- auth type
- session persistence behavior
- likely Playwright storageState strategy
- role differences if visible
- known automation risks

Write findings into:
- docs/discovery/auth-notes.md
- docs/specs/product-under-test.md

Step 5 — Discover the UI journeys that actually matter

A good harness does not start by automating random pages. It starts with meaningful journeys.

Identify at least these categories

Smoke journeys

Short, critical checks that prove the application is alive.

Examples:

sign in
load dashboard
browse catalog
open detail page
complete checkout
create a simple record
fetch a critical account page

Regression journeys

Broader user behavior and business logic.

Examples:

edit profile
update payment method
create/edit/delete flow
permission checks
filtering/sorting/search
validation and error handling

Accessibility targets

Pages worth early a11y coverage.

Examples:

sign-in form
checkout flow
key dashboard
search results
important modal/dialog workflows

What to avoid at this stage

Do not over-specify every test case yet.
This chapter is for journey mapping, not full suite design.

Copy-paste prompt for Claude Code

Based on the discovered product structure, identify the most important UI journeys.

Organize them into:
- smoke journeys
- regression journeys
- accessibility targets

Write the result into:
- docs/specs/ui-journeys.md

Focus on business-critical user flows rather than exhaustive test cases.

Step 6 — Discover the API surface

The harness should support API automation from day one, ideally using Playwright APIRequestContext.

Learn the API structure

If you have API docs, Postman collections, or OpenAPI, capture:

endpoint groups
auth endpoints
main resources
create/read/update/delete patterns
request/response formats
special headers
environment differences
known rate limits
unstable endpoints or async workflows

Group endpoints into client domains

Avoid dumping raw endpoint lists without structure.

Good grouping examples:

Auth
Users
Orders
Catalog
Billing
Reporting
Admin

Copy-paste prompt for Claude Code

Discover the API structure for the application.

Capture:
- endpoint groups
- auth model
- key resources
- common request patterns
- important response contracts
- risks and special behaviors

Organize the output by domain and write it into:
- docs/specs/api-endpoints.md

Assume the future harness will use Playwright APIRequestContext unless there is a strong reason not to.

Step 7 — Write `docs/specs/product-under-test.md`

This file is the highest-level description of the system under test.

Required sections

Use this exact structure as a starting point (or update environments names if internally company calls them differently):

# Product Under Test

## Overview
Short description of the product.

## Environments
- local:
- qa:
- staging:
- production:

## User Roles
- guest
- authenticated user
- admin
- support
- other app-specific roles

## Feature Areas
- Authentication
- Search
- Catalog
- Checkout
- Account
- Reporting
- Admin
- app-specific modules

## Routing / URL Patterns
List important routes or patterns.

## Authentication Model
Describe login, session model, saved state strategy, and automation concerns.

## Major Risks for Automation
List risk areas that can cause flakiness or complexity.

## Notes
Anything else important for future agents.

Writing guidance

This file should be concise, but not vague.
Write for a future agent who lands in the repo with no chat history.

Step 8 — Write `docs/specs/ui-journeys.md`

This file defines where early UI automation should go. Talk to your product owner/product manager. Capture everything they respond to the question "Which pieces of functionality, if broken, would stop the release to Prod?" and put it under "Regression Journeys" section.

Recommended structure

# UI Journeys

## Smoke Journeys
- login
- open primary landing page
- complete business-critical short flow

## Regression Journeys
- account/settings behavior
- create/edit/delete flows
- validation scenarios
- permission boundaries

## Accessibility Targets
- forms
- modals
- key landing pages
- critical transaction flows

## Priority Notes
Explain which journeys matter most and why.

Writing guidance

Use product language, not generic language.

Bad:

“dashboard stuff”
“main flow”

Better:

“Customer checkout with saved address”
“Admin creates a new coupon”
“Support user searches for an order and opens details”

Step 9 — Write `docs/specs/api-endpoints.md`

This file tells the scaffolding step how API clients should be organized.

Recommended structure

# API Endpoints

## Auth
- POST /login
- POST /logout
- refresh/session endpoints

## <Domain Name>
- GET /resource
- POST /resource
- PUT /resource/:id
- DELETE /resource/:id

## Contracts and Validation Notes
- required headers
- schema concerns
- pagination
- async processing
- rate limiting

Writing guidance

Do not try to document every single low-value endpoint. Capture the domain structure that will shape the harness.

Step 10 — Generate `playwright-scaffolding.md`

This is the most important artifact in the chapter.

playwright-scaffolding.md is the custom blueprint Claude Code will use in the next chapter to scaffold the repo.

It should be derived from:

the generic harness principles
product-under-test.md
ui-journeys.md
api-endpoints.md

What `playwright-scaffolding.md` must contain

At minimum, it should specify:

real page-object names
real feature domains
real API client groupings
fixture strategy
likely flow helpers
likely reusable component objects
likely smoke/regression/a11y grouping
auth strategy
expected environments
early plan and agent workflow expectations
rules like “selectors live in page objects”
rules like “use Playwright APIRequestContext for API clients”

Copy-paste prompt for Claude Code

Create playwright-scaffolding.md by reconciling the generic Playwright harness architecture with the real application structure captured in:

- docs/specs/product-under-test.md
- docs/specs/ui-journeys.md
- docs/specs/api-endpoints.md

Rules:
- replace generic names with real application terminology
- keep the harness architecture, but customize folder and file naming to the product
- define likely page objects, API clients, flows, reusable components, fixtures, and starter test groupings
- encode agent workflow expectations for planner, generator, and evaluator
- assume Playwright + TypeScript for UI and API automation
- assume Playwright APIRequestContext for API tests unless the app clearly requires otherwise
- assume selectors should live inside the owning page objects

Write the result to:
- playwright-scaffolding.md

Step 11 — Validate the artifacts before moving on

Before you continue to the next chapter, review the artifacts.

Checklist

product-under-test.md names real feature areas
ui-journeys.md uses real business flows
api-endpoints.md is grouped by meaningful client domains
playwright-scaffolding.md uses real app terminology
generic names were replaced where real names are known
auth/session assumptions are explicit
the future harness shape is clear enough to scaffold

If this is not true, fix the artifacts before moving on.

What not to do in this chapter

Do not:

generate code yet
create page objects yet
create API clients yet
write detailed test cases yet
keep generic names when the app provides better ones
rely on chat memory instead of writing artifacts to disk

This is a discovery and customization chapter, not an implementation chapter.

Deliverables from Chapter 1

You are ready for the next chapter only when these files exist and are usable:

docs/specs/product-under-test.md
docs/specs/ui-journeys.md
docs/specs/api-endpoints.md
playwright-scaffolding.md

Mental model

generic harness architecture
        +
real product structure
        =
custom blueprint for scaffolding

That custom blueprint is playwright-scaffolding.md.

Pre-Requisites: Discover the Application and Produce Customization Artifacts

Why this chapter exists

Set up Claude Code for discovery

Start in Plan Mode

Name the session

Let auto memory work for you

End state of this chapter

Core rule

Discovery priority order

What Claude Code should learn during discovery

Step 1 — Create a discovery workspace

Step 2 — Inspect the Site Map, if one exists

What to extract from the Site Map

Copy-paste prompt for Claude Code

What to do manually if Claude Code misses context

Step 3 — If there is no Site Map, traverse the app deliberately

Traverse these areas in order

Capture as you go

Copy-paste prompt for Claude Code

Step 4 — Discover authentication and session behavior

Determine the auth model

Document edge cases

Copy-paste prompt for Claude Code

Step 5 — Discover the UI journeys that actually matter

Identify at least these categories

Smoke journeys

Regression journeys

Accessibility targets

What to avoid at this stage

Copy-paste prompt for Claude Code

Step 6 — Discover the API surface

Learn the API structure

Group endpoints into client domains

Copy-paste prompt for Claude Code

Step 7 — Write docs/specs/product-under-test.md

Required sections

Writing guidance

Step 8 — Write docs/specs/ui-journeys.md

Recommended structure

Writing guidance

Step 9 — Write docs/specs/api-endpoints.md

Recommended structure

Writing guidance

Step 10 — Generate playwright-scaffolding.md

What playwright-scaffolding.md must contain

Copy-paste prompt for Claude Code

Step 11 — Validate the artifacts before moving on

Checklist

What not to do in this chapter

Deliverables from Chapter 1

Mental model

Step 7 — Write `docs/specs/product-under-test.md`

Step 8 — Write `docs/specs/ui-journeys.md`

Step 9 — Write `docs/specs/api-endpoints.md`

Step 10 — Generate `playwright-scaffolding.md`

What `playwright-scaffolding.md` must contain