Playwright Framework Architecture: Designing for Scale
Architecture thinking matters more than tool knowledge. The biggest mistakes in test frameworks come from poor design decisions, not from misusing APIs.
“Generates standard Playwright files you can inspect, modify, and run in any CI pipeline.”
Open-source test automation
1. Architecture Over API Knowledge
Teams that know every Playwright API but design their framework poorly end up with suites that take two hours to run. The architectural mistake that causes the most damage is treating every test as an independent browser session with full setup and teardown when most tests could share state safely.
The right framework architecture separates tests into tiers based on their isolation needs. Tests that modify data need full isolation. Tests that only read data can share a browser context, cutting startup overhead by 60% or more. This tiering decision affects every other framework choice including parallelization strategy, data management, and failure handling.
2. Sharing Browser State Safely
Playwright's browser context model makes it possible to share authentication state across tests without repeating login flows. The storageState feature captures cookies and local storage from one context and injects them into others. When done correctly, this eliminates the single biggest time sink in most test suites: redundant authentication.
The risk is test pollution. If one test modifies shared state (changing user preferences, creating data), subsequent tests may behave differently depending on execution order. The safeguard is to use shared state only for read-only operations and create fresh contexts for any test that writes data. This pattern scales to hundreds of tests without the ordering problems that plague naive sharing approaches.
Generate well-architected tests
Assrt produces Playwright tests with proper isolation and selector strategies. Open-source, no lock-in.
Get Started →3. Full Page State Logging at Failure
A screenshot at failure time tells you what the page looked like. The actual DOM structure tells you why the page looked that way. Network request logs tell you what data the page received. Together, these three pieces of context let you diagnose most failures without reproducing them locally.
Teams that log all three report that 90% of their flaky tests turn out to be timing issues with API responses. The test expected data to be present, but the API response arrived after the assertion timeout. Without the network log, this looks like a random failure. With it, the fix is obvious: wait for the specific network response before asserting.
4. The 90% Timing Insight
Most flaky test investigations end with the same root cause: the test made a timing assumption that only holds under ideal conditions. Locally, the API responds in 50ms and the test passes every time. In CI, shared resources and network variability push response times to 500ms, and the test fails intermittently.
The architectural fix is to build wait-for-response patterns into your base test utilities. Instead of asserting immediately after a user action, the framework waits for the relevant API call to complete before checking the UI state. This pattern eliminates an entire category of flaky tests and requires almost no per-test effort once the base utilities are in place.
5. Test Data Management at Scale
Test data management is where frameworks start to crack at scale, especially with cross-browser execution where each browser needs its own clean state. The most robust approach uses API calls to create test data before each test and clean it up afterward, bypassing the UI entirely for data setup.
This separation between data setup (API) and behavior testing (UI) makes tests faster, more reliable, and easier to parallelize. Each test creates exactly the data it needs, runs its UI assertions, and cleans up without affecting other tests running in parallel on different browser instances.
Ready to automate your testing?
Assrt discovers test scenarios, writes Playwright tests, and self-heals when your UI changes.