Skip to main content
Version: 1.15

Playwright Test

Playwright Test provides a test function to declare tests and expect function to write assertions.

import { test, expect } from '@playwright/test';
test('basic test', async ({ page }) => {  await page.goto('https://playwright.dev/');  const name = await page.innerText('.navbar__title');  expect(name).toBe('Playwright');});

test(title, testFunction)#

Declares a test.

import { test, expect } from '@playwright/test';
test('basic test', async ({ page }) => {  await page.goto('https://playwright.dev/');  const name = await page.innerText('.navbar__title');  expect(name).toBe('Playwright');});

test.afterAll(hookFunction)#

Declares an afterAll hook that is executed once after all tests. When called in the scope of a test file, runs after all tests in the file. When called inside a test.describe(title, callback) group, runs after all tests in the group.

test.afterEach(hookFunction)#

Declares an afterEach hook that is executed after each test. When called in the scope of a test file, runs before each test in the file. When called inside a test.describe(title, callback) group, runs before each test in the group.

test.beforeAll(hookFunction)#

Declares a beforeAll hook that is executed once before all tests. When called in the scope of a test file, runs before all tests in the file. When called inside a test.describe(title, callback) group, runs before all tests in the group.

// example.spec.tsimport { test, expect } from '@playwright/test';
test.beforeAll(async () => {  console.log('Before tests');});
test.afterAll(async () => {  console.log('After tests');});
test('my test', async ({ page }) => {  // ...});

You can use test.afterAll(hookFunction) to teardown any resources set up in beforeAll.

test.beforeEach(hookFunction)#

Declares a beforeEach hook that is executed before each test. When called in the scope of a test file, runs before each test in the file. When called inside a test.describe(title, callback) group, runs before each test in the group.

// example.spec.tsimport { test, expect } from '@playwright/test';
test.beforeEach(async ({ page }) => {  // Go to the starting url before each test.  await page.goto('https://my.start.url/');});
test('my test', async ({ page }) => {  expect(page.url()).toBe('https://my.start.url/');});

You can use test.afterEach(hookFunction) to teardown any resources set up in beforeEach.

test.describe(title, callback)#

Declares a group of tests.

test.describe('two tests', () => {  test('one', async ({ page }) => {    // ...  });
  test('two', async ({ page }) => {    // ...  });});

test.describe.only(title, callback)#

Declares a focused group of tests. If there are some focused tests or suites, all of them will be run but nothing else.

test.describe.only('focused group', () => {  test('in the focused group', async ({ page }) => {    // This test will run  });});test('not in the focused group', async ({ page }) => {  // This test will not run});

test.describe.parallel(title, callback)#

Declares a group of tests that could be run in parallel. By default, tests in a single test file run one after another, but using test.describe.parallel(title, callback) allows them to run in parallel.

test.describe.parallel('group', () => {  test('runs in parallel 1', async ({ page }) => {  });  test('runs in parallel 2', async ({ page }) => {  });});

Note that parallel tests are executed in separate processes and cannot share any state or global variables. Each of the parallel tests executes all relevant hooks.

test.describe.parallel.only(title, callback)#

Declares a focused group of tests that could be run in parallel. By default, tests in a single test file run one after another, but using test.describe.parallel(title, callback) allows them to run in parallel. If there are some focused tests or suites, all of them will be run but nothing else.

test.describe.parallel.only('group', () => {  test('runs in parallel 1', async ({ page }) => {  });  test('runs in parallel 2', async ({ page }) => {  });});

Note that parallel tests are executed in separate processes and cannot share any state or global variables. Each of the parallel tests executes all relevant hooks.

test.describe.serial(title, callback)#

Declares a group of tests that should always be run serially. If one of the tests fails, all subsequent tests are skipped. All tests in a group are retried together.

note

Using serial is not recommended. It is usually better to make your tests isolated, so they can be run independently.

test.describe.serial('group', () => {  test('runs first', async ({ page }) => {  });  test('runs second', async ({ page }) => {  });});

test.describe.serial.only(title, callback)#

Declares a focused group of tests that should always be run serially. If one of the tests fails, all subsequent tests are skipped. All tests in a group are retried together. If there are some focused tests or suites, all of them will be run but nothing else.

note

Using serial is not recommended. It is usually better to make your tests isolated, so they can be run independently.

test.describe.serial.only('group', () => {  test('runs first', async ({ page }) => {  });  test('runs second', async ({ page }) => {  });});

test.fail([condition, description])#

  • condition <void|boolean|function(Fixtures):boolean> Optional condition - either a boolean value, or a function that takes a fixtures object and returns a boolean. Test or tests are marked as "should fail" when the condition is true.#
  • description <void|string> Optional description that will be reflected in a test report.#
  • returns: <void>#

Marks a test or a group of tests as "should fail". Playwright Test runs these tests and ensures that they are actually failing. This is useful for documentation purposes to acknowledge that some functionality is broken until it is fixed.

Unconditional fail:

import { test, expect } from '@playwright/test';
test('not yet ready', async ({ page }) => {  test.fail();  // ...});

Conditional fail a test with an optional description:

import { test, expect } from '@playwright/test';
test('fail in WebKit', async ({ page, browserName }) => {  test.fail(browserName === 'webkit', 'This feature is not implemented for Mac yet');  // ...});

Conditional fail for all tests in a file or test.describe(title, callback) group:

import { test, expect } from '@playwright/test';
test.fail(({ browserName }) => browserName === 'webkit');
test('fail in WebKit 1', async ({ page }) => {  // ...});test('fail in WebKit 2', async ({ page }) => {  // ...});

test.fixme([condition, description])#

  • condition <void|boolean|function(Fixtures):boolean> Optional condition - either a boolean value, or a function that takes a fixtures object and returns a boolean. Test or tests are marked as "fixme" when the condition is true.#
  • description <void|string> Optional description that will be reflected in a test report.#
  • returns: <void>#

Marks a test or a group of tests as "fixme". These tests will not be run, but the intention is to fix them.

Unconditional fixme:

import { test, expect } from '@playwright/test';
test('not yet ready', async ({ page }) => {  test.fixme();  // ...});

Conditional fixme a test with an optional description:

import { test, expect } from '@playwright/test';
test('fixme in WebKit', async ({ page, browserName }) => {  test.fixme(browserName === 'webkit', 'This feature is not implemented for Mac yet');  // ...});

Conditional fixme for all tests in a file or test.describe(title, callback) group:

import { test, expect } from '@playwright/test';
test.fixme(({ browserName }) => browserName === 'webkit');
test('fixme in WebKit 1', async ({ page }) => {  // ...});test('fixme in WebKit 2', async ({ page }) => {  // ...});

fixme from a hook:

import { test, expect } from '@playwright/test';
test.beforeEach(async ({ page }) => {  test.fixme(process.env.APP_VERSION === 'v2', 'No settings in v2 yet');  await page.goto('/settings');});

test.only(title, testFunction)#

Declares a focused test. If there are some focused tests or suites, all of them will be run but nothing else.

test.only('focus this test', async ({ page }) => {  // Run only focused tests in the entire project.});

test.setTimeout(timeout)#

Changes the timeout for the test.

import { test, expect } from '@playwright/test';
test('very slow test', async ({ page }) => {  test.setTimeout(120000);  // ...});

Changing timeout from a slow hook:

import { test, expect } from '@playwright/test';
test.beforeEach(async ({ page }, testInfo) => {  // Extend timeout for all tests running this hook by 30 seconds.  test.setTimeout(testInfo.timeout + 30000);});

Timeout for the currently running test is available through testInfo.timeout.

test.skip(title, testFunction)#

Declares a skipped test, similarly to test(title, testFunction). Skipped test is never run.

import { test, expect } from '@playwright/test';
test.skip('broken test', async ({ page }) => {  // ...});

test.skip()#

Unconditionally skip a test. Test is immediately aborted when you call test.skip().

import { test, expect } from '@playwright/test';
test('skipped test', async ({ page }) => {  test.skip();  // ...});

Unconditionally skip all tests in a file or test.describe(title, callback) group:

import { test, expect } from '@playwright/test';
test.skip();
test('skipped test 1', async ({ page }) => {  // ...});test('skipped test 2', async ({ page }) => {  // ...});

test.skip(condition, description)#

  • condition <boolean> A skip condition. Test or tests are skipped when the condition is true.#
  • description <void|string> An optional description that will be reflected in a test report.#
  • returns: <void>#

Conditionally skip a test with an optional description.

import { test, expect } from '@playwright/test';
test('skip in WebKit', async ({ page, browserName }) => {  test.skip(browserName === 'webkit', 'This feature is not implemented for Mac');  // ...});

Skip from test.beforeEach(hookFunction) hook:

import { test, expect } from '@playwright/test';
test.beforeEach(async ({ page }) => {  test.skip(process.env.APP_VERSION === 'v1', 'There are no settings in v1');  await page.goto('/settings');});

test.skip(callback, description)#

  • callback <function(Fixtures):boolean> A function that returns whether to skip, based on test fixtures. Test or tests are skipped when the return value is true.#
  • description <void|string> An optional description that will be reflected in a test report.#
  • returns: <void>#

Conditionally skips all tests in a file or test.describe(title, callback) group.

import { test, expect } from '@playwright/test';
test.skip(({ browserName }) => browserName === 'webkit');
test('skip in WebKit 1', async ({ page }) => {  // ...});test('skip in WebKit 2', async ({ page }) => {  // ...});

test.slow([condition, description])#

  • condition <void|boolean|function(Fixtures):boolean> Optional condition - either a boolean value, or a function that takes a fixtures object and returns a boolean. Test or tests are marked as "slow" when the condition is true.#
  • description <void|string> Optional description that will be reflected in a test report.#
  • returns: <void>#

Marks a test or a group of tests as "slow". Slow tests will be given triple the default timeout.

Unconditional slow:

import { test, expect } from '@playwright/test';
test('slow test', async ({ page }) => {  test.slow();  // ...});

Conditional slow a test with an optional description:

import { test, expect } from '@playwright/test';
test('slow in WebKit', async ({ page, browserName }) => {  test.slow(browserName === 'webkit', 'This feature is slow on Mac');  // ...});

Conditional slow for all tests in a file or test.describe(title, callback) group:

import { test, expect } from '@playwright/test';
test.slow(({ browserName }) => browserName === 'webkit');
test('slow in WebKit 1', async ({ page }) => {  // ...});test('fail in WebKit 2', async ({ page }) => {  // ...});

test.step(title, body)#

Declares a test step.

import { test, expect } from '@playwright/test';
test('test', async ({ page }) => {  await test.step('Log in', async () => {    // ...  });});

test.use(options)#

Specifies options or fixtures to use in a single test file or a test.describe(title, callback) group. Most useful to set an option, for example set locale to configure context fixture.

import { test, expect } from '@playwright/test';
test.use({ locale: 'en-US' });
test('test with locale', async ({ page }) => {  // Default context and page have locale as specified});

It is also possible to override a fixture by providing a function.

import { test, expect } from '@playwright/test';
test.use({  locale: async ({}, use) => {    // Read locale from some configuration file.    const locale = await fs.promises.readFile('test-locale', 'utf-8');    await use(locale);  },});
test('test with locale', async ({ page }) => {  // Default context and page have locale as specified});

test.expect#

expect function can be used to create test assertions. Read expect library documentation for more details.