The Scaffold: Playwright Project Structure Built for AI

Have you ever started a new Playwright project and spent the first two days just figuring out where things go? Where do selectors live? How do page objects get into tests? Where does test data belong?

Most teams answer these questions ad hoc, and end up with a different answer every time. After a few months the codebase looks like that - a mix of conventions, inconsistencies, and copy-pasted patterns that no one quite owns.

A scaffold solves this before it starts. But the one we're exploring here was designed with a twist. It wasn't just built for humans. It was built for AI agents to work with.

🤔 What Is a Scaffold?

A scaffold is a pre-built project structure that answers all the "where does this go?" questions upfront. Before you write a single test, you already have:

• A folder for page objects




• A folder for test data




• A single import point for all fixtures




• Conventions for selectors, naming, and test structure

Think of it like a city grid. Before buildings go up, the streets are laid. You always know how to get from A to B because the plan was made in advance.

pages/          → UI page objects and components

tests/          → Test scenarios, organized by area and type

test-data/      → Factories (dynamic) and static JSON (edge cases)

fixtures/       → Dependency injection: wires everything together

enums/          → No hardcoded strings anywhere

config/         → URLs and environment settings

.claude/        → AI instruction files: skills and the orchestrator

🧱 What the Scaffold Gives You

Beyond folder structure, the scaffold comes with working patterns for every layer of a test suite:

• Page Object Model: UI pages represented as TypeScript classes. Locators and actions in one place. When a selector changes, you update one file. POM




• Fixtures and Dependency Injection: Page objects arrive in tests already instantiated. No new LoginPage(page) boilerplate, no manual setup.




• Type-Safe API Testing: Zod - a runtime type validation library - validates API response shapes. If the backend changes a field name, the test fails immediately. Zod




• Smart Test Data: Faker - a library for generating realistic dummy data - creates unique values every run. Static JSON handles edge cases and invalid inputs.




• Strict Linting: ESLint and Prettier enforce conventions automatically. Pre-commit hooks block anything that doesn't meet the standard. If you want to see this in action, the Never Commit Broken Code Again article walks through the full setup.

🤖 But Here's the Real Point

All of that is table stakes for a modern Playwright project. What makes this scaffold different is the .claude/ folder.

On the root level of the project, there is a file called CLAUDE.md and a .claude/ folder. Inside it lives a separate folder for each skill, along with a file for each one. Together, they define a complete instruction set for an AI agent. Every rule, every pattern, every forbidden anti-pattern is written down in a format that an AI reads before generating a single line of code.

The scaffold was designed so that an AI agent can build and extend it correctly, without supervision.

The rest of this series is about exactly that: how agentic QA works, what those files contain, and how you can use AI to build a professional test automation framework faster than you thought possible.

🔌 Works With Your Tools

The scaffold isn't locked to a single AI tool. The same rules and skills are provided in three formats:

• Claude Code reads CLAUDE.md and .claude/skills/




• Cursor reads .cursor/rules/ and .cursor/skills/




• GitHub Copilot reads .github/copilot-instructions.md and .github/instructions/

Same architecture, same conventions, same guardrails. You pick the tool you prefer and the scaffold works with it.

🐳 One Command to Start

The scaffold ships with a Dev Container configuration. If you have Docker installed, you open the project and everything is ready: Node, Playwright browsers, Python, browser-use, and AI CLIs. No manual setup, no dependency hunting, no "it works on my machine". One command, fully configured environment.

🙏🏻 Thank you for reading! This article was the setup. Starting from the next one, we get into the part that changes how you think about test automation. That's the AI side of it. See you there.

You can find the Public README.md file for the scaffold on GitHub: Playwright Scaffold

You can get access to the private GitHub repository here: Get Access