test.setTimeout() for slow test
test('very slow test', async ({ page }) => { test.setTimeout(120000); // ... });
Playwright · Test runner API · all subjects
test
77 notes in this subject, read out of this brain and free to use. This is page 1 of 2.
Configure retries and timeout example
test.describe.configure({ retries: 2, timeout: 20_000 }); test('runs first', async ({ page }) => {}); test('runs second', async ({ page }) => {});
Parallel describes in order example
test.describe.configure({ mode: 'parallel' }); test.describe('A, runs in parallel with B', () => { test.describe.configure({ mode: 'default' }); test('in order A1', async ({ page }) => {}); test('in order A2', async ({ page }) => {}); }); test.describe('B, runs in parallel with A', () => { test.describe.configure({ mode: 'default' }); test('in order B1', async ({ page }) => {}); test('in order B2', async ({ page }) => {}); });
Fixme describe group example
test.describe.fixme('broken tests that should be fixed', () => { test('example', async ({ page }) => { // This test will not run }); });
test.describe() groups tests
test.describe() groups tests with optional title and details. Syntax: test.describe(title, callback), test.describe(callback), or test.describe(title, details, callback). Groups can have tags, annotations, and locks applied to all tests in the group. Anonymous groups (without title) are useful for applying common options via test.use(). The callback runs immediately and tests declared within belong to the group.
test.setTimeout() changes test timeout
test.setTimeout() changes the timeout for the currently running test. Takes timeout parameter in milliseconds; zero means no timeout. Can be called in test body, beforeEach (affects test timeout shared with hook), beforeAll/afterAll (affects hook timeout). Can also use test.describe.configure({ timeout }) for all tests in a group. Current test timeout available via TestInfo.timeout.
test() function declares a test
The test() function declares a test with a title and body function. It accepts two or three parameters: test(title, body) or test(title, details, body). The title is a string, details is optional and contains tag, annotation, and lock properties, and the body is a function that takes Fixtures and optional TestInfo.
Test tags syntax and usage
Test tags are declared either as part of the details object with tag property (string or array of strings) or included in the test title starting with @ symbol. Each tag must start with @ symbol. Tags are displayed in test reports and available via TestCase.tags property. Tests can be filtered by tags using command line, TestConfig.grep, or TestProject.grep.
Test annotations syntax and usage
Test annotations are declared in the details object with annotation property as an object or array of objects. Each annotation has a required type field (string) and optional description field (string). Annotations are displayed in the test report and available via TestCase.annotations property. Annotations can also be added at runtime via TestInfo.annotations.
Test locks prevent concurrent execution
Test locks are declared in the details object with lock property (string or array of strings). Tests that share a lock name never run concurrently, even across different files or projects. This is useful when tests access shared resources that do not support concurrent access.
test.afterEach() hook execution
test.afterEach() declares a hook executed after each test. When called at file scope, it runs after each test in the file; when inside test.describe(), it runs after each test in the group. The hook function receives the same Fixtures as tests and optional TestInfo. Multiple afterEach hooks run in registration order. Hooks can have optional titles (since v1.38). All hooks run even if some fail.
test.beforeAll() hook execution
test.beforeAll() declares a hook executed once per worker process before all tests. When called at file scope, it runs before all tests in the file; when inside test.describe(), it runs before all tests in the group. Use test.afterAll() to teardown resources. Multiple beforeAll hooks run in registration order. Hooks can have optional titles (since v1.38). Worker process restarts on test failures and beforeAll runs again in the new worker.
test.beforeEach() hook execution
test.beforeEach() declares a hook executed before each test. When called at file scope, it runs before each test in the file; when inside test.describe(), it runs before each test in the group. The hook function receives the same Fixtures as tests and optional TestInfo. Multiple beforeEach hooks run in registration order. Use test.afterEach() to teardown resources. All hooks run even if some fail.
Default mode example
test.describe.configure({ mode: 'default' }); test('runs first', async ({ page }) => {}); test('runs second', async ({ page }) => {});
test.describe.configure() execution modes
test.describe.configure() configures execution for a scope (file or describe group). Options: mode ('default', 'parallel', or 'serial'), retries (number), timeout (milliseconds). mode='default' runs tests in order with independent retries. mode='parallel' runs tests concurrently in separate processes. mode='serial' runs tests serially and skips remaining tests if one fails. Configuration applies regardless of declaration order.
test.describe.fixme() skips group
test.describe.fixme() declares a group of tests marked as 'fixme' that will not be executed. Syntax: test.describe.fixme(title, callback), test.describe.fixme(callback), or test.describe.fixme(title, details, callback). Tests in the group will not run. Can include tags and annotations in details.
test.describe.only() focuses group
test.describe.only() declares a focused group of tests. If there are focused tests or suites, only those run. Syntax: test.describe.only(title, callback), test.describe.only(callback), or test.describe.only(title, details, callback). Can include tags and annotations in details.
test.describe.parallel() marks group parallel
test.describe.parallel() declares a group of tests that run in parallel (discouraged; use test.describe.configure() instead). Syntax: test.describe.parallel(title, callback), test.describe.parallel(callback), or test.describe.parallel(title, details, callback). Parallel tests execute in separate processes and cannot share state. Each parallel test executes all relevant hooks.
test.describe.parallel.only() focuses parallel group
test.describe.parallel.only() declares a focused group that runs in parallel (discouraged; use test.describe.configure() instead). Syntax: test.describe.parallel.only(title, callback), test.describe.parallel.only(callback), or test.describe.parallel.only(title, details, callback). Only focused tests/suites run.
test.describe.serial() runs group serially
test.describe.serial() declares a group of tests that run serially (discouraged; use test.describe.configure() instead). Syntax: test.describe.serial(title, callback), test.describe.serial(title), or test.describe.serial(title, details, callback). If one test fails, subsequent tests are skipped. All tests in the group are retried together.
test.describe.serial.only() focuses serial group
test.describe.serial.only() declares a focused group that runs serially (discouraged; use test.describe.configure() instead). Syntax: test.describe.serial.only(title, callback), test.describe.serial.only(title), or test.describe.serial.only(title, details, callback). If one test fails, subsequent tests are skipped.
test.describe.skip() skips group
test.describe.skip() declares a skipped group of tests that will not be run. Syntax: test.describe.skip(title, callback), test.describe.skip(title), or test.describe.skip(title, details, callback). Tests in the skipped group are never executed.
test.expect property for assertions
test.expect is an object that can be used to create test assertions. It can be accessed as test.expect(value).toHaveTitle('Title') or similar assertion methods.
test.abort() fails test immediately
test.abort() aborts the currently running test by throwing an error. The test is immediately marked as failed and execution stops. Useful from fixtures or route handlers to fail tests on unrecoverable misuse. Accepts optional message parameter describing the reason for abort.
test.fail() marks test as should-fail
test.fail() marks a test or group as 'should fail'. Playwright runs the test and ensures it actually fails. Syntax: test.fail(title, body), test.fail(title, details, body), test.fail(condition, description), test.fail(callback, description), or test.fail(). Can be used at declaration time or runtime. Runtime usage: test.fail(browserName === 'webkit', 'description'). Callback form test.fail(callback, description) marks all tests in scope when condition is true.
test.fail.only() focuses failing test
test.fail.only() declares a focused test expected to fail. Syntax: test.fail.only(title, body) or test.fail.only(title, details, body). Playwright runs only this focused test and ensures it fails.
test.fixme() marks test to be fixed
test.fixme() marks a test or group as 'fixme'. Playwright will not run the test past the test.fixme() call. Syntax: test.fixme(title, body), test.fixme(title, details, body), test.fixme(condition, description), test.fixme(callback, description), or test.fixme(). Runtime usage: test.fixme(browserName === 'webkit', 'description'). Callback form test.fixme(callback, description) marks all tests in scope when condition is true. If used conditionally in test body, test runs but aborts immediately.
test.info() returns TestInfo
test.info() returns information about the currently running test as a TestInfo object. Can only be called during test execution; throws otherwise. Used to access test metadata like title, status, expectedStatus, timeout, and to attach files.
test.only() focuses single test
test.only() declares a focused test. If there are focused tests or suites, only those run. Syntax: test.only(title, body) or test.only(title, details, body). Title is required.
Serial mode example
test.describe.configure({ mode: 'serial' }); test('runs first', async ({ page }) => {}); test('runs second', async ({ page }) => {});
test.skip() skips test at runtime
test.skip() skips a test so Playwright will not run it past the test.skip() call. Syntax: test.skip(title, body), test.skip(title, details, body), test.skip(condition, description), test.skip(callback, description), or test.skip(). Skipped tests are not supposed to be run; use test.fixme() if you intend to fix. Runtime usage: test.skip(browserName !== 'webkit', 'description'). Callback form test.skip(callback, description) skips all tests in scope when condition is true.
test.slow() marks test as slow
test.slow() marks a test as 'slow', giving it triple the default timeout. Cannot be used in beforeAll or afterAll hooks; use test.setTimeout() instead. Syntax: test.slow(), test.slow(condition, description), or test.slow(callback, description). Runtime usage: test.slow(browserName === 'webkit', 'description'). Callback form test.slow(callback, description) marks all tests in scope when condition is true.
test.step() declares test step
test.step() declares a test step shown in the report. Returns the value returned by the step callback. Syntax: await test.step(title, body) or await test.step(title, body, options). Options: box (boolean, defaults to false), location (Location object), timeout (milliseconds, defaults to 0). When box=true, errors point to step call site rather than step internals. Steps can be nested.
test.step.skip() skips step
test.step.skip() marks a test step as 'skip' to disable its execution. Syntax: await test.step.skip(title, body) or await test.step.skip(title, body, options). Step will not be executed. Options: box (boolean), location (Location), timeout (milliseconds).
Basic test example
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 with tags example
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 with annotation example
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 with lock example
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. });
afterEach hook example
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 }) => { // ... });
beforeAll and afterAll hooks example
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 }) => { // ... });
beforeEach hook example
import { test, expect } from '@playwright/test'; test.beforeEach(async ({ page }) => { console.log(`Running ${test.info().title}`); await page.goto('https://my.start.url/'); }); test('my test', async ({ page }) => { expect(page.url()).toBe('https://my.start.url/'); });
describe group example
test.describe('two tests', () => { test('one', async ({ page }) => { // ... }); test('two', async ({ page }) => { // ... }); });
Anonymous describe group with test.use example
test.describe(() => { test.use({ colorScheme: 'dark' }); test('one', async ({ page }) => { // ... }); test('two', async ({ page }) => { // ... }); });
Tagged describe group example
import { test, expect } from '@playwright/test'; test.describe('two tagged tests', { tag: '@smoke', }, () => { test('one', async ({ page }) => { // ... }); test('two', async ({ page }) => { // ... }); });
Annotated describe group example
import { test, expect } from '@playwright/test'; test.describe('two annotated tests', { annotation: { type: 'issue', description: 'https://github.com/microsoft/playwright/issues/23180', }, }, () => { test('one', async ({ page }) => { // ... }); test('two', async ({ page }) => { // ... }); });
Describe group with lock example
import { test, expect } from '@playwright/test'; test.describe('two tests with a lock', { lock: 'user-settings', }, () => { test('one', async ({ page }) => { // ... }); test('two', async ({ page }) => { // ... }); });
Parallel mode example
test.describe.configure({ mode: 'parallel' }); test('runs in parallel 1', async ({ page }) => {}); test('runs in parallel 2', async ({ page }) => {});
Only describe group example
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 });
Parallel.only describe group example
test.describe.parallel.only('group', () => { test('runs in parallel 1', async ({ page }) => {}); test('runs in parallel 2', async ({ page }) => {}); });
Serial.only describe group example
test.describe.serial.only('group', () => { test('runs first', async ({ page }) => { }); test('runs second', async ({ page }) => { }); });
Skip describe group example
test.describe.skip('skipped group', () => { test('example', async ({ page }) => { // This test will not run }); });
test.expect usage example
test('example', async ({ page }) => { await test.expect(page).toHaveTitle('Title'); });
test.extend() usage in test
import { test } from './my-test'; test('test 1', async ({ todoPage }) => { await todoPage.addToDo('my todo'); // ... });
test.abort() example
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(); }); // ... });
test.fail() example at declaration
import { test, expect } from '@playwright/test'; test.fail('not yet ready', async ({ page }) => { // ... });
test.fail() with condition example
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() with callback example
import { test, expect } from '@playwright/test'; test.fail(({ browserName }) => browserName === 'webkit', 'not implemented yet'); test('fail in WebKit 1', async ({ page }) => { // ... }); test('fail in WebKit 2', async ({ page }) => { // ... });
test.fail.only() example
import { test, expect } from '@playwright/test'; test.fail.only('focused failing test', async ({ page }) => { // This test is expected to fail }); test('not in the focused group', async ({ page }) => { // This test will not run });
test.fixme() at declaration example
import { test, expect } from '@playwright/test'; test.fixme('to be fixed', async ({ page }) => { // ... });
test.fixme() with callback example
import { test, expect } from '@playwright/test'; test.fixme(({ browserName }) => browserName === 'webkit', 'Should figure out the issue'); test('to be fixed in Safari 1', async ({ page }) => { // ... }); test('to be fixed in Safari 2', async ({ page }) => { // ... });