I Built 3 Playwright Frameworks So You Can Learn What Actually Scales

Zeeaan Haral — Tue, 02 Jun 2026 11:14:20 +0000

From Script‑Based to Enterprise Playwright: Frameworks That Actually Scale

When I started learning Playwright, every article told me the same things:

“Use Page Object Model”
“Create fixtures”
“Don’t use waitForTimeout”

Nobody showed me:

What a real project should look like
How folders should be organized
When POM becomes too big
How teams handle authentication cleanly
Why tests become flaky (and how to actually fix them)

So I learned by making mistakes.

Lots of mistakes.

After months of trial and error – and building automation frameworks from scratch at my job – I decided to document everything that worked. Not as a collection of tips, but as complete, runnable frameworks.

That’s why I built playwright-best-practices.

What makes this different from most Playwright repositories

Most GitHub repos show you one “perfect” architecture. You clone it, run it, and… you don’t know why it’s built that way.

This repo shows you the evolution:

Script‑based (no patterns)
↓
Simple Page Object Model
↓
Advanced POM (layered architecture)

You can compare each approach side‑by‑side and understand when complexity becomes worthwhile.

What’s inside (no fluff, no guessing)

Three runnable frameworks (clone and `npm test`)

Framework	What it teaches	Best for
`01-script-based`	Raw, inline interactions – the “I just need it to run” baseline	Understanding the pain that patterns solve
`02-simple-pom`	Classic Page Object Model – locators + actions in one class	Most teams (80% of use cases)
`03-advanced-pom`	Separate layers: locators, actions, assertions	Large suites where simple POM becomes a 1000‑line monster

One documentation folder (anti‑patterns)

Folder	What it is
`04-anti-pattern-lab`	Not runnable – a written guide of common mistakes

Why no runnable anti‑pattern code? Because broken examples can be confusing if they don’t fail clearly. Instead, I documented them – so you can recognize the smell before it infects your suite.

Additional production‑ready goodies

Worker‑scoped login fixture – one login for the whole suite
Environment‑based credentials – clean .env example
GitHub Actions + Jenkins CI configs – ready to drop into your project
Flaky test strategies – not just retries, but structural fixes

Advanced POM explained (because it’s often misunderstood)

When I say “Advanced POM”, I don’t mean bigger. I mean separated responsibilities:

Layer	Responsibility	Example
Locators	Store element selectors only	`loginPage.emailInput`
Actions	Perform business interactions	`loginPage.loginWithCredentials()`

This prevents your Page Objects from turning into 1000‑line files as your project grows. It also makes tests dramatically easier to refactor – change a selector in one place, and everything updates.

Lessons I learned building Playwright frameworks (the hard way)

Mistake #1: Putting assertions inside Page Objects

Why it failed:

Page Objects became tied to specific test flows. Reusability dropped. Changing a button’s text broke unrelated tests.

What I do now:

Keep assertions in dedicated assertion classes or test files. Page Objects should only expose state and actions.

Mistake #2: Logging in before every test

Why it failed:

Test suite took 3x longer. Rate‑limiting kicked in. Flakiness spiked.

What I do now:

Worker‑scoped login fixtures – one authentication per worker, shared across tests.

Mistake #3: Using `waitForTimeout(5000)` as a lazy fix

Why it failed:

Tests became slow and still flaky – just slower flaky.

What I do now:

waitForSelector, waitForResponse, or auto‑waiting assertions. The repo has concrete examples.

Who should use this repository

Role	Why it’s valuable
Junior SDET	Skip the painful trial‑and‑error phase – see what a real project looks like
Cypress → Playwright mover	Understand Playwright’s different approach (fixtures, worker scope, trace viewer)
Team lead	Hand this to juniors as a reference architecture
Anyone fighting flaky tests	The anti‑pattern lab + flaky test strategies will save your weekends

How to use the repo (the way I intended)

Clone it

git clone https://github.com/ZeeaanNawazHarall/playwright-best-practices
Run the script‑based framework – feel the mess

cd examples/script-framework && npm install && npx playwright test
Run the simple POM – see how much cleaner it gets
Run the advanced POM – understand how teams scale
Read the anti‑pattern lab – recognize mistakes you might be making right now

You’ll leave with a mental map of why each pattern exists – not just copy‑pasted code.

A final honest note

I’m not claiming this is the only way. But these patterns come from real work at my job (AccuraSol). They saved my weekends, made my scripts stable, and helped me sleep better.

I open‑sourced it because I remember being overwhelmed when I started. If this repo saves you one late night of debugging a flaky test, it’s done its job.

Repository link & call to action

If you’re learning Playwright or mentoring junior automation engineers, check it out:

👉 github.com/ZeeaanNawazHarall/playwright-best-practices

Feedback, issues, and pull requests are welcome.

Found a better pattern? Open a PR. Found a mistake? Tell me. Let’s make this the actual best‑practices repo, no gatekeeping.

— Zeeaan

SDET @ AccuraSol

DEV Community: Zeeaan Haral