Protractor to Playwright migration for a suite you inherited

Who this is for

An Angular application old enough to have an end-to-end suite in Protractor, and a team that did not write it. Nobody starts a Protractor suite now, so the specs predate most of the people looking at them.

Test quality almost never forces the decision. One of these does:

• An Angular upgrade that has stopped, with the e2e toolchain named in the blocking ticket.
• A CI image or a Node version the suite has never been tested against. Protractor 7.0.0 declares node >=10.13.x in its engines field, and dist-tags.latest still resolves to 7.0.0.
• Nobody left wants the suite, and nobody you interview has used the framework.

There is no language decision here: a Protractor suite is already TypeScript or JavaScript and stays that way. We work in Playwright's other three official bindings too, Python, Java and .NET.

If you could read the whole suite in an afternoon, open the free guide below and do it yourselves. If the repository also holds a half-built replacement in something else, start at migrating from any other framework.

What the official guide gives you free

Playwright publishes a Protractor migration guide. Open it before this page and before you talk to anyone: a ten-row cheat sheet mapping element(by.*) onto page.locator(), one before-and-after example converted line by line, and two polyfills for waitForAngular. There is no equivalent guide for Selenium or Cypress. If your suite is small and its specs are straightforward, that page is your migration and you are done here.

A translation table decides the easy half. It leaves these open:

• Whether a test is worth converting. The table assumes you want every test you have, which on a suite whose authors have left is the expensive assumption.
• What the new suite's locators look like. Every row lands on page.locator() with a CSS or XPath string, which is how four hundred tests arrive in Playwright addressed the Protractor way.
• Where the suite was already fighting Protractor's synchronisation. The call sites where somebody switched Angular waiting off are the map of what flakes after conversion, and no cheat sheet has a row for it.
• Everything that is not a spec: protractor.conf.js, the onPrepare hook your login lives in, the CI job, and the protractor dependency itself.

How it works

1. Inventory

   The inventory reads for things the other two migration pages do not have to look for. What each spec was meant to prove, reconstructed from the code, the spec names and the commit messages, as a sentence per test — including the tests where the sentence is that nobody can say. Every call site where the suite turned Angular waiting off: waitForAngularEnabled(false) and, on older suites, browser.ignoreSynchronization, deprecated in Protractor's changelog at 6.0.0 in favour of the first. And whether the suite still executes. You give us the repository, the pipeline, and time with whoever remembers why it looks like this.

2. A pilot slice

   One flow, converted the whole way through and green in your pipeline before the rest is touched. If the suite has not had a green run in a year this phase gets bigger: it has to establish what the application does as well as what the spec claims it did. You give us the flow that matters most, and somewhere we can run it.

3. Bulk conversion

   Everything else, in batches small enough to read, in the vocabulary the pilot settled, each reviewed and merged before the next begins. You give us a reviewer who knows what the product is supposed to do.

4. Cutover

   For a while both suites run on every commit. Once the Playwright job has been green everywhere the Protractor job was, the Protractor job comes out of the pipeline and the toolchain out of the repository. You give us the decision that the overlap has run long enough.

The two cheat-sheet rows that only mean anything on AngularJS

Check those two rows before you plan anything. element(by.model('...')) becomes page.locator('[ng-model="..."]'), and element(by.repeater('...')) becomes page.locator('[ng-repeat="..."]'). Both are exact, and the right-hand side of each is an attribute selector, so it finds something only if that attribute is in your rendered HTML. Open dev tools and search for ng-model: ten seconds, and it tells you more about the shape of this job than the spec count does.

Protractor's README says why: the project works with AngularJS and is compatible with Angular applications, but "for Angular apps, the binding and model locators are not supported", and it recommends by.css instead. So a suite full of by.model was written against AngularJS, while one written for Angular 2 and later is already full of CSS strings — two different jobs, and the second carries a trap the first does not, because a CSS string that still resolves can point at a component somebody rebuilt underneath it. The cheat sheet is ten rows and by.binding is not one of them, so that translation is yours.

Either way, every row lands on page.locator() with a string, which is what a like-for-like table is for and also the one moment you get to choose differently. Playwright's locators documentation names getByRole, getByText, getByLabel, getByPlaceholder, getByAltText, getByTitle and getByTestId as the recommended built-in locators, and the best practices page gives the reason under its own heading, "Prefer user-facing attributes to XPath or CSS selectors". The same converted test, twice:

import { test, expect } from '@playwright/test';

test('adds a todo through the AngularJS attribute', async ({ page }) => {
  await page.goto('/todos/');
  await page.locator('[ng-model="todoList.todoText"]').fill('first test');
  await page.getByRole('button', { name: 'Add' }).click();

  await expect(page.getByRole('listitem')).toHaveText(['first test']);
});

test('adds a todo through a locator that outlives the attribute', async ({ page }) => {
  await page.goto('/todos/');
  await page.getByLabel('New todo').fill('first test');
  await page.getByRole('button', { name: 'Add' }).click();

  await expect(page.getByRole('listitem')).toHaveText(['first test']);
});

The second survives somebody deleting ng-model, and which of the two your suite ends up in gets decided once, in the pilot. Choosing locators for a suite you are going to keep runs that argument at length.

Where this stops

An application this old usually contains something the engagement does not cover. Those specs get named during the inventory, and they are not in the quote.

Security and penetration testing are not offered here either, in any framework.

Read first

• Which locator to reach for first. The decision the cheat-sheet section leaves you holding, argued properly.
• Auto-waiting, and the timeouts around it. What replaces waitForAngular, at length.
• What sits between the runner and the browser. Where the difference in the waiting model comes from.