🎭 End-to-end web tests with Playwright

🚧 This project is under active development and is not ready for serious use.

Zero config cross-browser end-to-end testing for web apps. Browser automation with Playwright, Jest-like assertions and support for TypeScript.

• Get started
  • Installation
  • Write a test
  • Run the test
• Examples
  • Multiple pages
  • Network mocking
  • Mobile emulation
• Customize your suite
  • Annotations
  • Parameters
  • Fixtures
  • Parallel execution
  • Retries

Get started

Installation

npm i -D @playwright/test

Write a test

Create foo.spec.ts (or foo.spec.js) to define your test. Playwright provides a page argument to the test function.

// tests/foo.spec.ts
const { it, expect } = require('@playwright/test');

it('is a basic test with the page', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  const home = await page.waitForSelector('home-navigation');
  expect(await home.innerText()).toBe('🎭 Playwright');
});

Default arguments

The test runner provides browser primitives as arguments to your test functions. Tests can use one or more of these primitives.

• page: Instance of Page. Each test gets a new isolated page to run the test.
• context: Instance of [BrowserContext][browser-context]. Each test gets a new isolated context to run the test. The page object belongs to this context.
• browser: Instance of Browser. Browsers are shared across tests to optimize resources. Each worker process gets a browser instance.

Use test fixtures to customize or create new function arguments.

Spec syntax

Use it and describe to write test functions.

const { it, describe } = require('@playwright/test');

describe('feature foo', () => {
  it('is working correctly', async ({ page }) => {
    // Test function
    // ...
  })
});

To run a single test use fit or it.only. To skip a test use xit or it.skip. Use test annotations to mark tests as slow, flaky or fixme.

Assertions

The test runner provides the expect package for assertions. See expect API reference.

Run the test

Tests can be run on single or multiple browsers and with flags to generate screenshot on test failures.

# Run all tests across Chromium, Firefox and WebKit
npx folio

# Run tests on a single browser
npx folio --param browserName=chromium

# Run all tests in headful mode
npx folio --param headful

# Take screenshots on failure
npx folio --param screenshotOnFailure

# See all options
npx folio --help

Test runner CLI can be customized with test parameters.

Examples

Multiple pages

The context argument is an instance of [BrowserContext][browser-context]. Browser contexts are isolated execution environments that can host multiple pages.

const { it } = require('@playwright/test');

it('tests on multiple web pages', async ({ context }) => {
  const pageFoo = await context.newPage();
  const pageBar = await context.newPage();
  // Test function code
});

See multi-page scenarios for more examples.

Network mocking

Define a custom argument that mocks networks call for a browser context.

const { it, fixtures } = require('@playwright/test');

fixtures.mockedContext.init(async ({ context }, runTest) => {
  context.route(/.css/, route => route.abort());
  runTest(context);
});

it('loads pages without css requests', async ({ mockedContext }) => {
  const page = await mockedContext.newPage();
  await page.goto('https://stackoverflow.com');
  // Test function code
});

Mobile emulation

Override default options for creating a BrowserContext to use mobile emulation.

const { it, fixtures } = require('@playwright/test');
const { devices } = require('playwright');

fixtures.defaultContextOptions.override(async ({}, runTest) => {
  await runTest({ ...devices['iPhone 11'] });
});

it('uses mobile emulation', async ({ context }) => {
  // Test function code
});