Home / Blog / Onboarding a team onto Playwright

How to get a team writing Playwright tests: what to settle, and what to leave alone

Updated 1 September 2026 · Playwright 1.62

Nothing about the framework changes when a team goes from one engineer to four. The repository changes completely. One engineer decides where a spec lives by putting it somewhere; four engineers decide it four times, in four pull requests opened on the same afternoon, and none of them is wrong.

The decisions themselves are already written down elsewhere. Where the suite sits, what a locator may be, what a test may assume about the data and what runs per pull request all get settled while building a first suite by hand, and the catalogue of what good looks like is the practice list, linked further down. This page answers the question neither of those has to: how four people settle each of those decisions once, and how the answer outlives the person who made it.

What does a team have to agree before anyone writes the first spec?

The technical decisions have answers one engineer can reach alone, and the tutorial reaches them. The four settlements below arrive only because there is more than one person in the room.

• Who decides. One named person owns the conventions, and it costs something: for a fortnight they are a bottleneck, because every pull request with a new shape in it waits on one opinion. The alternative is a vote per pull request, which re-opens the same question every time it comes up and closes it differently depending on who is reviewing that day.
• Where the decision is written down. The fourth engineer joins in week three and was at none of the conversations. A README beside the specs, a CONTRIBUTING file, a block comment at the top of the config — the location matters less than whether every person on the team can name it without asking. A convention nobody can locate ends at the first new starter.
• Which conventions a machine will hold. Some can be facts about the repository by Friday. The rest stay in code review, costing somebody's attention every week for as long as the suite exists, so sort them into the two piles early.
• What a spec has to be before it is merged. One sentence, agreed once. The content of that sentence belongs to your application. Agreeing it before the first review is cheaper than discovering it during the fortieth.

None of those is a rule about testing; they are decisions about who and where. Skipping them costs nothing at first, which is why they get skipped.

What do the first two weeks look like when four engineers start at once?

Four engineers green-fielding in parallel produce four answers to questions nobody asked them. Four locator styles, two helper folders with a third set of helpers living inside the spec files, and two views on whether a spec may log in through the interface. By day ten there are specs in the repository and no shape to them, and the merge that would give them one is a rewrite. It is the sort nobody budgets for, because nothing is broken and every test passes.

The alternative costs something visible in week one: three of the four are not writing tests. One person builds the walking skeleton, which is the config, the way the suite logs in, one spec that goes end to end, and the check that runs it on every pull request. The other three read it, review it and argue with it. When they start writing, they start against a repository that already has a shape.

A lead who has just been given four people will feel that week, and it is the cheapest week in the quarter to spend. Neither arrangement has a number attached to it here: nobody has counted how many specs a team writes either way, so the paragraph above is an argument from cost rather than a finding.

Which parts of Playwright can a team safely ignore in month one?

The official best practices page runs twenty-seven headings below its title, from testing philosophy through locators, codegen, the VS Code extension, debugging, all browsers, dependency currency, CI, linting, parallelism and sharding, to soft assertions. None of them is marked optional and there is no order in them, which is what a manual has to do: it does not know which reader it has, so everything arrives at the same weight. A team that adopts all of it in month one adopts none of it.

Each deferral below has a cost it avoids and a trigger that ends it. A deferral with no trigger is neglect.

• Sharding. It solves a wall-clock problem the team does not have yet. The documentation on it describes splitting tests across several machines and then merging the reports back together, with a merge-reports command line tool of its own: three moving parts to own before there is a suite worth distributing across anything. Trigger: the CI run takes longer than people are willing to wait before merging. Splitting a suite across machines covers the mechanics for the day that arrives.
• Visual comparison. The documentation puts a warning next to its first screenshot example: "Browser rendering can vary based on the host OS, version, settings, hardware, power source (battery vs. power adapter), headless mode, and other factors. For consistent screenshots, run tests in the same environment where the baseline screenshots were generated." A team that turns this on in week one has bought a second source of flakiness before it can read the first. Trigger: a regression that is visual and nothing else, such as a design system, a chart or a print layout. Screenshot comparison is where the environment problem gets solved.
• Component testing. Immaturity is not the reason. Version 1.62 shipped a new component testing model, the experimental packages are gone, and the documentation describes the replacement as stable: tests import test and expect from plain @playwright/test, with no separate config dialect. Defer it because it answers a different question, sitting next to the components and usually with a different owner, and this team was assembled to answer the end-to-end question first. Trigger: the front-end team wants it and will own it. The 1.62 model walks through the story gallery and the mount fixture.
• A page object layer. Specs that read top to bottom are easier to review while the team is still agreeing what a spec looks like. Trigger: the same three lines have been copied into a fourth spec. The page object argument holds both positions.
• Running every browser on every run. The documentation recommends testing across all browsers, and says why: it is how you find out the application works for all your users. The order here differs from that recommendation. Three projects in the config means every spec runs three times and every flake has three places to come from, before there is one browser the team trusts. Trigger: the first month in which the one browser stays green.

Whatever that project list eventually says, it is a list of browsers. Playwright's device emulation gives a spec a phone-sized viewport, a phone's user agent and touch input, which is mobile web. The iOS or Android build your users downloaded from a store is not something this suite reaches, and no entry in the config changes that.

Two things do not get deferred, because every later week is cheaper for having them. Turn the trace on for the first retry, so a failure can be read instead of re-run; a team without traces learns to press the retry button, and that habit is much harder to remove than to prevent. And put the type check and the lint gate in while there are five specs to fix rather than forty.

Which conventions can a machine enforce, and which need a person?

A convention a person has to remember is a convention that survives until that person is on holiday. So the first question to ask about anything the team agrees is whether a machine can hold it, and some of the ones that matter most cost a line of configuration.

The test id attribute is the clearest case. Four engineers will otherwise answer "what do we hang test hooks off" four ways, in four pull requests, all defensible. Naming it once turns it into a fact about the repository. Everything below was written and run against Playwright 1.62.1, the current release of the 1.62 line.

// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    testIdAttribute: 'data-qa',
  },
});

Playwright 1.62.1 · TypeScript · playwright.config.ts

That option replaces the default rather than adding to it. With the config above, page.getByTestId('save') resolves <button data-qa="save">, and an element carrying data-testid stops resolving at all; both halves were run here as two tests and both passed. Which attribute to put in that string is a question about locators, and it has more than one defensible answer.

The second machine-held convention is the gate on every pull request, and the documentation is specific about what goes in it. Under Lint your tests, the best practices page says: "We recommend TypeScript and linting with ESLint for your tests to catch errors early. Use @typescript-eslint/no-floating-promises ESLint rule to make sure there are no missing awaits before the asynchronous calls to the Playwright API. On your CI you can run tsc --noEmit to ensure that functions are called with the right signature."

package.json

{
  "name": "e2e",
  "private": true,
  "scripts": {
    "test": "playwright test",
    "typecheck": "tsc --noEmit"
  },
  "devDependencies": {
    "@playwright/test": "1.62.1",
    "typescript": "5.9.3"
  }
}

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "commonjs",
    "moduleResolution": "node",
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true
  },
  "include": ["tests", "playwright.config.ts"]
}

Playwright 1.62.1 · TypeScript 5.9.3 · both scripts run

The gate is now a thing in the repository instead of a paragraph in an onboarding document. npm run typecheck runs the compiler over the tests and the config without emitting anything, which is the check the documentation names for CI.

The two checks catch different defects and neither covers for the other, which is why the documentation names both. Run against the samples above, tsc --noEmit caught a misspelled assertion option: toBeVisible({ timeuot: 1000 }) came back as error TS2561: Object literal may only specify known properties, but 'timeuot' does not exist. It said nothing at all about an assertion written with no await in front of it, and the missing await is the ESLint rule's job.

What is left over needs a person, and it is a short list: whether the test should exist at all, and whether it is testing your product or testing Playwright. Once the machine holds the rest, that is the only thing review time is being spent on. The practice list is what a reviewer holds a spec against.

Who owns the suite when everyone owns it?

"The whole team owns the suite" is how a suite ends up owned by nobody, because a red build belonging to everyone is nobody's morning. Ownership here is two named jobs, and neither of them is "write all the tests".

• Someone owns the conventions. Their job is to answer whether a convention is still right, and to change it when it is not. A convention with no owner cannot be changed, only ignored, and a team that has started ignoring one has started ignoring the file it lives in.
• Someone is on the hook for a red build today. A rotation, published, with one rule attached: the build gets read before it gets re-run. The person on rota does not have to fix it. They have to find out what it was and say so where the team can see it.

Where both jobs stay implicit, the suite belongs to whoever wrote most of it. That is a person, and a person has a notice period.

How do you tell whether it worked?

These are observations rather than measurements. None of them carries a number, a percentage or a timeframe, because nobody here has measured one, and a lead can check every one of them by reading the repository for ten minutes.

• A red build gets read before anyone re-runs it. Somebody opened the trace. The tell in the other direction is a second CI run started within a minute of the first one failing, which is a team that has decided failures are weather. Working out which tests are flaky and why is the next job once that habit has set in.
• A test gets written without anyone asking how. The question stopped arriving in the lead's messages, and nobody announced that it had.
• A convention gets followed by someone who was not in the room when it was set. It is the only signal here that shows the convention outlived the conversation that produced it.
• A test gets deleted, on purpose, with a reason. A suite nobody prunes is a suite nobody owns.
• A review comment is about the product. While the comments are about the framework, the team is still learning the tool. Once they are about whether the assertion describes something a customer cares about, the tool has stopped being the subject.

When this bites you: the quarter the suite goes quiet

Nothing breaks. The suite is green every morning and no meeting is called about it. It has also not grown in five weeks, and the last four commits come from the same person.

None of what happened underneath was reported. Features shipped without tests and nobody blocked them, because blocking one was never anybody's job. The newest engineer could not find the conventions, invented their own, and nobody minded. Nobody read a red build any more; it just got retried.

Every one of those traces back to a decision that was made in a conversation and never written anywhere a new person would look, which is what makes the first move small. Read the last ten merged pull requests and count how many touched the suite. If the answer is one or two, then writing tests is not part of the job as anyone on the team currently understands it, and no amount of framework knowledge changes that.

Reading those ten pull requests sometimes turns a process problem into a staffing one: the conventions are fine, and nobody has the hours to hold them. That is the point at which teams hire an engineer who already works in Playwright every day to hold them from inside the repository.

Questions