Microsoft released (in preview) a dedicated test runner for Playwright, its test automation tool. The Playwright test runner provides zero-config cross-browser end-to-end testing for web apps, Jest-like assertions, and built-in support for TypeScript. The new test runner leverages Folio, a customizable test framework to build higher-level test frameworks.
While testing libraries are actively developed by the community (e.g., playwright-testing-library, or jest-playwright), some developers expressed interest on Reddit for an integrated testing library built specifically for Playwright. Microsoft released in preview the Playwright official test runner after using it internally for a few months.
The Playwright test runner provides it
, describe
, and expect
APIs that can be used as follows:
import { it, expect, describe } from "@playwright/test";
describe("feature foo", () => {
it("compares page screenshot", async ({ page, browserName }) => {
await page.goto("https://stackoverflow.com");
const screenshot = await page.screenshot();
expect(screenshot).toMatchSnapshot(`test-${browserName}.png`, { threshold: 0.2 });
});
});
As the previous code illustrates, the tests defined with it
use an asynchronous function that is passed a set of arguments. The default arguments are page
(an instance of a Playwright Page object); context
(an instance of BrowserContext) and contextOptions
; and browser
and browserOptions
. The documentation provides examples of usage of the default arguments to handle testing multiple pages, produce visual snapshots and make visual comparisons, emulate mobile devices, and mock network calls.
Tests can be run on a single or multiple browsers, in headful or headless mode. Tests may also be slowed down, have screenshots saved in a separate directory in case of failure, or be video-recorded.
For advanced configurations and fixtures, developers may use Folio APIs. Folio self-describes as “a customizable test framework to build your own test frameworks”. An example of using Folio to configure viewport size and HTTPS error handling is as follows:
// test/fixtures.ts
import { folio as baseFolio } from "@playwright/test";
import { BrowserContextOptions } from "playwright";
const builder = baseFolio.extend();
builder.contextOptions.override(async ({ contextOptions }, runTest) => {
const modifiedOptions: BrowserContextOptions = {
...contextOptions, // default
viewport: { width: 1440, height: 900 }
}
await runTest(modifiedOptions);
});
const folio = builder.build();
export const it = folio.it;
export const expect = folio.expect;
// test/index.spec.ts
The previous fixture file (test/fixtures.ts
) creates and exports fixture-ready it
and expect
methods to be used in test specifications as follows:
// test/index.spec.ts
import { it, expect } from "./fixtures";
// Test functions go here
it("should have modified viewport", async ({ context }) => {
// ...
});
Folio additionally supports test annotations to deal with failures, flakiness, and tests that are not yet ready.
The Playwright test runner can be installed as follows:
npm i -D @playwright/test
Folio is actively developed and pending release. Folio is an open-source project under the Apache 2 license. The Playwright test runner is nearing the release of its first major iteration. Feedback is welcome and should follow the contribution guidelines and code of conduct.