DEV Community

Cover image for Stop Spending Two Weeks Configuring Playwright. Use a Skeleton Built for AI Adaptation.🤖
Albert Alov
Albert Alov

Posted on

Stop Spending Two Weeks Configuring Playwright. Use a Skeleton Built for AI Adaptation.🤖

#playwright #testing #ai #typescript

Every SDET joining a new project goes through the same ritual.

Run npm init playwright@latest. Spend day one on ESLint, Prettier, Husky. Day two on folder structure debates. Day three writing a Base API client. By the time you write a test that actually validates business logic, a week is gone.

Boilerplates exist to solve this — but they have a fundamental flaw: adapting one to your domain takes almost as long as starting from scratch. You're still hunting down every SamplePageObject and example-login.spec.ts and manually replacing them with your actual app's concepts.

What if the boilerplate came pre-wired for an AI agent to adapt it for you?

What is playwright-ai-skeleton?

It's a production-ready E2E framework built on Playwright and TypeScript, following patterns I've used across multiple real projects:

  • Page Object Model with strictly private locators — business intent exposed, Playwright internals hidden
  • Hybrid testing — API clients and UI Page Objects sharing the same Playwright fixture chain
  • API-first data setup — immutable data builders for fast, reliable state injection without UI
  • Zod validation — fails fast if .env or API responses don't match the expected schema
  • Worker-scoped auth — one login per worker instead of one per test, cutting CI time significantly
  • Pre-wired infrastructure — GitHub Actions, Docker Compose, and a Slack reporter included

But the architecture is not the point. The point is what's inside docs/.

The adaptation guide

The repo ships with two files designed not for human reading, but for AI input:

  • docs/CONVENTIONS.md — strict architectural rules the AI must follow
  • docs/ADAPTATION_GUIDE.md — a step-by-step prompt that drives the AI through customizing the skeleton for your specific domain

The entire onboarding flow looks like this:

git clone https://github.com/vola-trebla/playwright-ai-skeleton.git my-project
cd my-project
# Open in Cursor or Claude Code, then:
# "Read docs/ADAPTATION_GUIDE.md and adapt this for an e-commerce app called ShopFrog"
Enter fullscreen mode Exit fullscreen mode

The AI reads the guide, understands the architecture's constraints, and starts a structured conversation:

  • What is your base URL?
  • What are your core domain entities?
  • How does authentication work?

After you answer, it renames files, generates your API clients, scaffolds your Page Objects, sets up Zod schemas, and writes your first smoke test — all consistent with the conventions in CONVENTIONS.md.

From git clone to a compiling, project-specific framework in under 10 minutes.

Why strict conventions matter for AI

AI coding assistants are fast but undirected — ask them to "write a Playwright framework" and you get a mix of outdated patterns, inconsistent selectors, and business logic leaking into locator files.

CONVENTIONS.md constrains the output:

  • Use getByRole — never raw CSS selectors
  • Expose login() — never click() on the Page Object surface
  • Data builders are immutable — no test mutates shared state

The AI doesn't just write code. It writes code that conforms to a specific architectural standard, enforced by the guide it was given.

Try it 

git clone https://github.com/vola-trebla/playwright-ai-skeleton.git
Enter fullscreen mode Exit fullscreen mode

Feed docs/ADAPTATION_GUIDE.md to Claude or Copilot. Answer the questions. Ship your first test today.

The infrastructure problem is solved. Your job is testing business logic — not configuring linters.

Top comments (0)