How to Structure a Playwright Test Suite That Stays Fast at 100 Tests

Picture the Playwright test suite you actually want. A hundred tests deep, and it still runs fast. A new starter opens the folder and instantly sees where everything lives. CI comes back green in minutes, not coffee breaks, and when something does break, the failure is real, not flake.

That is not a fantasy. A scalable Playwright test suite is mostly a question of structure, and structure is exactly the thing nobody remembers to design until it is already too late. Your tests are probably fine. It is the architecture around them that quietly rots.

That is the gap the playwright-pro agent skill exists to close. It scaffolds and audits the architecture layer of a Playwright suite: directory layout, config, fixtures, auth state, retries, and CI execution, so the structure around your tests is designed on purpose instead of by accident.

Why Playwright Test Suite Structure Matters

Here is the uncomfortable truth about Playwright: writing your first test is a joy. Keeping a hundred of them fast, isolated, and readable is a slow-motion nightmare. And the thing that decides which way it goes is almost never test-writing skill. It is Playwright test architecture, the boring, load-bearing decisions you make before the suite gets big.

Get the structure right and new tests slot into an obvious place, auth happens once, and CI stays quick. Get it wrong and every new test makes the suite slightly worse, until one day you are fighting the tooling instead of shipping.

Common Playwright Architecture Problems

If you have felt the 11pm version of this, a red CI run and a suite that fights you instead of helping, it usually traces back to the same handful of structural problems:

• every test logs in from scratch instead of reusing saved Playwright auth state
• specs, page objects, and fixtures all live in one flat folder
• retries are cranked up to hide flaky tests instead of fixing them
• CI runs everything on a single worker and takes far too long
• playwright.config.ts is copy-pasted between environments until it quietly diverges

None of these are test-writing problems, and no amount of writing better tests will save you from them. They are architecture problems, and they are exactly what the skill targets.

How playwright-pro Scaffolds a New Playwright Project

The skill starts by scanning the project, reading package.json and checking whether a playwright.config.ts and tests/ directory already exist. If it is a clean slate, it scaffolds the full recommended structure: config, directory layout, an auth setup project, and the right .gitignore entries.

You do not drive it file by file. You point it at the app and state the intent, something like “set up Playwright for this app”, and it stands up a scalable layout, a sensible multi-browser config, and auth handled once. Then it stops, lists what it created, and asks whether anything needs adjusting before you build on top of it.

You can also name a single concern, such as “add CI sharding” or “wire up fixtures”, and it goes straight to that without touching the rest.

How playwright-pro Audits an Existing Playwright Suite

Most suites are not greenfield. They already exist, and they have already started to sprawl. For those, the skill runs a Playwright test suite audit: an evidence-driven scorecard against the current setup, reported back without changing anything unless you ask.

The part that earns trust is that every finding ties back to a real file or config line rather than vague stylistic judgement. It asks before overwriting an existing config and only creates the files a project is actually missing. It does not barge in and regenerate work that already looks correct. Your good decisions stay yours.

Recommended Playwright Directory Structure

Most of the pain above comes down to one flat folder doing too many jobs. A better Playwright directory structure separates tests by type, keeps shared code out of the specs, and gives auth its own home:

tests/
  e2e/
  api/
  visual/
  public/
pages/
fixtures/
auth/
  setup.ts
  storage-state.json
playwright.config.ts

A quick tour of why it is shaped this way:

• tests/e2e, api, visual, public keep different kinds of tests apart, so a slow visual run does not drag on every quick API check, and each type can have its own config and CI treatment.
• pages/ holds page objects, the shared UI vocabulary your specs lean on, kept out of the test files themselves.
• fixtures/ is your fixture barrel, one place to compose and export custom fixtures rather than re-importing setup into every spec.
• auth/setup.ts signs in once and writes storage-state.json, the saved session the rest of the suite reuses.

Six months from now, a new test has an obvious home, and you still know where everything lives.

Playwright Auth State, Fixtures, Retries, and CI Sharding

Those four are the load-bearing parts of the suite, and they are where a good structure pays for itself.

Auth state, done once. A setup project signs in and saves Playwright storage state to disk, so the rest of the suite skips the login flow entirely. This is usually the single biggest speed win in a suite, and you get it for free once the structure supports it.

Fixtures that compose. A fixtures barrel lets tests declare what they need (a logged-in page, seeded data, a mock server) without copy-pasting setup. That is what keeps a growing suite readable rather than repetitive.

Retries that do not lie. Cranking retries to bury flaky tests just hides genuine failures. The goal is a retry policy that survives real flakiness without masking real breakage, so a green run means green.

CI sharding and config. Parallelism, Playwright CI sharding, trace and video artifacts, and a retry policy all configured deliberately, plus config best practices that keep environments in sync instead of drifting apart. Sharding splits the run across workers so total time drops as you add capacity.

Where the Skill Pays Off

It earns its keep at the two ends of a suite’s life. At the start, it prevents the structural debt that is agony to unwind once fifty tests already depend on the wrong shape. Later, it hands you a way to inspect a suite you inherited and say precisely what is weak, whether that is slow auth, no sharding, or config drift, with evidence attached instead of a shrug.

What playwright-pro Does Not Do

Fair is fair, so here is the boundary.

That boundary is the point, not a weakness. It fixes the layer you cannot easily change later and leaves the craft of writing individual tests where it belongs, with you.

Bottom Line

The playwright-pro skill is at its best when the question is not “how do I write this test” but “how should this whole suite be shaped so it stays fast and maintainable”. It scaffolds that shape for new projects and grades it for the ones you already have.

It will not turn a bad test into a good one. What it will do is make sure the Playwright test suite structure around your tests is designed on purpose, so all the effort you pour into writing them does not get buried under a layout that cannot scale.

So try it on the suite you already dread. Point the playwright-pro skill at your messiest project, run the audit, and read the scorecard. Worst case, you learn exactly where the bodies are buried. Best case, you get the fast, sane, hundred-test suite you actually wanted.