Skip to main content

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)​

Added in: v1.10

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)​

Added in: v1.10

Declares an afterAll hook that is executed once per worker 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. If multiple afterAll hooks are added, they will run in the order of their registration.

Note that worker process is restarted on test failures, and afterAll hook runs again in the new worker. Learn more about workers and failures.

test.afterEach(hookFunction)​

Added in: v1.10

Declares an afterEach hook that is executed after each test. When called in the scope of a test file, runs after each test in the file. When called inside a test.describe(title, callback) group, runs after each test in the group. If multiple afterEach hooks are added, they will run in the order of their registration.

You can access all the same Fixtures as the test function itself, and also the TestInfo object that gives a lot of useful information. For example, you can check whether the test succeeded or failed.

// example.spec.ts
import { test, expect } from '@playwright/test';

test.afterEach(async ({ page }, testInfo) => {
  console.log(`Finished ${testInfo.title} with status ${testInfo.status}`);

  if (testInfo.status !== testInfo.expectedStatus)
    console.log(`Did not run as expected, ended up at ${page.url()}`);
});

test('my test', async ({ page }) => {
  // ...
});

test.beforeAll(hookFunction)​

Added in: v1.10

Declares a beforeAll hook that is executed once per worker process 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. If multiple beforeAll hooks are added, they will run in the order of their registration.

// example.spec.ts
import { test, expect } from '@playwright/test';

test.beforeAll(async () => {
  console.log('Before tests');
});

test.afterAll(async () => {
  console.log('After tests');
});

test('my test', async ({ page }) => {
  // ...
});

Note that worker process is restarted on test failures, and beforeAll hook runs again in the new worker. Learn more about workers and failures.

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

test.beforeEach(hookFunction)​

Added in: v1.10

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. If multiple beforeEach hooks are added, they will run in the order of their registration.

You can access all the same Fixtures as the test function itself, and also the TestInfo object that gives a lot of useful information. For example, you can navigate the page before starting the test.

// example.spec.ts
import { test, expect } from '@playwright/test';

test.beforeEach(async ({ page }, testInfo) => {
  console.log(`Running ${testInfo.title}`);
  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)​

Added in: v1.10

Declares a group of tests.

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

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

test.describe(callback)​

Added in: v1.24

Declares an anonymous group of tests. This is convenient to give a group of tests a common option with test.use(options).

test.describe(() => {
  test.use({ colorScheme: 'dark' });

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

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

test.describe.configure([options])​

Added in: v1.10
  • options? <Object>
    • mode? <"parallel"|"serial">#
  • returns: <void>#

Set execution mode of execution for the enclosing scope. Can be executed either on the top level or inside a describe. Configuration applies to the entire scope, regardless of whether it run before or after the test declaration.

Learn more about the execution modes here.

Running tests in parallel:

// Run all the tests in the file concurrently using parallel workers.
test.describe.configure({ mode: 'parallel' });
test('runs in parallel 1', async ({ page }) => {});
test('runs in parallel 2', async ({ page }) => {});

Running tests sequentially:

// Annotate tests as inter-dependent.
test.describe.configure({ mode: 'serial' });
test('runs first', async ({ page }) => {});
test('runs second', async ({ page }) => {});

test.describe.fixme(title, callback)​

Added in: v1.25

Declares a test group similarly to test.describe(title, callback). Tests in this group are marked as "fixme" and will not be executed.

test.describe.fixme('broken tests', () => {
  test('example', async ({ page }) => {
    // This test will not run
  });
});

test.describe.only(title, callback)​

Added in: v1.10

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)​

Added in: v1.10

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.

note

See test.describe.configure([options]) for the preferred way of configuring the execution mode.

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)​

Added in: v1.10

Declares a focused group of tests that could be run in parallel. This is similar to test.describe.parallel(title, callback), but focuses the group. If there are some focused tests or suites, all of them will be run but nothing else.

test.describe.serial(title, callback)​

Added in: v1.10

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

See test.describe.configure([options]) for the preferred way of configuring the execution mode.

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)​

Added in: v1.10

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.describe.skip(title, callback)​

Added in: v1.10

Declares a skipped test group, similarly to test.describe(title, callback). Tests in the skipped group are never run.

test.describe.skip('skipped group', () => {
  test('example', async ({ page }) => {
    // This test will not run
  });
});

test.extend(fixtures)​

Added in: v1.10

Extends the test object by defining fixtures and/or options that can be used in the tests.

First define a fixture and/or an option.

import { test as base } from '@playwright/test';
import { TodoPage } from './todo-page';

export type Options = { defaultItem: string };

// Extend basic test by providing a "defaultItem" option and a "todoPage" fixture.
export const test = base.extend<Options & { todoPage: TodoPage }>({
  // Define an option and provide a default value.
  // We can later override it in the config.
  defaultItem: ['Do stuff', { option: true }],

  // Define a fixture. Note that it can use built-in fixture "page"
  // and a new option "defaultItem".
  todoPage: async ({ page, defaultItem }, use) => {
    const todoPage = new TodoPage(page);
    await todoPage.goto();
    await todoPage.addToDo(defaultItem);
    await use(todoPage);
    await todoPage.removeAll();
  },
});

Then use the fixture in the test.

// example.spec.ts
import { test } from './my-test';

test('test 1', async ({ todoPage }) => {
  await todoPage.addToDo('my todo');
  // ...
});

Configure the option in config file.

// playwright.config.ts
import type { PlaywrightTestConfig } from '@playwright/test';
import { Options } from './my-test';

const config: PlaywrightTestConfig<Options> = {
  projects: [
    {
      name: 'shopping',
      use: { defaultItem: 'Buy milk' },
    },
    {
      name: 'wellbeing',
      use: { defaultItem: 'Exercise!' },
    },
  ]
};
export default config;

Learn more about fixtures and parametrizing tests.

test.fail()​

Added in: v1.10

Unconditonally marks a test as "should fail". Playwright Test runs this test and ensures that it is actually failing. This is useful for documentation purposes to acknowledge that some functionality is broken until it is fixed.

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

test('not yet ready', async ({ page }) => {
  test.fail();
  // ...
});

test.fail(condition[, description])​

Added in: v1.10
  • condition <boolean> Test is marked as "should fail" when the condition is true.#
  • description? <string> Optional description that will be reflected in a test report.#
  • returns: <void>#

Conditionally mark a test as "should fail" 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');
  // ...
});

test.fail(callback[, description])​

Added in: v1.10
  • callback <function(Fixtures):boolean> A function that returns whether to mark as "should fail", based on test fixtures. Test or tests are marked as "should fail" when the return value is true.#
  • description? <string> Optional description that will be reflected in a test report.#
  • returns: <void>#

Conditionally mark all tests in a file or test.describe(title, callback) group as "should fail".

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(title, testFunction)​

Added in: v1.10

Declares a test to be fixed, similarly to test(title, testFunction). This test will not be run.

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

test.fixme('test to be fixed', async ({ page }) => {
  // ...
});

test.fixme()​

Added in: v1.10

Mark a test as "fixme", with the intention to fix it. Test is immediately aborted when you call test.fixme().

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

test('test to be fixed', async ({ page }) => {
  test.fixme();
  // ...
});

Mark all tests in a file or test.describe(title, callback) group as "fixme".

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

test.fixme();

test('test to be fixed 1', async ({ page }) => {
  // ...
});
test('test to be fixed 2', async ({ page }) => {
  // ...
});

test.fixme(condition[, description])​

Added in: v1.10
  • condition <boolean> Test is marked as "fixme" when the condition is true.#
  • description? <string> Optional description that will be reflected in a test report.#
  • returns: <void>#

Conditionally mark a test as "fixme" with an optional description.

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

test('broken in WebKit', async ({ page, browserName }) => {
  test.fixme(browserName === 'webkit', 'This feature is not implemented on Mac yet');
  // ...
});

test.fixme(callback[, description])​

Added in: v1.10
  • callback <function(Fixtures):boolean> A function that returns whether to mark as "fixme", based on test fixtures. Test or tests are marked as "fixme" when the return value is true.#
  • description? <string> Optional description that will be reflected in a test report.#
  • returns: <void>#

Conditionally mark all tests in a file or test.describe(title, callback) group as "fixme".

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

test.fixme(({ browserName }) => browserName === 'webkit');

test('broken in WebKit 1', async ({ page }) => {
  // ...
});
test('broken in WebKit 2', async ({ page }) => {
  // ...
});

test.info()​

Added in: v1.10

Returns information about the currently running test. This method can only be called during the test execution, otherwise it throws.

test.only(title, testFunction)​

Added in: v1.10

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)​

Added in: v1.10

Changes the timeout for the test. Zero means no timeout. Learn more about various timeouts.

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

test('very slow test', async ({ page }) => {
  test.setTimeout(120000);
  // ...
});

Changing timeout from a slow beforeEach or afterEach hook. Note that this affects the test timeout that is shared with beforeEach/afterEach hooks.

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

Changing timeout for a beforeAll or afterAll hook. Note this affects the hook's timeout, not the test timeout.

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

test.beforeAll(async () => {
  // Set timeout for this hook.
  test.setTimeout(60000);
});

Changing timeout for all tests in a test.describe(title, callback) group.

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

test.describe('group', () => {
  // Applies to all tests in this group.
  test.setTimeout(60000);

  test('test one', async () => { /* ... */ });
  test('test two', async () => { /* ... */ });
  test('test three', async () => { /* ... */ });
});

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

test.skip(title, testFunction)​

Added in: v1.10

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()​

Added in: v1.10

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])​

Added in: v1.10
  • condition <boolean> A skip condition. Test is skipped when the condition is true.#
  • description? <void|string> 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])​

Added in: v1.10
  • 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? <string> 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()​

Added in: v1.10

Unconditionally marks a test as "slow". Slow test will be given triple the default timeout.

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

test('slow test', async ({ page }) => {
  test.slow();
  // ...
});
note

test.slow() cannot be used in a beforeAll or afterAll hook. Use test.setTimeout(timeout) instead.

test.slow(condition[, description])​

Added in: v1.10
  • condition <boolean> Test is marked as "slow" when the condition is true.#
  • description? <string> Optional description that will be reflected in a test report.#
  • returns: <void>#

Conditionally mark a test as "slow" with an optional description. Slow test will be given triple the default timeout.

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

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

test.slow(callback[, description])​

Added in: v1.10
  • callback <function(Fixtures):boolean> A function that returns whether to mark as "slow", based on test fixtures. Test or tests are marked as "slow" when the return value is true.#
  • description? <string> Optional description that will be reflected in a test report.#
  • returns: <void>#

Conditionally mark all tests in a file or test.describe(title, callback) group as "slow". Slow tests will be given triple the default timeout.

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)​

Added in: v1.10

Declares a test step.

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

test('test', async ({ page }) => {
  await test.step('Log in', async () => {
    // ...
  });
});

The method returns value retuned by the step callback.

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

test('test', async ({ page }) => {
  const user = await test.step('Log in', async () => {
    // ...
    return 'john';
  });
  expect(user).toBe('john');
});

test.use(options)​

Added in: v1.10

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. test.use can be called either in the global scope or inside test.describe, it's is an error to call it within beforeEach or beforeAll.

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​

Added in: v1.10

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