@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

⚠️ This project is not ready for production. Stay tuned! ⚠️

🎭 Playwright test runner

Cross-browser end-to-end testing for web apps. Browser automation with Playwright, Jest-like assertions and built-in support for TypeScript.

Playwright test runner is available in preview and minor breaking changes could happen. We welcome your feedback to shape this towards 1.0.

• Get started
  • Installation
  • Write a test
  • Tests and assertions syntax
  • Write a configuration file
  • Run the test suite
• Examples
  • Multiple pages
  • Mobile emulation
  • Network mocking
  • Visual comparisons
• Configuration
  • Modify options
  • Skip tests with annotations
  • Export JUnit report

Get started

Installation

npm i -D @playwright/test

Write a test

Create tests/foo.spec.ts to define your test. The test function uses the page argument for browser automation.

import { test, expect } from "@playwright/test";

test("is a basic test with the page", async ({ page }) => {
  await page.goto("https://playwright.dev/");
  const name = await page.innerText(".navbar__title");
  expect(name).toBe("Playwright");
});

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. Each test gets a new isolated context to run the test. The page object belongs to this context. Learn how to configure context creation.
• browser: Instance of Browser. Browsers are shared across tests to optimize resources. Learn how to configure browser launch.
• browserName: The name of the browser currently running the test. Either chromium, firefox or webkit.

You can now run the test using the underlying Folio command line:

# Assuming that test files are in the tests directory.
npx folio -c tests

Tests and assertions syntax

• Use test to write test functions. Run a single test with test.only and skip a test with test.skip.
• Use test.describe to group related tests together.
• Use test.beforeAll and test.afterAll hooks to set up and tear down resources shared between tests.
• Use test.beforeEach and test.afterEach hooks to set up and tear down resources for each test individually.
• For assertions, use the expect API.

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

test.describe("feature foo", () => {
  test.beforeEach(async ({ page }) => {
    // Go to the starting url before each test.
    await page.goto("https://my.start.url/feature-foo");
  });

  test("is working correctly", async ({ page }) => {
    // Assertions use the expect API.
    expect(page.url()).toBe("https://my.start.url/feature-foo");
  });
});

Write a configuration file

Create config.ts to configure your tests: specify browser launch options, run tests in multiple browsers and much more. Here is an example configuration that runs every test in Chromium, Firefox and WebKit.

import { PlaywrightTestProject } from "@playwright/test";

const projects: PlaywrightTestProject[] = [
  {
    name: 'chromium',
    use: {
      browserName: 'chromium',
      headless: true,
      viewport: { width: 1280, height: 720 },
    },
  },

  {
    name: 'webkit',
    use: {
      browserName: 'webkit',
      headless: true,
      viewport: { width: 1280, height: 720 },
    },
  },

  {
    name: 'firefox',
    use: {
      browserName: 'firefox',
      headless: true,
      viewport: { width: 1280, height: 720 },
    },
  }
];

module.exports = {
  timeout: 30000,  // Each test is given 30 seconds.
  projects,
};

Run the test suite

Tests can be run in single or multiple browsers, in parallel or sequentially.

# Run all tests across Chromium, Firefox and WebKit
$ npx folio --config=config.ts

# Run tests on a single browser
$ npx folio --config=config.ts --project=chromium

# Run tests in parallel
$ npx folio --config=config.ts --workers=5

# Run tests sequentially
$ npx folio --config=config.ts --workers=1

# Retry failing tests
$ npx folio --config=config.ts --retries=2

# See all options
$ npx folio --help

Refer to the command line documentation for all options.

Configure NPM scripts

Save the run command as an NPM script.

{
  "scripts": {
    "test": "npx folio --config=config.ts"
  }
}

---

Examples

Multiple pages

The default context argument is a BrowserContext. Browser contexts are isolated execution environments that can host multiple pages. See multi-page scenarios for more examples.

import { test } from "@playwright/test";

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

Mobile emulation

use section in the configuration file can be used to configure mobile emulation in the default context.

// config.ts
import { PlaywrightTestProject } from "@playwright/test";
+ import { devices } from "playwright";

const projects: PlaywrightTestProject[] = [
  {
    name: 'chromium',
    use: {
      browserName: 'chromium',
      headless: true,
-     viewport: { width: 1280, height: 720 },
+     ...devices["Pixel 2"],
    },
  },

  {
    name: 'webkit',
    use: {
      browserName: 'webkit',
      headless: true,
-     viewport: { width: 1280, height: 720 },
+     ...devices["iPhone 11"],
    },
  },

  {
    name: 'firefox',
    use: {
      browserName: 'firefox',
      headless: true,
      viewport: { width: 1280, height: 720 },
    },
  }
];

module.exports = {
  timeout: 30000,  // Each test is given 30 seconds.
  projects,
};

Network mocking

Define a custom route that mocks network calls for a browser context.

// In foo.spec.ts
import { test, expect } from "@playwright/test";

test.beforeEach(async ({ context }) => {
  // Block any css requests for each test in this file.
  await context.route(/.css/, route => route.abort());
});

test("loads page without css", async ({ page }) => {
  // Alternatively, block any png requests just for this test.
  await page.route(/.png/, route => route.abort());

  // Test function code.
  await page.goto("https://stackoverflow.com");
});

Visual comparisons

The expect API supports visual comparisons with toMatchSnapshot. This uses the pixelmatch library, and you can pass threshold as an option.

import { test, expect } from "@playwright/test";

test("compares page screenshot", async ({ page }) => {
  await page.goto("https://stackoverflow.com");
  const screenshot = await page.screenshot();
  expect(screenshot).toMatchSnapshot(`test.png`, { threshold: 0.2 });
});

On first execution, this will generate golden snapshots. Subsequent runs will compare against the golden snapshots. To update golden snapshots with new actuals, run with the --update-snapshots flag.

# Update golden snapshots when they differ from actual
npx folio --update-snapshots

---

Configuration

Modify options

You can modify browser launch options, context creation options and testing options either globally in the configuration file, or locally in the test file.

Playwright test runner is based on the Folio framework, so it supports any configuration available in Folio, and adds a lot of Playwright-specific options.

Globally in the configuration file

You can specify different options for each browser using projects in the configuration file. Below is an example that changes some global testing options, and Chromium browser configuration.

// config.ts
import { PlaywrightTestProject } from "@playwright/test";

const projects: PlaywrightTestProject[] = [
  {
    name: 'chromium',
    use: {
      browserName: 'chromium',
-     headless: true,
-     viewport: { width: 1280, height: 720 },
+
+     // Launch options:
+     headless: false,
+     slowMo: 50,
+
+     // Context options:
+     viewport: { width: 800, height: 600 },
+     ignoreHTTPSErrors: true,
+
+     // Testing options:
+     video: 'retain-on-failure',    },
  },

  {
    name: 'webkit',
    use: {
      browserName: 'webkit',
      headless: true,
      viewport: { width: 1280, height: 720 },
    },
  },

  {
    name: 'firefox',
    use: {
      browserName: 'firefox',
      headless: true,
      viewport: { width: 1280, height: 720 },
    },
  }
];

module.exports = {
- timeout: 30000,  // Each test is given 30 seconds.
+ timeout: 90000,  // Each test is given 90 seconds.
+ retries: 2,  // Failing tests will be retried at most two times.
  projects,
};

Locally in the test file

With test.use() you can override some options for a file, or a describe block.

// my.spec.ts
import { test, expect } from "@playwright/test";

// Run tests in this file with portrait-like viewport.
test.use({ viewport: { width: 600, height: 900 } });

test('my test', async ({ page }) => {
  // Test code goes here.
});

Available options

See the full list of launch options in browserType.launch() documentation.

See the full list of context options in browser.newContext() documentation.

Available testing options:

• screenshot: 'off' | 'on' | 'only-on-failure' - Whether to capture a screenshot after each test, off by default.
  • off - Do not capture screenshots.
  • on - Capture screenshot after each test.
  • only-on-failure - Capture screenshot after each test failure.
• video: 'off' | 'on' | 'retain-on-failure' | 'retry-with-video' - Whether to record video for each test, off by default.
  • off - Do not record video.
  • on - Record video for each test.
  • retain-on-failure - Record video for each test, but remove all videos from successful test runs.
  • retry-with-video - Record video only when retrying a test.

Most notable testing options from Folio documentation:

• retries: number - Each failing test will be retried up to the certain number of times.
• testDir: string - Directory where test runner should search for test files.
• timeout: number - Timeout in milliseconds for each test.
• workers: number - The maximum number of worker processes to run in parallel.

Skip tests with annotations

The Playwright test runner can annotate tests to skip under certain parameters. This is enabled by Folio annotations.

test("should be skipped on firefox", async ({ page, browserName }) => {
  test.skip(browserName === "firefox", "optional description for the skip");
  // Test function
});

Export JUnit report

The Playwright test runner supports various reporters, including exporting as a JUnit compatible XML file.

// config.ts
import { PlaywrightTestProject } from "@playwright/test";

const projects: PlaywrightTestProject[] = [
  {
    name: 'chromium',
    use: {
      browserName: 'chromium',
      headless: true,
      viewport: { width: 1280, height: 720 },
    },
  },

  {
    name: 'webkit',
    use: {
      browserName: 'webkit',
      headless: true,
      viewport: { width: 1280, height: 720 },
    },
  },

  {
    name: 'firefox',
    use: {
      browserName: 'firefox',
      headless: true,
      viewport: { width: 1280, height: 720 },
    },
  }
];

module.exports = {
  timeout: 30000,  // Each test is given 30 seconds.
+ reporter: [
+  'list',  // Terminal output
+  { name: 'junit', outputFile: 'report.xml' },  // And junit report
+ ],
  projects,
};