@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

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
  • Mobile emulation
  • Network mocking

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. Test functions can use one or more of these arguments.

• 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.
  • contextOptions: Default options passed to context creation.
• browser: Instance of Browser. Browsers are shared across tests to optimize resources. Each worker process gets a browser instance.
  • browserOptions: Default options passed to browser creation.

Specs and assertions

• Use it and describe to write test functions. Run a single test with it.only and skip a test with it.skip.
• For assertions, use the expect API.

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

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

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

# Record videos
npx folio --param video

# 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 default context argument is a [BrowserContext][browser-context]. Browser contexts are isolated execution environments that can host multiple pages. See multi-page scenarios for more examples.

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

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

Mobile emulation

The contextOptions fixture defines default options used for context creation. This fixture can be overriden to configure mobile emulation in the default context.

import { folio } from '@playwright/test';
import { devices } from 'playwright';

const fixtures = folio.extend();
fixtures.contextOptions.override(async ({ contextOptions }, runTest) => {
  await runTest({
    ...contextOptions,
    ...devices['iPhone 11']
  });
});
const { it, describe, extend } = fixtures.build();

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

Network mocking

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

// In fixtures.ts
import { folio as base } from '@playwright/test';
import { BrowserContext } from 'playwright';

// Extend base fixtures with a new test-level fixture
const fixtures = base.extend<{ mockedContext: BrowserContext }>();

fixtures.mockedContext.init(async ({ context }, runTest) => {
  // Modify existing `context` fixture to add a route
  context.route(/.css/, route => route.abort());
  // Pass fixture to test functions
  runTest(context);
});

export folio = fixtures.build();

// In foo.spec.ts
import { folio } from './fixtures';
const { it, expect } = folio;

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