{"canonical_url":"https://engineer.company/glossary/playwright/","content_markdown":"# Playwright\n\n## What it is\n\nPlaywright is an open-source framework from Microsoft for automating web browsers, with one\nprogramming interface for Chromium, Firefox and WebKit. Playwright Test, published on npm as\n`@playwright/test`, is the test runner built on top of it, and it is what most people mean when they\nuse the name. The same project ships the plain library for scripts that are not tests, a\ncommand-line tool and an MCP server aimed at AI agents, and an extension for Visual Studio Code, all\nunder the Apache License 2.0.\n\nBeyond JavaScript and TypeScript, the same browser control is available from Python, where the\nproject recommends its pytest plugin, from Java, with any test framework such as JUnit, and from\n.NET, with base classes for MSTest, NUnit and xUnit.\n\n`npx playwright install` downloads its own builds of the three engines, and because each release\nmoves those versions forward, the command may need to be run again after an upgrade. It can also\ndrive Google Chrome and Microsoft Edge where they are already on the machine. Tests run headless\nby default, without a visible window. The installation guide's example runs tests in parallel\nacross all three engines through configured browser projects; without those projects, the\nrunner's default browser is Chromium. Each test gets a fresh browser context, the equivalent of a\nnew browser profile, so one test's cookies and storage do not carry into the next.\n\nA test reads like the steps a person would take:\n\n```js\nimport { test, expect } from \"@playwright/test\";\n\ntest(\"signing in opens the inbox\", async ({ page }) =\u003e {\n    await page.goto(\"https://example.com/sign-in\");\n    await page.getByLabel(\"Email\").fill(\"reader@example.com\");\n    await page.getByRole(\"button\", { name: \"Sign in\" }).click();\n    await expect(page.getByRole(\"heading\", { name: \"Inbox\" })).toBeVisible();\n});\n```\n\nTwo mechanisms carry most of the weight. Before an action, Playwright runs actionability checks and\nwaits until all of them pass. For a click, the locator must resolve to exactly one element, and that\nelement must be visible, stable, which means its bounding box stays the same for at least two\nanimation frames in a row, able to receive the click rather than sitting under another element, and\nenabled. If the checks do not pass within the timeout, the action ends in a `TimeoutError`.\nAssertions written as `await expect(locator)` behave the same way: they fetch the element again and\nagain until the condition holds or the assertion timeout, five seconds by default, runs out.\n\n## Why it matters\n\nThe decision Playwright serves is which behaviour has to be checked in a real browser, and how to\nmake those checks trustworthy enough that a red build is believed. Some faults exist only once the\npage is assembled: a dialog that covers the button it should reveal, a layout that hides a field at\none width, a script that works in one engine and throws in another. Tests that run pieces of code in\nisolation cannot see them.\n\nBrowser tests turn flaky when the test and the page race each other. The page fetches data, animates\nand re-renders, and a test that clicks the moment its line runs sometimes clicks too early. The\nusual remedy was a fixed pause, too short on a slow machine and wasted time on a fast one.\nAuto-waiting and retrying assertions replace the pause with the condition the test actually depends\non. The assertions guide puts it plainly: web pages show information asynchronously, and assertions\nthat check only once lead to flaky tests.\n\nThe second choice is how a test finds things. The locators guide recommends user-facing attributes\nfirst, and role locators above all, because `getByRole` with an accessible name is the closest a\ntest gets to “how users and assistive technology perceive the page”. That has a side effect worth\nhaving: a test that clicks the button named “Sign in” breaks if the button loses its name, which is\nthe same defect a screen reader user would meet. The guide also says role locators “do not replace\naccessibility audits and conformance tests”. Test ids are the fallback. The guide calls them the\nmost resilient option and also “not user facing”, so a suite that finds everything by id proves less\nabout what a visitor experiences. CSS and XPath selectors are not recommended, because the DOM\nchanges often.\n\nThe cost is time. Starting a browser and loading a page makes browser tests the slowest kind a\nproject has. When one breaks on a build server, the trace viewer is the way back in. The documented\nconfiguration example records a trace on a failed test's first retry, with retries set to two on\nCI and zero locally; the runner's built-in defaults are no tracing and no retries. The trace steps\nthrough each action with the page before and after it, the network requests and the console.\n\n## What it looks like in practice\n\nOne platform here keeps its business logic in the database, and the work was to\n[build a layered test suite across four layers](/portfolio/built-a-test-suite-across-go-sql-and-browser/).\nIts stated task was to check each layer's behaviour where that behaviour actually lives, “rather\nthan everything being checked from the outside through a browser.” The Go API carries 981 test\nfunctions. The database carries 494 behavioural test files, so a stored function is tested in the\ndatabase instead of through three layers of application above it. The frontend carries 543 Vitest\nand Playwright specs, including 48 end-to-end files and 30 browser specs; the page gives one count\nfor both tools. The whole suite runs as 10 jobs in a 612-line workflow, and the page is direct about\nthe price: the suite is slow, it taxes every change, and at this size it needs maintenance of its\nown.\n\nThis site drives its own browser checks with a different library, Puppeteer, and its\n[credits page](/credits/) shows the same trade-off. Those checks cover what a validator cannot, such\nas measured contrast, focus order, target size, viewport overflow and print pagination. The gate\nruns all of them but viewport overflow before every push; that one, like the pixel-for-pixel visual\nregression check, waits for a person to run it on demand.\n\n## Where it goes wrong\n\nMost Playwright trouble comes from tests that check less than their names claim.\n\n**A fixed pause stands in for a condition.** A test waits two seconds and then reads the page, or\nreads a value once and compares it with a generic assertion. On a busy build server two seconds is\nsometimes too short. Assert on what a visitor would see with a web-first assertion such as\n`toHaveText`, and let it retry.\n\n**Elements are found by their markup.** A selector through three nested `div` elements or a styling\nclass breaks on the next redesign while the page still works. Find the element by role and\naccessible name, or by label or text, and add a test id only where nothing a user perceives\nidentifies it.\n\n**A passing role locator is taken as an accessibility check.** `getByRole` proves that one element\nhas the role and name the test asked for. It says nothing about contrast, focus order or the rest of\nthe page. For that, run a rule engine such as axe from the test, as Playwright's own\n[guide](https://playwright.dev/docs/accessibility-testing) does through `@axe-core/playwright`; the\nscan covers the page “in its current state when you call it”, so open the menu or the dialog first.\n\n**A click is forced through.** The `force` option turns off the non-essential actionability checks;\nfor a click, Playwright stops checking that the target actually receives the event. A test that\nneeds it is often working around something a visitor would also meet, such as a banner over the\nbutton. Treat the original error as a finding, and either dismiss the banner the way a visitor would\nor fix the overlap.\n\n**A flaky test is retried until it passes.** With retries on, a test that fails on the first run and\npasses on a retry is marked flaky rather than failed. A test that is flaky week after week is either\nracing the page or catching a real intermittent fault, and the trace recorded on its first retry is\nwhere to start looking.\n\n**Everything is checked through the browser.** A rule about prices or permissions, tested by\nclicking through three screens, is slow and breaks for reasons unrelated to the rule. Test the rule\nwhere it lives, and keep browser tests for what only a browser can show: the journey, the layout and\nthe differences between engines.\n\n## Further reading\n\n- [Installation](https://playwright.dev/docs/intro) — installing Playwright Test, running the\n  example tests, the HTML report and UI Mode.\n- [Locators](https://playwright.dev/docs/locators) — the recommended order for finding elements,\n  from role and label to test ids.\n- [Auto-waiting](https://playwright.dev/docs/actionability) — the actionability checks behind each\n  action and what `force` turns off.\n- [Assertions](https://playwright.dev/docs/test-assertions) — retrying and non-retrying assertions,\n  the default timeout, soft assertions and polling.\n- [Trace viewer](https://playwright.dev/docs/trace-viewer-intro) — recording a trace on retry and\n  stepping through a failed test action by action.\n- [Browsers](https://playwright.dev/docs/browsers) — installing the engines, running branded Chrome\n  and Edge, and the two headless modes.\n\n\u003chttps://engineer.company/glossary/playwright/\u003e\n","date_modified":"2026-11-09T21:50:25Z","description":"What Playwright Test waits for before each click, why it finds elements by role and name, and what a suite run in real browsers costs to keep.","formats":{"gemtext":"https://engineer.company/glossary/playwright/index.gmi","gopher":"https://engineer.company/glossary/playwright/gophermap","html":"https://engineer.company/glossary/playwright/","json":"https://engineer.company/glossary/playwright/index.json","markdown":"https://engineer.company/glossary/playwright/index.md","pdf":"https://engineer.company/glossary/playwright/index.pdf"},"kind":"page","language":"en","title":"What is Playwright?","url":"https://engineer.company/glossary/playwright/","version":1}