1.41.1 • Published 3 months ago

@playwright/test v1.41.1

Weekly downloads
2,036
License
Apache-2.0
Repository
github
Last release
3 months ago

🎭 Playwright test runner npm version

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

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 { 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.

Write a configuration file

Create config.ts to configure your tests. Here is an example configuration that runs every test in Chromium, Firefox and WebKit.

import { ChromiumEnv, FirefoxEnv, WebKitEnv, test, setConfig } from "@playwright/test";

setConfig({
  testDir: __dirname,  // Search for tests in this directory.
  timeout: 30000,  // Each test is given 30 seconds.
});

const options = {
  headless: true,  // Run tests in headless browsers.
  viewport: { width: 1280, height: 720 },
};

// Run tests in three browsers.
test.runWith(new ChromiumEnv(options), { tag: 'chromium' });
test.runWith(new FirefoxEnv(options), { tag: 'firefox' });
test.runWith(new WebKitEnv(options), { tag: 'webkit' });

Run the test

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 --tag=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

Configure NPM scripts

Save the run command as an NPM script.

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

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

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

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

// config.ts
import { ChromiumEnv, FirefoxEnv, WebKitEnv, test, setConfig } from "@playwright/test";
+ import { devices } from "playwright";

setConfig({
  testDir: __dirname,  // Search for tests in this directory.
  timeout: 30000,  // Each test is given 30 seconds.
});

const options = {
  headless: true,  // Run tests in headless browsers.
-  viewport: { width: 1280, height: 720 },
+  ...devices["iPhone 11"],
};

// Run tests in three browsers.
test.runWith(new ChromiumEnv(options), { tag: 'chromium' });
test.runWith(new FirefoxEnv(options), { tag: 'firefox' });
test.runWith(new WebKitEnv(options), { tag: 'webkit' });

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 in the configuration file.

// config.ts
import { ChromiumEnv, FirefoxEnv, WebKitEnv, test, setConfig } from "@playwright/test";

setConfig({
  testDir: __dirname,  // Search for tests in this directory.
-  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.
});

const options = {
-  headless: true,  // Run tests in headless browsers.
-  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',
};

// Run tests in three browsers.
test.runWith(new ChromiumEnv(options), { tag: 'chromium' });
test.runWith(new FirefoxEnv(options), { tag: 'firefox' });
test.runWith(new WebKitEnv(options), { tag: 'webkit' });

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 configuration options, see the full list in Folio documentation:

  • retries: number - Each failing test will be retried up to the certain number of times.
  • workers: number - The maximum number of worker processes to run in parallel.

Browser-specific options

You can specify different options for each browser when creating a corresponding environment.

// config.ts
import { ChromiumEnv, FirefoxEnv, WebKitEnv, test, setConfig } from "@playwright/test";

setConfig({
  testDir: __dirname,  // Search for tests in this directory.
  timeout: 30000,  // Each test is given 30 seconds.
});

const options = {
  headless: true,  // Run tests in headless browsers.
  viewport: { width: 1280, height: 720 },
};

// Run tests in three browsers.
test.runWith(new ChromiumEnv(options), { tag: 'chromium' });
test.runWith(new FirefoxEnv(options), { tag: 'firefox' });
- test.runWith(new WebKitEnv(options), { tag: 'webkit' });
+ test.runWith(new WebKitEnv({
+   ...options,
+   viewport: { width: 800, height: 600 },  // Use different viewport for WebKit.
+ }), { tag: 'webkit' });

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

Modify context options for a single test

Pass a second parameter that has contextOptions property to the test function:

const options = {
  contextOptions: {
    ignoreHTTPSErrors: true,
  }
};

test("no https errors in this test", options, async ({ page }) => {
  // Test function
});

Export JUnit report

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

# Specify output file as an environment variable
# Linux/macOS
$ export FOLIO_JUNIT_OUTPUT_NAME=junit.xml
# Windows
$ set FOLIO_JUNIT_OUTPUT_NAME=junit.xml

# Use junit and CLI reporters
$ npx folio --reporter=junit,line

# See all supported reporters
$ npx folio --help
@lwk7454/metaspacex-autofarmbytestrone_playwrightframework_typescript_v3appist-devshipment-portal-e2e@dozero/test@infinitebrahmanuniverse/nolb-_playmax-playwright@everything-registry/sub-chunk-726ui-test-dataframe-builderproperty-automationpwf-test-ckpwf-ckpw-simple-testrail-reporterpw-test-logs-reporterpwmochawesomeprism-playwrightqyk-cli@roomle/rubens-clisk-e2e-1sk_e2e_2@sakamoto66/playwright-markdown-timeline-reporter@sakamoto66/playwright-summary-reporter@patternfly/pfe-toolsrete-qa@ouardini/scrapeyard@octomind/debugtopus@ocsjs/scripts@phantom/synpress@opensumi/playwrightsandeepfw@previewjs/testingsample-es2@prestashop-core/prestashop-ui-testing@prestashop-core/ui-testing@prestashopcorp/tests-framework@stacksjs/testing@sloonzz/synpress@silenteer/pw-shell@skunal8197/synpress-flask@near-wallet/e2e-tests@neovici/cfgrailflow-zephyr@mollify/lms@mollify/mollypeoplehr-approver@mentimeter/play-lambda@mayankbhatt1004/sample-api-client@mega-apps/cli@mega-apps/test-cli-demo@nocobase/test@matthijsburgh/vue-cli-plugin-electron-builder@ngx-playwright/test@now11/play-pw@sanity/test@scalewright/performance-trackingspuronejs@serenity-js/playwright-testsprintsq@storefront-x/testing@tester119/wallets-testing-widgets@tester120/wallets-testing-wallets@tester120/wallets-testing-widgets@tester221/wallets-testing-wallets@tester112/wallets-testing-wallets@tester112/wallets-testing-widgets@tester113/wallets-testing-wallets@tester113/wallets-testing-widgets@tester221/wallets-testing-widgets@tester223/wallets-testing-wallets@tester223/wallets-testing-widgets@tester234/wallets-testing-wallets@tester234/wallets-testing-widgets@tester513/wallets-testing-wallets@tester513/wallets-testing-widgets@tester667/wallets-testing-wallets@tester667/wallets-testing-widgets@tester114/wallets-testing-wallets@tester114/wallets-testing-widgets@tester115/wallets-testing-wallets@tester115/wallets-testing-widgets@tester116/wallets-testing-wallets@tester116/wallets-testing-widgets@tester117/wallets-testing-wallets@tester117/wallets-testing-widgets@tester118/wallets-testing-wallets@tester118/wallets-testing-widgets@tester119/wallets-testing-walletsticatec-data-sheet@open-xchange/appsuite-codeceptjssafetestsalesforce-test-automation-frameworkroamjs-scriptsscrapeyard@public-ui/visual-tests@qavajs/steps-playwright@spscommerce/e2e-core@spartan-org/e2e-playwrighttest-ipfs-exampletest-framework-001test-framework-dev
1.41.1

3 months ago

1.41.0

3 months ago

1.39.0

7 months ago

1.40.0

5 months ago

1.40.1

5 months ago

1.36.0

10 months ago

1.36.1

10 months ago

1.36.2

9 months ago

1.37.0

9 months ago

1.37.1

8 months ago

1.38.0

8 months ago

1.38.1

7 months ago

1.35.1

11 months ago

1.35.0

11 months ago

1.34.2

11 months ago

1.34.3

11 months ago

1.34.0

11 months ago

1.34.1

11 months ago

1.32.2

1 year ago

1.32.3

1 year ago

1.33.0

1 year ago

1.32.0

1 year ago

1.32.1

1 year ago

1.31.2

1 year ago

1.31.1

1 year ago

1.31.0

1 year ago

1.30.0

1 year ago

1.29.0

1 year ago

1.29.1

1 year ago

1.29.2

1 year ago

1.28.1

1 year ago

1.28.0

1 year ago

1.27.0

2 years ago

1.27.1

2 years ago

1.26.0

2 years ago

1.26.1

2 years ago

1.25.1

2 years ago

1.25.2

2 years ago

1.24.1

2 years ago

1.24.2

2 years ago

1.24.0

2 years ago

1.23.2

2 years ago

1.23.3

2 years ago

1.23.0

2 years ago

1.23.1

2 years ago

1.23.4

2 years ago

1.25.0

2 years ago

1.22.0

2 years ago

1.22.1

2 years ago

1.22.2

2 years ago

1.20.1

2 years ago

1.20.2

2 years ago

1.21.0

2 years ago

1.21.1

2 years ago

1.20.0

2 years ago

1.18.1

2 years ago

1.18.0

2 years ago

1.19.0

2 years ago

1.19.2

2 years ago

1.19.1

2 years ago

1.18.0-rc1

2 years ago

1.17.2

2 years ago

1.17.0-rc1

2 years ago

1.17.1

2 years ago

1.17.0

2 years ago

1.16.3

2 years ago

1.16.2

3 years ago

1.16.1

3 years ago

1.16.0

3 years ago

1.15.2

3 years ago

1.15.1

3 years ago

1.15.0

3 years ago

1.14.1

3 years ago

1.14.0

3 years ago

1.13.1

3 years ago

1.13.0

3 years ago

1.12.3

3 years ago

1.12.2

3 years ago

1.12.1

3 years ago

1.12.0

3 years ago

0.1112.0-alpha3

3 years ago

0.1112.0-alpha2

3 years ago

0.1112.0-alpha1

3 years ago

0.1111.0

3 years ago

0.1102.0-alpha1

3 years ago

0.1102.0

3 years ago

0.1110.0

3 years ago

0.1101.0

3 years ago

0.1101.0-alpha2

3 years ago

0.1101.0-alpha

3 years ago

0.1100.0

3 years ago

0.192.0

3 years ago

0.191.0

3 years ago

0.180.0

3 years ago

0.171.0

3 years ago

0.170.0

3 years ago

0.162.0

3 years ago

0.152.0

3 years ago

0.151.1

4 years ago

0.151.0

4 years ago

0.9.21-post

4 years ago

0.9.18

4 years ago

0.9.19

4 years ago

0.150.0

4 years ago

0.9.20

4 years ago

0.9.21

4 years ago

0.9.22

4 years ago

0.9.17

4 years ago

0.9.16

4 years ago

0.9.14

4 years ago

0.9.15

4 years ago

0.9.12

4 years ago

0.9.13

4 years ago

0.9.11

4 years ago

0.9.10

4 years ago

0.9.9

4 years ago

0.9.8

4 years ago

0.9.7

4 years ago

0.9.4

4 years ago

0.9.3

4 years ago

0.9.6

4 years ago

0.9.5

4 years ago

0.9.2

4 years ago

0.3.29

4 years ago

0.3.28

4 years ago

0.9.1

4 years ago

0.3.27

4 years ago

0.3.26

4 years ago