---
name: e2e-page-object
description: Create or update Playwright page objects from live UI exploration with Humand conventions
---

# /e2e-page-object - Create or Update a Page Object

Build or refine a page object class for a specific page/flow using current UI state and Humand POM conventions.

## Workspace

This skill supports two layouts:

- **Single-app** (`<root>/e2e/playwright.config.ts`): resolve `<workspace>/` to `e2e/`.
- **Multi-app** (`<root>/<app>/playwright.config.ts` per app, e.g. `web/`, `backoffice/`): resolve `<workspace>/` to that app's folder.

Detect by probing for `playwright.config.ts` or from the target URL/app. If ambiguous, ASK before proceeding.

## Scope

- Works inside the resolved E2E workspace.
- Outputs:
  - `<workspace>/pages/{PageName}.ts`
  - optional `<workspace>/fixtures/base.fixture.ts` update

## Knowledge References

Read these before generating code.

### Required

1. `knowledge/patterns/page-objects.md`
2. `knowledge/writing-tests/locators.md`
3. `knowledge/writing-tests/fixtures.md`
4. `knowledge/humand/conventions.md`

### Conditional

1. `knowledge/patterns/react-patterns.md` (if target page uses reactive/complex MUI composition)
2. `knowledge/writing-tests/forms.md` (if POM covers forms/wizard flows)
3. `knowledge/patterns/authentication.md` (if POM includes auth/community screens)

### Trigger checklist

- Are there complex React/MUI interactive regions in target page? -> include `react-patterns.md`
- Does the page include forms, validation, or wizard progression? -> include `forms.md`
- Is page object for login/session/community selection flows? -> include `authentication.md`

Before editing page objects, resolve which Conditional docs apply and list them in your working response.

And align with:

- `rules/playwright-generator.mdc`

## Inputs

- `pageName` (required): example `GoalsCyclesPage`
- `url` (required): example `http://localhost:3001/goals/cycles`
- `app` (required for multi-app, optional for single-app)
- `mode` (optional): `create` or `update` (default auto-detect)

## Workflow

### 0) Resolve app context

Read `.e2e/context.local.json`. If missing, suggest running `/e2e-setup` first. If the dev opts to proceed without it, run in **degraded mode** — build POM from live UI exploration only, without aligning method names against the underlying components.

When the target workspace matches an `apps[<name>]` key (e.g. workspace `web` ↔ `apps.web`), use that app's `repoPath` and `pagesPath` to inspect the page component and align POM method naming with the implementation.

### 1) Inspect existing code

- If page object already exists, preserve naming and method style.
- Reuse existing shared helpers from the shared base:
  - Multi-app: `<root>/shared/pages/BasePage.ts`
  - Single-app: `<workspace>/pages/BasePage.ts`

### 2) Explore UI with MCP

- Navigate to target route.
- Snapshot interactive controls, tabs, dialogs, forms, and list/table regions.

### 3) Build POM structure

- readonly locator properties
- user-action methods (`goto`, `create*`, `switch*`, `toggle*`, etc.)
- `expect*` helper methods for repeated page-state checks (Humand pattern)

### 4) Keep test readability high

- Avoid leaking raw locator details into test files.
- Keep method names behavior-oriented.
- Prefer accessibility-first locators and use `data-testid` only when needed.

### 5) Fixture registration

- If a new page object is introduced, add it to `<workspace>/fixtures/base.fixture.ts`.

### 6) Local verification

- Prefer validating POM changes through the local `package.json` scripts (or `npx playwright test --config=<workspace>/playwright.config.ts ...`) so the local Playwright version and browser path stay aligned.
- If the flow depends on auth, refresh storage state before rerunning focused specs.

### 7) Cleanup

Exploration writes throwaway page snapshots and console logs to `<root>/.playwright-mcp/`. Once the page object is written:

- call `browser_close` to end the MCP session and trigger any consumer hooks
- delete the `.playwright-mcp/` directory at the project root (or its contents)

These artifacts are not consumed by downstream skills and should not be committed.

## MCP tools used

- `browser_navigate`
- `browser_snapshot`
- `browser_close`

## Out of scope

- Full test generation from specs (use `/e2e-generate`)
- Failure repair loops (use `/e2e-heal`)