agentic-playwright

See it

From the (empty) directory your project should live in — the . means "scaffold right here, and name the project after this folder" (a fresh git clone of an empty repo works too). Prefer a new subfolder? Pass a name instead of .:

npm create agentic-playwright . -- --demo

Zero questions. Scaffolds the framework, installs dependencies and a browser, and ends by running the smoke test against a live demo application — you see green before writing a line. Under 5 minutes on normal broadband.

Without the rulebook vs with it

The same prompt — "write a test for the product search" — to the same AI assistant:

// ❌ Unsupervised: XPath, hard waits, `any`, magic timeouts, no structure
test('search', async ({ page }) => {
    await page.goto('https://practicesoftwaretesting.com');
    await page.locator('//input[@id="search-query"]').fill('pliers');
    await page.locator('//button[@type="submit"]').click();
    await page.waitForTimeout(5000);
    const cards: any = await page.$$('.card');
    expect(cards.length > 0).toBe(true);
});

// ✅ With Agentic Playwright: fixtures, steps, web-first assertions
import { expect, test } from '../../../fixtures/pom/test-options';

test(
    'should show only matching products when searching',
    { tag: '@regression' },
    async ({ homePage }) => {
        await test.step('GIVEN the user is on the home page', async () => {
            await homePage.open();
        });

        await test.step('WHEN the user searches for "pliers"', async () => {
            await homePage.searchFor('pliers');
        });

        await test.step('THEN every result matches the search term', async () => {
            await expect(homePage.searchCaption).toContainText('pliers');
            await expect(homePage.productNames.first()).toContainText('Pliers');
        });
    }
);

Dependency-injected page objects, Given/When/Then steps, web-first assertions, no hard waits, no any, one tag per test — enforced by a Constitution and 17 skills the assistant loads automatically, with a write-time hook that blocks the forbidden patterns outright.

Not affiliated with Microsoft. Playwright is an open-source project by Microsoft; this scaffold builds on it.

This is a scaffold, not a finished framework. The example files (AppPage, login.spec.ts, NavigationComponent, etc.) demonstrate the patterns and conventions you should follow. Replace them with your real application's pages, tests, and data as you build out your test suite.

Table of Contents

• Features
• Prerequisites
• Quick Start: npm create
• Quick Start: Dev Container
  • Claude Code Custom Status Line
• Quick Start: Local Setup Script
• Manual Installation
• Getting Started: Adapting the Scaffold
• Project Structure
• Configuration
• Environment Variables
• Running Tests
• Tag Reference
• Writing Tests
• Page Object Model
• API Testing
• Data Strategy
• Authentication Setup
• Code Quality
• Coding Standards
• Core Principles (The Constitution)
• AI-Assisted Development Workflow
• AI Rules Architecture
• Architecture Overview
• Troubleshooting
• Agentic Playwright Pro
• License

Features

• TypeScript -- Full type safety with strict mode enabled
• Page Object Model -- Maintainable and scalable test architecture
• Fixture-based Architecture -- Reusable test components with dependency injection
• API Testing -- Built-in apiRequest fixture with Zod schema validation and helper fixtures for setup/teardown
• Multi-browser Support -- Chrome, Firefox, and WebKit configurations
• Environment Management -- Flexible .env configuration with multi-environment support
• Authentication Handling -- Pre-configured storage state for authenticated tests
• Code Quality -- ESLint + Prettier + Husky pre-commit hooks
• Parallel Execution -- Fast test runs with configurable workers
• Comprehensive Reporting -- HTML reports with traces, screenshots, and videos
• AI-Assisted Development -- Modular orchestrator rules for Claude Code, Cursor, and GitHub Copilot with glob-scoped auto-loading. Each tool's rule tree (.claude/, .cursor/, .github/instructions/) is self-contained and stands alone.
• Confidence-Gated Workflow -- The ai-native-workflow skill is the sole entry-point router for non-trivial work. Every plan must include Confidence: <1-10>, Rationale, and Unknowns; below confidence 5 the agent is required to stop and ask the user for the missing primary input rather than emit a plan built on guesses.
• Constitution Enforcement Hook -- .claude/scripts/enforce_constitution.py is wired as a Claude Code PreToolUse hook in .claude/settings.json. It blocks any Write/Edit/MultiEdit that would introduce a mechanically-detectable WON'T violation (waitForTimeout, z.object in schemas, XPath, @playwright/test imports in specs, .json static data, the @functional tag, tags on test.describe()) before the file is ever written -- a hard backstop beneath the prompt-level rules.
• Version Single-Source -- the root VERSION file is the one source of truth for the product version. npm run version:stamp writes it into package.json; npm run check:version asserts VERSION == package.json == the latest CHANGELOG.md heading and fails on drift. Gated in .husky/pre-commit (when a version surface is staged) and in CI (skill-lint.yml).
• Pre-Commit Drift Lints -- npm run check:skills-drift keeps Constitution rules anchored in their owning skill's Critical block; npm run check:skills-references walks all three rule trees (.claude/skills/, .cursor/skills/, .github/instructions/, .github/skills/) and catches broken pointers, orphan references, and broken section anchors between each SKILL.md and its references/ siblings. Both fire from .husky/pre-commit whenever any of those trees has files staged.
• Upstream Skill Sync -- skills-lock.json records the SHA-256 of the locally vendored copies of skill-creator (from anthropics/skills) and playwright-cli (from @playwright/cli). npm run skills:verify re-hashes the local files and exits non-zero on drift; npm run skills:reinstall fetches upstream, overwrites .claude/skills/<name>/SKILL.md and .cursor/skills/<name>/SKILL.md, and refreshes the lock; npm run skills:update re-locks after intentional local edits.
• Playwright CLI Exploration -- playwright-cli is the default browser exploration path for UI discovery, tracing, storage inspection, and flow capture
• Out-of-the-Box Anthropic Skills -- playwright-cli and skill-creator are reinstalled fresh from the upstream Anthropic packages and tracked via skills-lock.json for reproducible installs
• AI Task Workflows Playbook -- AI-WORKFLOWS.md maps the exact step sequence for every common flow (API suite for a controller, functional tests from a ticket, E2E suite, debugging, refactors, and more) to its owning skill and phase, with an anti-drift guardrails table -- so AI-assisted execution stays consistent across sessions

Prerequisites

• Node.js v22.x or later
• npm v10.x or later

Quick Start: npm create

The fastest path — scaffold a fresh project with everything wired, straight into the directory you are standing in:

npm create agentic-playwright . -- --demo

Why the .? It scaffolds into the current directory and names the project after the folder — the natural fit when you have already created (or cloned) an empty repo for your tests. The directory must be empty apart from repo bookkeeping like .git; if a git repo already