A Scalable Playwright Framework That Survives 500 Tests

Clean, repeating steel structural framework of a modern building, a metaphor for a scalable Playwright and TypeScript test automation framework.
In this post
  1. TL;DR
  2. Why do most scalable Playwright frameworks rot?
  3. The folder structure that scales
  4. Fixtures over base classes
  5. Config and environments without copy-paste
  6. Parallelism, retries, and CI wiring
  7. Page objects vs fixtures: the maintainability call
  8. Where Nopmark fits
  9. FAQ

A scalable Playwright framework is easy to start and hard to keep clean. You can stand up the project in ten minutes. Keeping it maintainable at 500 tests is the hard part, and it is the part the quickstart guides skip.

The structure is the test strategy. Get the architecture right early and the suite stays fast and readable as it grows. Get it wrong and every new hire quietly rewrites it. This is the opinionated, batteries-included layout I would hand a team starting fresh in TypeScript.

TL;DR

  • A flat tests/ folder and one god-fixture file are the two most common reasons frameworks rot.
  • Organize by feature, not by page or by test type.
  • Put shared setup in composable fixtures, not in a base class everyone extends.
  • Layer config by environment so nothing is copy-pasted.
  • Wire parallelism, retries, and tracing before you have 100 tests, not after they hurt.

Why do most scalable Playwright frameworks rot?

Three failure modes show up again and again.

The flat folder. Everything lands in tests/. At 30 specs it is fine. At 300 you cannot find anything, related tests are scattered, and nobody knows what is already covered. Coverage gaps hide in the noise.

The god-fixture. One fixtures.ts that exports everything: auth, test data, API clients, page objects, all tangled together. Every test imports the whole thing. Changing one fixture risks breaking unrelated suites, and nobody dares refactor it.

Copy-pasted config. Base URL, timeouts, and credentials pasted into each spec or duplicated across half-configured environment files. The day you change the staging URL, you change it in eleven places and miss two.

Each of these is cheap to avoid at the start and expensive to fix later. So fix them at the start.

The folder structure that scales

Organize by feature, the way your product is actually divided, not by Playwright artifact type.

project-root/ tests/ auth/ login.spec.ts password-reset.spec.ts checkout/ cart.spec.ts payment.spec.ts account/ profile.spec.ts fixtures/ auth.fixture.ts api.fixture.ts test-data.fixture.ts pages/ LoginPage.ts CheckoutPage.ts utils/ api-client.ts data-factory.ts config/ playwright.config.ts environments.ts playwright.config.ts

The principle: when someone needs to work on checkout, everything for checkout is in one place. Specs grouped by feature, page objects named for what they represent, fixtures and utilities separated so they compose rather than tangle. A new engineer can open tests/checkout/ and understand the coverage in a minute.

Fixtures over base classes

Playwright fixtures are what make a scalable Playwright framework possible, and they are the one people from a Selenium background tend to underuse.

Instead of a BaseTest class that every spec extends and that slowly accumulates every helper anyone ever needed, write small fixtures that provide exactly one thing and compose them per test.

// fixtures/auth.fixture.ts import { test as base } from '@playwright/test'; import { LoginPage } from '../pages/LoginPage';

type AuthFixtures = { loginPage: LoginPage; authenticatedPage: void; };

export const test = base.extend<AuthFixtures>({ loginPage: async ({ page }, use) => { await use(new LoginPage(page)); }, authenticatedPage: async ({ page, loginPage }, use) => { await loginPage.goto(); await loginPage.loginAs('standard_user'); await use(); }, });

Now a test asks only for what it needs. A test that needs a logged-in session requests authenticatedPage and gets it. A test that does not, does not pay for it. This is the difference between setup that stays clean and setup that becomes a dumping ground.

Use auth state, not repeated logins. For suites where most tests need a session, log in once in global setup, save the storage state, and reuse it. Logging in through the UI in every test is the single biggest waste of runtime in most suites.

Config and environments without copy-paste

Keep one config and resolve environment values from a single source.

// config/environments.ts const environments = { local: { baseURL: 'http://localhost:3000' }, staging: { baseURL: 'https://staging.example.com' }, prod: { baseURL: 'https://example.com' }, };

const env = process.env.TEST_ENV || 'local'; export const config = environments[env];

Your playwright.config.ts reads from that. Switching environments becomes TEST_ENV=staging, not a find-and-replace across the repo. Secrets come from environment variables or your CI vault, never committed.

In the Playwright config itself, set the defaults that prevent flakiness before it starts: web-first assertions with sensible timeouts, no hard waits, trace on first retry.

export default defineConfig({ use: { baseURL: config.baseURL, trace: 'on-first-retry', screenshot: 'only-on-failure', }, retries: process.env.CI ? 2 : 0, workers: process.env.CI ? 4 : undefined, });

Parallelism, retries, and CI wiring

Decide these early, because retrofitting them is painful.

  • Parallelism: Playwright runs files in parallel by default. Keep tests independent so they can. A test that depends on another test's leftover state will fail unpredictably under parallel execution. Independence is not optional at scale, it is the price of speed.
  • Retries: Set retries to 2 in CI and 0 locally. Local retries hide flakiness you want to see while developing. CI retries absorb genuine infrastructure noise. Pair retries with trace: 'on-first-retry' so a flake leaves you a full trace to diagnose.
  • Sharding in CI: When the suite gets large, split it across machines with Playwright's built-in sharding. Wire it into your pipeline once and forget it.
  • Reporting: Use the HTML reporter plus a CI-friendly reporter (line or a JUnit output your CI can parse). A failure should leave behind a trace, a screenshot, and a readable report, not just a red X.

Page objects vs fixtures: the maintainability call

You do not have to choose. Use both for what each is good at.

  • Page objects model the structure of a screen: selectors and the actions you take on that screen. They keep selectors in one place so a UI change is a one-file fix.
  • Fixtures handle setup, state, and dependency injection: getting you to the right starting point with the right data.

The common mistake is stuffing setup logic into page objects, or putting selectors into fixtures. Keep the line clean. Page objects know about the page. Fixtures know about the test's preconditions. When both stay in their lane, the framework reads well years later.

Where Nopmark fits

A framework is only as strong as the test design behind it. Clean structure does not save you if the tests assert the wrong things or miss the scenarios that matter. The foundations of good test design, equivalence partitioning, boundary analysis, risk-based prioritization, are what make an automation suite worth maintaining. Nopmark's ISTQB CTFL certification covers those foundations with accredited instructors, so the tests you automate are the right tests, not just well-organized ones.

FAQ

Should I organize Playwright tests by page or by feature? By feature. Page-based folders scatter related tests and make coverage hard to read. Feature folders mirror how your product and your team are actually divided, so everything for one area lives together.

Do I still need the Page Object Model with Playwright? Yes, for selector and action reuse, but pair it with fixtures rather than a giant base class. Page objects model screens. Fixtures handle setup and state. Keep them separate.

How do I stop my Playwright suite from getting slow? Reuse authentication via saved storage state instead of logging in per test, keep tests independent so they parallelize, and shard across machines in CI when the suite grows. Most slowness comes from repeated UI logins.

How many retries should I configure? Two in CI, zero locally. Local retries hide flakiness you want to catch while writing tests. CI retries absorb infrastructure noise. Always enable trace on first retry so you can diagnose what flaked.

Is this structure overkill for a small suite? The folders and config layering cost almost nothing to set up early and save real pain later. Start with the structure even at 20 tests. Retrofitting it at 300 is the expensive path.

Ready to make sure the tests you automate are the right ones? Nopmark's ISTQB CTFL certification covers the test design foundations behind every good framework, taught by accredited instructors with hands-on practice. See Nopmark's certification programs.

Keep reading