ZeeaanNawazHarall/playwright-best-practices

I like this repo’s shape: it is not just a “tips” README, it has a real reference structure behind it. The strongest part is the way the maintainer separates official Playwright guidance from architectural opinions. The framework architecture doc is especially useful because it does not blindly push Page Object Model everywhere; it explains script-based tests, simple POM, and split locator/action POM as a scale-dependent spectrum, then points readers to runnable SauceDemo examples. That makes the repo more practical than many testing-template projects.

The runnable examples are a real differentiator. examples/pom-framework includes its own playwright.config.ts, lockfile, fixtures, page objects, tests, Allure reporting, HTML/JSON reports, storageState auth reuse, and a GitHub Actions matrix that runs the POM, simple POM, and script frameworks. The anti-pattern section is also strong because it shows before/after snippets for common mistakes like XPath over semantic locators, waitForTimeout, waitForSelector, and .isVisible() snapshot assertions. That kind of concrete correction is exactly what helps teams improve a flaky suite.

A few things would make it easier to adopt. The root README says the repo is MIT licensed, but examples/pom-framework/package.json still says ISC; aligning the package metadata with the root license would avoid confusion for people copying an example. Some tests, such as the cart scenario, use test.describe.serial and carry cart state across multiple test cases. That may be intentional as a scenario walkthrough, but it slightly conflicts with the repo’s own “isolate tests from each other” principle, so I would either combine that flow into one end-to-end test or add a note explaining why serial state is being demonstrated there. I’d also consider making the CI status easier to interpret by documenting that only Chromium is enabled by default while Firefox/WebKit are scaffolded but commented out.

Overall, this is a polished early-stage reference project with unusually good documentation discipline. It already has the important community files, a changelog, contribution guidance, CI, and runnable examples. The main missing piece is adoption signal: as of inspection it has no stars or forks yet, so its credibility will need to come from continued maintenance, issue responses, and keeping examples current with Playwright releases.