@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 web 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
• 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

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

Learn how to customize or create your own arguments with test fixtures.

• page: Instance of Page. Each test gets a new isolated page to run the test.
• context: Instance of BrowserContext. 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.

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. See annotations to mark tests as slow, flaky or fixme.

Assertions

For assertions, the test runner uses the expect package. 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 --browser-name=chromium

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

# Take screenshots on failure
npx folio --screenshot-on-failure

# See all options
npx folio --help

---

Parallelized execution

The test runner launches a number of worker processes to parallelize test execution. By default, this number is equal to number of CPU cores divided by 2. Each worker process runs a browser and some tests.

To run in serial, use the --jobs flag.

npx folio --jobs 1

Setup environment with fixtures

Fixtures initialize your test functions. Fixtures can be used to set up the test environment with services and state that are required by the test.

For end-to-end testing, this test runner sets up a page in a browser. This behavior can be customized.

Default fixtures

• Each worker process launches a browser (this is the browser fixture).
  • The browser fixture uses the defaultBrowserOptions fixture to define browser launch options.
• Each worker runs tests.
• Each test is provided a browser context (context fixture) and a page (page fixture). Browser contexts are isolated execution environments that share a browser instance.
  • The context fixture uses the defaultContextOptions fixture to define context options.

Examples

// Test uses the page fixture
it('should load the website', async ({ page }) => {
  await page.goto('https://playwright.dev');
  expect(await page.title()).toContain('Playwright');
});

// Test uses the context fixture and launches multiple pages
it('should load two pages', async ({ context }) => {
  const pageOne = await context.newPage();
  const pageTwo = await context.newPage();
  // ...
})

Override default fixtures

Default options can be overriden to specific testing requirements. For example, defaultContextOptions can be modified to launch browser contexts with mobile emulation.

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

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

Define custom fixtures

It is possible to define custom fixtures to setup the test environment. If the fixture is to be shared across tests, define a worker-level fixture. If not, use test-level fixtures.

For example, we can extend the default page fixture to navigate to a URL before running the tests. This will be a test-level fixture. This can be further extended to wrap the page into a page object model.

fixtures.defineTestFixture('homePage', async({page}, test) => {
  await page.goto('https://playwright.dev/');
  await test(page);
});

it('should be on the homepage', async ({homePage}) => { 
  expect(await homePage.title()).toContain('Playwright');
});

TODO: How to add TypeScript support with declareTestFixtures

Parameterize your tests

A common pattern with end-to-end tests is to run test suites against multiple parameters.

Default parameters

browserName: Can be chromium, firefox or webkit. Tests are parameterized across the 3 browsers.

Custom parameters

You can define custom parameters

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

// Define the parameter
fixtures.defineParameter('appUrl', 'URL of the app to test against', 'http://localhost');
//                         |          |                               |
//                       Name      Description                     Default value

// To generate parameterized tests
fixtures.generateParameterizedTests('appUrl', ['https://production.app',
                                               'https://staging.app']);

// Use in your test
// NOTE: Only the tests that have appUrl as arguments will be parameterized
it('should add item to cart', async ({ appUrl }) => {
  // ...
})

TODO: How to add TypeScript support with declareParameters

To run tests with a custom value for the parameter, convert the name of the parameter into kebab-case (appUrl becomes app-url)

npx folio --app-url=https://newlocation.app

Annotate your tests

Annotate your tests with modifiers: flaky, fixme, fail, skip, and slow.

Annotations can be applied conditionally with parameters.

test.skip(params.browserName === 'firefox', 'Not supported for Firefox')

One or more annotations can be combined.

it('should add item to cart', (test, params) => {
  test.flaky('Uses Math.random internally')
  test.skip(params.browserName == 'firefox')
}, async ({ page }) => {
  // Test content
})

Spec syntax

To run a single test use fit or it.only.

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

it.only('should be focused', ...);
// Alternatively
fit('should be focused', ...);

To skip a test use xit or it.skip.

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

it.skip('should be skipped', ...);
// Alternatively
xit('should be skipped', ...);

Tests can be wrapped inside describe blocks to structure tests.

Assertions

For assertions, the test runner uses the popular expect package. See expect API reference.