Init

/pw-kit:init — Scaffold a New Playwright + TypeScript Project

Follow this 6-phase workflow when a user asks you to bootstrap a brand-new Playwright + TypeScript test project with this kit's conventions pre-wired.

Required Inputs

Before starting, gather:

1. Project name (used for package.json name field)
2. Application base URL (for .env template)
3. Ticket prefix (e.g., DEVQA, JIRA, LIN, GH) — for test naming. Default to plugin's userConfig.ticketPrefix if set, else ask.
4. Target directory — where should the project be created?
5. Feature module names (optional) — sample modules to scaffold sub-folders for, e.g., users, orders, products. Default to one example: example.

If any are missing, ask before proceeding.

Phase 1 — Create Folder Structure

mkdir -p <project>/{pages,tests,api,modals,data,docs,.vscode}
mkdir -p <project>/pages/{components}
mkdir -p <project>/tests/{utility,user-group-permissions,ci-cd-smoke}
mkdir -p <project>/tests/utility/example-test-patterns
mkdir -p <project>/api/{custom,integrations}

For each <feature> module:

mkdir -p <project>/pages/<feature>
mkdir -p <project>/tests/<feature>

Phase 2 — Write Configuration Files

Generate from the templates in assets/:

Substitute {{PROJECT_NAME}}, {{BASE_URL_DEFAULT}}, {{TICKET_PREFIX}} placeholders during write.

Phase 3 — Write Base Class Skeletons

The kit ships a lean starter — three base classes that cover ~80% of modern SaaS pages. Generate these files (templates in assets/):

Each contains the essential methods documented in the pom skill — locators for common app frame elements, grid dynamic locators keyed by gridPrefix, date helpers (typeDateValue, formatDateByLocale, relative-year vars), form helpers (toggleSwitch, filterSingleSelect), modal helpers, save variants, etc.

Mark optional sections clearly:

// ─────────────────────────────────────────────────────────────────────────────
// OPTIONAL: Permissions test helpers
// Remove this block if you don't have a permissions/access-control system.
// ─────────────────────────────────────────────────────────────────────────────
async verifyNoSecurityRightsState(): Promise<void> { /* ... */ }
async verifyViewOnlyRightsState(): Promise<void> { /* ... */ }
// ...

Teams prune what they don't use; the comments make it obvious where to cut.

Phase 4 — Write the Fixture Registry

Generate pages/base-pages-fixture.ts from assets/base-pages-fixture.ts.tmpl. The template includes:

• Browser + browserPage root fixtures
• LoginPage + HomePage stub imports (placeholder POMs)
• CommonTestFunctions for randomization
• Utility fixtures: todayString, futureDateString, newDescription, isCI
• Alphabetical placement comments for new entries

// Maintain alphabetical order in BOTH the Pages interface AND the test.extend body.
// PRs that break this are flagged in code review.

Phase 5 — Seed Example Files

Login/Home stub POMs

pages/login-page.ts
pages/home-page.ts

Minimal but functional — show the user how a real POM is structured.

Common test functions

tests/utility/common-test-functions.ts

A CommonTestFunctions class with randomBoolean(), randomNumber(length?), randomElement(), getRandomNumberByLength(length), getDateNDaysFromNow(days, culture?).

Example test patterns (excluded from execution)

Drop the example template tests in tests/utility/example-test-patterns/:

example-grid-test.spec.ts          # search, filter, sort, paginate, delete
example-edit-test.spec.ts          # full CRUD on edit page
example-modal-test.spec.ts         # opening, confirming, cancelling a modal

These show the patterns in context. playwright.config.ts has testIgnore: ['**/utility/example-test-patterns/**'] so they don't run.

AGENTS.md

Generate AGENTS.md from assets/AGENTS.md.tmpl. This is the project rules document that AI agents read. It compresses the conventions taught by each skill into a single reference at the project root.

README.md

Generate README.md from assets/README.md.tmpl with prerequisites, install steps, and usage.

Phase 6 — Install Dependencies and Verify

cd <project>
npm install
npx playwright install --with-deps

Then run a smoke check:

npx playwright test --list      # should print the example tests (excluded), 0 actual tests
npx eslint . --ext .ts          # should complete without errors
npx prettier --check .          # should pass

If everything passes:

Project initialized at <path>. Next steps:

1. Fill in .env with your real BASE_URL and credentials (copy .env.example to .env).
2. Write your first POM following the pom skill conventions.
3. Register it in base-pages-fixture.ts (alphabetical).
4. Invoke /pw-kit:new-test to write your first test from a ticket.

Optional: pin Playwright version via Context7 MCP

The template uses "@playwright/test": "latest" for convenience. For production projects, pin to a specific version. Use Context7 MCP to look up the current stable release and any breaking-change notes before pinning:

1. Resolve Playwright Test library id via Context7
2. Fetch the latest stable version + recent changelog
3. Edit package.json: replace "latest" with the pinned version (e.g. "1.49.0")
4. Re-run npm install

Customization After Init

The kit ships lean. Customize for your project:

Each customization is opt-in. The kit doesn't impose patterns you don't need.

Common Mistakes During Init

Further Reading

• assets/ — all the template files. Each is a complete, working example with placeholder substitutions.