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');
});
Methods
test
Added in: v1.10Declares a test.
test(title, body)test(title, details, body)
Usage
import { test, expect } from '@playwright/test';
test('basic test', async ({ page }) => {
await page.goto('https://playwright.dev/');
// ...
});
Tags
You can tag tests by providing additional test details. Alternatively, you can include tags in the test title. Note that each tag must start with @ symbol.
import { test, expect } from '@playwright/test';
test('basic test', {
tag: '@smoke',
}, async ({ page }) => {
await page.goto('https://playwright.dev/');
// ...
});
test('another test @smoke', async ({ page }) => {
await page.goto('https://playwright.dev/');
// ...
});
Test tags are displayed in the test report, and are available to a custom reporter via TestCase.tags property.
You can also filter tests by their tags during test execution:
- in the command line;
- in the config with testConfig.grep and testProject.grep;
Learn more about tagging.
Annotations
You can annotate tests by providing additional test details.
import { test, expect } from '@playwright/test';
test('basic test', {
annotation: {
type: 'issue',
description: 'https://github.com/microsoft/playwright/issues/23180',
},
}, async ({ page }) => {
await page.goto('https://playwright.dev/');
// ...
});
Test annotations are displayed in the test report, and are available to a custom reporter via TestCase.annotations property.
You can also add annotations during runtime by manipulating testInfo.annotations.
Learn more about test annotations.
Locks
You can declare named locks to prevent specific tests from running at the same time, while all other tests continue to run in parallel. Tests that share a lock name never run concurrently, even when they are declared in different files or belong to different projects. This is useful when a few tests access a shared resource that does not support concurrent access.
import { test, expect } from '@playwright/test';
test('update user settings', {
lock: 'user-settings',
}, async ({ page }) => {
// This test never runs concurrently with other tests
// that declare the 'user-settings' lock.
});
The built-in -exclusive- lock runs the test only when no other tests are running.
Learn more about test locks.
Arguments
-
Test title.
-
detailsObject (optional) Added in: v1.42#Additional test details.
-
bodyfunction(Fixtures, TestInfo)#Test body that takes one or two arguments: an object with fixtures and optional TestInfo.
test.abort
Added in: v1.60Aborts the currently running test by throwing an error. The test is immediately marked as failed and execution stops. This is useful from inside a fixture or a route handler when you have detected an unrecoverable misuse and want to fail the test right away.
Usage
import { test, expect } from '@playwright/test';
test('does not publish to shared page', async ({ page }) => {
await page.route('**/publish', route => {
test.abort('Tests must not publish to the shared page. Use the `clone` option.');
return route.abort();
});
// ...
});
Arguments
-
Optional message describing the reason for the abort. It will be included in the failure error.
test.afterAll
Added in: v1.10Declares 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() group, runs after all tests in the group.
Usage
test.afterAll(async () => {
console.log('Done with tests');
// ...
});
Alternatively, you can declare a hook with a title.
test.afterAll('Teardown', async () => {
console.log('Done with tests');
// ...
});
Arguments
-
titlestring (optional) Added in: v1.38#Hook title.
-
hookFunctionfunction(Fixtures, TestInfo)#Hook function that takes one or two arguments: an object with worker fixtures and optional TestInfo.
Details
When 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.
Playwright will continue running all applicable hooks even if some of them have failed.
test.afterAll(hookFunction)test.afterAll(title, hookFunction)
test.afterEach
Added in: v1.10Declares 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() group, runs after each test in the group.
You can access all the same Fixtures as the test body itself, and also the TestInfo object that gives a lot of useful information. For example, you can check whether the test succeeded or failed.
test.afterEach(hookFunction)test.afterEach(title, hookFunction)
Usage
import { test, expect } from '@playwright/test';
test.afterEach(async ({ page }) => {
console.log(`Finished ${test.info().title} with status ${test.info().status}`);
if (test.info().status !== test.info().expectedStatus)
console.log(`Did not run as expected, ended up at ${page.url()}`);
});
test('my test', async ({ page }) => {
// ...
});
Alternatively, you can declare a hook with a title.
test.afterEach('Status check', async ({ page }) => {
if (test.info().status !== test.info().expectedStatus)
console.log(`Did not run as expected, ended up at ${page.url()}`);
});
Arguments
-
titlestring (optional) Added in: v1.38#Hook title.
-
hookFunctionfunction(Fixtures, TestInfo)#Hook function that takes one or two arguments: an object with fixtures and optional TestInfo.
Details
When multiple afterEach hooks are added, they will run in the order of their registration.
Playwright will continue running all applicable hooks even if some of them have failed.
test.beforeAll
Added in: v1.10Declares 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() group, runs before all tests in the group.
You can use test.afterAll() to teardown any resources set up in beforeAll.
test.beforeAll(hookFunction)test.beforeAll(title, hookFunction)
Usage
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 }) => {
// ...
});
Alternatively, you can declare a hook with a title.
test.beforeAll('Setup', async () => {
console.log('Before tests');
});
Arguments
-
titlestring (optional) Added in: v1.38#Hook title.
-
hookFunctionfunction(Fixtures, TestInfo)#Hook function that takes one or two arguments: an object with worker fixtures and optional TestInfo.
Details
When multiple beforeAll hooks are added, they will run in the order of their registration.
Note that worker process is restarted on test failures, and beforeAll hook runs again in the new worker. Learn more about workers and failures.
Playwright will continue running all applicable hooks even if some of them have failed.
test.beforeEach
Added in: v1.10Declares 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