Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.
You can extend Playwright assertions by providing custom matchers. These matchers will be available on the expect object.
import { expect as baseExpect } from '@playwright/test';
export const expect = baseExpect.extend({
async toHaveAmount(locator: Locator, expected: number, options?: { timeout?: number }) {
// ... see documentation for how to write matchers.
},
});
test('pass', async ({ page }) => {
await expect(page.getByTestId('cart')).toHaveAmount(5);
});
See the documentation for a full example.
You can now merge test fixtures from multiple files or modules:
import { mergeTests } from '@playwright/test';
import { test as dbTest } from 'database-test-utils';
import { test as a11yTest } from 'a11y-test-utils';
export const test = mergeTests(dbTest, a11yTest);
import { test } from './fixtures';
test('passes', async ({ database, page, a11y }) => {
// use database and a11y fixtures.
});
You can now merge custom expect matchers from multiple files or modules:
import { mergeTests, mergeExpects } from '@playwright/test';
import { test as dbTest, expect as dbExpect } from 'database-test-utils';
import { test as a11yTest, expect as a11yExpect } from 'a11y-test-utils';
export const test = mergeTests(dbTest, a11yTest);
export const expect = mergeExpects(dbExpect, a11yExpect);
import { test, expect } from './fixtures';
test('passes', async ({ page, database }) => {
await expect(database).toHaveDatabaseUser('admin');
await expect(page).toPassA11yAudit();
});
You can mark a test.step()
as "boxed" so that errors inside it point to the step call site.
async function login(page) {
await test.step('login', async () => {
// ...
}, { box: true }); // Note the "box" option here.
}
Error: Timed out 5000ms waiting for expect(locator).toBeVisible()
... error details omitted ...
14 | await page.goto('https://github.com/login');
> 15 | await login(page);
| ^
16 | });
See test.step()
documentation for a full example.
This version was also tested against the following stable channels:
https://github.com/microsoft/playwright/issues/27071 - expect(value).toMatchSnapshot() deprecation announcement on V1.38 https://github.com/microsoft/playwright/issues/27072 - [BUG] PWT trace viewer fails to load trace and throws TypeError https://github.com/microsoft/playwright/issues/27073 - [BUG] RangeError: Invalid time value https://github.com/microsoft/playwright/issues/27087 - [REGRESSION]: npx playwright test --list prints all tests twice https://github.com/microsoft/playwright/issues/27113 - [REGRESSION]: No longer able to extend PlaywrightTest.Matchers type for locators and pages https://github.com/microsoft/playwright/issues/27144 - [BUG]can not display trace https://github.com/microsoft/playwright/issues/27163 - [REGRESSION] Single Quote Wrongly Escaped by Locator When Using Unicode Flag https://github.com/microsoft/playwright/issues/27181 - [BUG] evaluate serializing fails at 1.38
This version was also tested against the following stable channels:
browserContext.on('weberror')
locator.pressSequentially()
reporter.onEnd()
now reports startTime
and total run duration
.page.type()
, frame.type()
, locator.type()
and elementHandle.type()
.
Please use locator.fill()
instead which is much faster. Use locator.pressSequentially()
only if there is a
special keyboard handling on the page, and you need to press keys one-by-one.[!NOTE] If you are using
@playwright/test
package, this change does not affect you.
Playwright recommends to use @playwright/test
package and download browsers via npx playwright install
command. If you are following this recommendation, nothing has changed for you.
However, up to v1.38, installing the playwright
package instead of @playwright/test
did automatically download browsers. This is no longer the case, and we recommend to explicitly download browsers via npx playwright install
command.
v1.37 and earlier
playwright
package was downloading browsers during npm install
, while @playwright/test
was not.
v1.38 and later
playwright
and @playwright/test
packages do not download browsers during npm install
.
Recommended migration
Run npx playwright install
to download browsers after npm install
. For example, in your CI configuration:
- run: npm ci
- run: npx playwright install --with-deps
Alternative migration option - not recommended
Add @playwright/browser-chromium
, @playwright/browser-firefox
and @playwright/browser-webkit
as a dependency. These packages download respective browsers during npm install
. Make sure you keep the version of all playwright packages in sync:
// package.json
{
"devDependencies": {
"playwright": "1.38.0",
"@playwright/browser-chromium": "1.38.0",
"@playwright/browser-firefox": "1.38.0",
"@playwright/browser-webkit": "1.38.0"
}
}
This version was also tested against the following stable channels:
https://github.com/microsoft/playwright/issues/26496 - [REGRESSION] webServer stdout is always getting printed https://github.com/microsoft/playwright/issues/26492 - [REGRESSION] test.only with project dependency is not working
This version was also tested against the following stable channels:
Watch the overview: Playwright 1.36 & 1.37
If you run tests on multiple shards, you can now merge all reports in a single HTML report (or any other report)
using the new merge-reports
CLI tool.
Using merge-reports
tool requires the following steps:
Adding a new "blob" reporter to the config when running on CI:
export default defineConfig({
testDir: './tests',
reporter: process.env.CI ? 'blob' : 'html',
});
The "blob" reporter will produce ".zip" files that contain all the information about the test run.
Copying all "blob" reports in a single shared location and running npx playwright merge-reports
:
npx playwright merge-reports --reporter html ./all-blob-reports
Read more in our documentation.
Playwright now supports Debian 12 Bookworm on both x86_64 and arm64 for Chromium, Firefox and WebKit. Let us know if you encounter any issues!
Linux support looks like this:
Ubuntu 20.04 | Ubuntu 22.04 | Debian 11 | Debian 12 | |
---|---|---|---|---|
Chromium | ✅ | ✅ | ✅ | ✅ |
WebKit | ✅ | ✅ | ✅ | ✅ |
Firefox | ✅ | ✅ | ✅ | ✅ |
This version was also tested against the following stable channels:
https://github.com/microsoft/playwright/issues/24316 - [REGRESSION] Character classes are not working in globs in 1.36
This version was also tested against the following stable channels:
https://github.com/microsoft/playwright/issues/24184 - [REGRESSION]: Snapshot name contains some random string after test name when tests are run in container
This version was also tested against the following stable channels:
Watch the overview: Playwright 1.36 & 1.37
🏝️ Summer maintenance release.
This version was also tested against the following stable channels:
https://github.com/microsoft/playwright/issues/23622 - [Docs] Provide a description how to correctly use expect.configure with poll parameter https://github.com/microsoft/playwright/issues/23666 - [BUG] Live Trace does not work with Codespaces https://github.com/microsoft/playwright/issues/23693 - [BUG] attachment steps are not hidden inside expect.toHaveScreenshot()
This version was also tested against the following stable channels:
UI mode is now available in VSCode Playwright extension via a new "Show trace viewer" button:
UI mode and trace viewer mark network requests handled with page.route()
and browserContext.route()
handlers, as well as those issued via the API testing:
New option maskColor
for methods page.screenshot()
, locator.screenshot()
, expect(page).toHaveScreenshot()
and expect(locator).toHaveScreenshot()
to change default masking color:
await page.goto('https://playwright.dev');
await expect(page).toHaveScreenshot({
mask: [page.locator('img')],
maskColor: '#00FF00', // green
});
New uninstall
CLI command to uninstall browser binaries:
$ npx playwright uninstall # remove browsers installed by this installation
$ npx playwright uninstall --all # remove all ever-install Playwright browsers
Both UI mode and trace viewer now could be opened in a browser tab:
$ npx playwright test --ui-port 0 # open UI mode in a tab on a random port
$ npx playwright show-trace --port 0 # open trace viewer in tab on a random port
playwright-core
binary got renamed from playwright
to playwright-core
. So if you use playwright-core
CLI, make sure to update the name:
$ npx playwright-core install # the new way to install browsers when using playwright-core
This change does not affect @playwright/test
and playwright
package users.
This version was also tested against the following stable channels: