@playwright/test

What is @playwright/test?

The @playwright/test npm package is a framework for end-to-end testing that allows developers to automate browser interactions for testing web applications. It supports multiple browsers, provides a rich set of APIs for navigation, interaction, and assertions, and offers features like test parallelization, fixtures, and snapshot testing.

What are @playwright/test's main functionalities?

Browser Automation

Automate browser actions such as navigating to a URL, interacting with page elements, and validating page properties.

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

test('basic test', async ({ page }) => {
  await page.goto('https://example.com');
  const title = await page.title();
  expect(title).toBe('Example Domain');
});

Cross-Browser Testing

Run tests across multiple browsers like Chromium, Firefox, and WebKit.

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

test.describe.configure({ browsers: ['chromium', 'firefox', 'webkit'] });

test('cross-browser test', async ({ page }) => {
  await page.goto('https://example.com');
  // Perform cross-browser checks
});

Mobile Emulation

Emulate mobile devices to test responsive designs and touch interactions.

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

const iPhone11 = devices['iPhone 11 Pro'];

test('mobile emulation test', async ({ browser }) => {
  const context = await browser.newContext({
    ...iPhone11,
  });
  const page = await context.newPage();
  await page.goto('https://example.com');
  // Perform actions in the emulated mobile environment
});

Visual Regression Testing

Capture screenshots and compare them against known good snapshots to detect visual regressions.

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

test('visual test', async ({ page }) => {
  await page.goto('https://example.com');
  expect(await page.screenshot()).toMatchSnapshot('homepage.png');
});

Test Fixtures

Create reusable test setup and teardown logic with fixtures.

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

test('use fixture', async ({ myFixture }) => {
  // Use the fixture in the test
});

test.extend({
  myFixture: async ({}, use) => {
    // Set up the fixture
    await use('some value');
    // Clean up the fixture
  },
});

Other packages similar to @playwright/test

cypress

Cypress is a popular end-to-end testing framework similar to Playwright. It offers a rich interactive test runner and has a focus on ease of use. Unlike Playwright, Cypress only supports testing in a Chromium-based browser, which can be a limitation for cross-browser testing.

selenium-webdriver

Selenium WebDriver is one of the oldest and most widely used browser automation tools. It supports multiple programming languages and browsers. Compared to Playwright, Selenium tests tend to be slower and can be more flaky due to reliance on the WebDriver protocol.

puppeteer

Puppeteer is a Node library developed by the Chrome DevTools team. It provides a high-level API to control Chrome or Chromium over the DevTools Protocol. Playwright is considered a successor to Puppeteer and extends its capabilities by supporting more browsers and additional features.

nightwatch

Nightwatch.js is an automated testing framework for web applications and websites, using the W3C WebDriver API. It is easy to use and set up. Compared to Playwright, Nightwatch may have less advanced features and browser support but is still a solid choice for many testing scenarios.

testcafe

TestCafe is a node.js tool for automating end-to-end web testing. It is known for its ease of setup and use, and it does not require WebDriver. Unlike Playwright, TestCafe runs tests written in JavaScript or TypeScript directly in the browser which can be both an advantage and a limitation depending on the context.

README

🎭 End-to-end 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 to define your test. The test function uses the page argument for browser automation.

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

it('is a basic test with the page', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  const name = await page.innerText('.home-navigation');
  expect(name).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.

Specs and assertions

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.

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

# Save screenshots on failure in test-results directory
npx folio --param screenshotOnFailure

# See all options
npx folio --help

Test runner CLI can be customized with test parameters.

Configure NPM scripts

Save the run command as an NPM script.

{
  "scripts": {
    "test": "npx folio --param screenshotOnFailure"
  }
}

---

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
});