Tools: The Scaffold: Playwright Project Structure Built for AI

🤔 What Is a Scaffold? ## 🧱 What the Scaffold Gives You ## 🤖 But Here's the Real Point ## 🔌 Works With Your Tools ## 🐳 One Command to Start 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. 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. 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. 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. 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. 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 Templates let you quickly answer FAQs or store snippets for re-use. Are you sure you want to hide this comment? It will become hidden in your post, but will still be visible via the comment's permalink. Hide child comments as well For further actions, you may consider blocking this person and/or reporting abuse CODE_BLOCK: 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 Enter fullscreen mode Exit fullscreen mode CODE_BLOCK: 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 CODE_BLOCK: 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 - A folder for page objects - A folder for test data - A single import point for all fixtures - Conventions for selectors, naming, and test structure - 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. - 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/