externalit
Callable
Parameters
externaltitle: string
externalbody: (args: PlaywrightTestArgs & PlaywrightTestOptions & Omit<SerenityOptions, actors> & SerenityFixtures & PlaywrightWorkerArgs & PlaywrightWorkerOptions & object, testInfo: TestInfo) => void | Promise<void>
Returns void
Index
Properties
externalonly
Declares a focused test. If there are some focused tests or suites, all of them will be run but nothing else.
test.only(title, body)
test.only(title, details, body)
Usage
test.only('focus this test', async ({ page }) => {
// Run only focused tests in the entire project.
});
externaldescribe
Declares a group of tests.
test.describe(title, callback)
test.describe(callback)
test.describe(title, details, callback)
Usage
You can declare a group of tests with a title. The title will be visible in the test report as a part of each test's title.
test.describe('two tests', () => {
test('one', async ({ page }) => {
// ...
});
test('two', async ({ page }) => {
// ...
});
});
Anonymous group
You can also declare a test group without a title. 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 }) => {
// ...
});
});
Tags
You can tag all tests in a group by providing additional details. Note that each tag must start with @
symbol.
import { test, expect } from '@playwright/test';
test.describe('two tagged tests', {
tag: '@smoke',
}, () => {
test('one', async ({ page }) => {
// ...
});
test('two', async ({ page }) => {
// ...
});
});
Learn more about tagging.
Annotations
You can annotate all tests in a group by providing additional details.
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 }) => {
// ...
});
});
Learn more about test annotations.
externalexpect
expect
function can be used to create test assertions. Read more about test assertions.
Usage
test('example', async ({ page }) => {
await test.expect(page).toHaveTitle('Title');
});
Methods
externalskip
Skip a test. Playwright will not run the test past the
test.skip()
call.Skipped tests are not supposed to be ever run. If you intent to fix the test, use test.fixme([title, details, body, condition, callback, description]) instead.
To declare a skipped test:
test.skip(title, body)
test.skip(title, details, body)
To skip a test at runtime:
test.skip(condition, description)
test.skip(callback, description)
test.skip()
Usage
You can declare a skipped test, and Playwright will not run it.
import { test, expect } from '@playwright/test';
test.skip('never run', async ({ page }) => {
// ...
});If your test should be skipped in some configurations, but not all, you can skip the test inside the test body based on some condition. We recommend passing a
description
argument in this case. Playwright will run the test, but abort it immediately after thetest.skip
call.import { test, expect } from '@playwright/test';
test('Safari-only test', async ({ page, browserName }) => {
test.skip(browserName !== 'webkit', 'This feature is Safari-only');
// ...
});You can skip all tests in a file or test.describe([title, details, callback]) group based on some condition with a single
test.skip(callback, description)
call.import { test, expect } from '@playwright/test';
test.skip(({ browserName }) => browserName !== 'webkit', 'Safari-only');
test('Safari-only test 1', async ({ page }) => {
// ...
});
test('Safari-only test 2', async ({ page }) => {
// ...
});You can also call
test.skip()
without arguments inside the test body to always mark the test as failed. We recommend usingtest.skip(title, body)
instead.import { test, expect } from '@playwright/test';
test('less readable', async ({ page }) => {
test.skip();
// ...
});Parameters
externaltitle: string
Test title.
externalbody: (args: PlaywrightTestArgs & PlaywrightTestOptions & Omit<SerenityOptions, actors> & SerenityFixtures & PlaywrightWorkerArgs & PlaywrightWorkerOptions & object, testInfo: TestInfo) => void | Promise<void>
Test body that takes one or two arguments: an object with fixtures and optional TestInfo.
Returns void
externalfixme
Mark a test as "fixme", with the intention to fix it. Playwright will not run the test past the
test.fixme()
call.To declare a "fixme" test:
test.fixme(title, body)
test.fixme(title, details, body)
To annotate test as "fixme" at runtime:
test.fixme(condition, description)
test.fixme(callback, description)
test.fixme()
Usage
You can declare a test as to be fixed, and Playwright will not run it.
import { test, expect } from '@playwright/test';
test.fixme('to be fixed', async ({ page }) => {
// ...
});If your test should be fixed in some configurations, but not all, you can mark the test as "fixme" inside the test body based on some condition. We recommend passing a
description
argument in this case. Playwright will run the test, but abort it immediately after thetest.fixme
call.import { test, expect } from '@playwright/test';
test('to be fixed in Safari', async ({ page, browserName }) => {
test.fixme(browserName === 'webkit', 'This feature breaks in Safari for some reason');
// ...
});You can mark all tests in a file or test.describe([title, details, callback]) group as "fixme" based on some condition with a single
test.fixme(callback, description)
call.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 }) => {
// ...
});You can also call
test.fixme()
without arguments inside the test body to always mark the test as failed. We recommend usingtest.fixme(title, body)
instead.import { test, expect } from '@playwright/test';
test('less readable', async ({ page }) => {
test.fixme();
// ...
});Parameters
externaltitle: string
Test title.
externalbody: (args: PlaywrightTestArgs & PlaywrightTestOptions & Omit<SerenityOptions, actors> & SerenityFixtures & PlaywrightWorkerArgs & PlaywrightWorkerOptions & object, testInfo: TestInfo) => void | Promise<void>
Test body that takes one or two arguments: an object with fixtures and optional TestInfo.
Returns void
externalfail
Marks a test as "should fail". Playwright 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.
To declare a "failing" test:
test.fail(title, body)
test.fail(title, details, body)
To annotate test as "failing" at runtime:
test.fail(condition, description)
test.fail(callback, description)
test.fail()
Usage
You can declare a test as failing, so that Playwright ensures it actually fails.
import { test, expect } from '@playwright/test';
test.fail('not yet ready', async ({ page }) => {
// ...
});If your test fails in some configurations, but not all, you can mark the test as failing inside the test body based on some condition. We recommend passing a
description
argument in this case.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');
// ...
});You can mark all tests in a file or test.describe([title, details, callback]) group as "should fail" based on some condition with a single
test.fail(callback, description)
call.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 }) => {
// ...
});You can also call
test.fail()
without arguments inside the test body to always mark the test as failed. We recommend declaring a failing test withtest.fail(title, body)
instead.import { test, expect } from '@playwright/test';
test('less readable', async ({ page }) => {
test.fail();
// ...
});Parameters
externaltitle: string
Test title.
externalbody: (args: PlaywrightTestArgs & PlaywrightTestOptions & Omit<SerenityOptions, actors> & SerenityFixtures & PlaywrightWorkerArgs & PlaywrightWorkerOptions & object, testInfo: TestInfo) => void | Promise<void>
Test body that takes one or two arguments: an object with fixtures and optional TestInfo.
Returns void
externalslow
Marks a test as "slow". Slow test will be given triple the default timeout.
Note that test.slow([condition, callback, description]) cannot be used in a
beforeAll
orafterAll
hook. Use test.setTimeout(timeout) instead.test.slow()
test.slow(condition, description)
test.slow(callback, description)
Usage
You can mark a test as slow by calling
test.slow()
inside the test body.import { test, expect } from '@playwright/test';
test('slow test', async ({ page }) => {
test.slow();
// ...
});If your test is slow in some configurations, but not all, you can mark it as slow based on a condition. We recommend passing a
description
argument in this case.import { test, expect } from '@playwright/test';
test('slow in Safari', async ({ page, browserName }) => {
test.slow(browserName === 'webkit', 'This feature is slow in Safari');
// ...
});You can mark all tests in a file or test.describe([title, details, callback]) group as "slow" based on some condition by passing a callback.
import { test, expect } from '@playwright/test';
test.slow(({ browserName }) => browserName === 'webkit', 'all tests are slow in Safari');
test('slow in Safari 1', async ({ page }) => {
// ...
});
test('fail in Safari 2', async ({ page }) => {
// ...
});Returns void
externalsetTimeout
Changes the timeout for the test. Zero means no timeout. Learn more about various timeouts.
Timeout for the currently running test is available through testInfo.timeout.
Usage
- Changing test timeout.
test('very slow test', async ({ page }) => {
test.setTimeout(120000);
// ...
}); - Changing timeout from a slow
beforeEach
orafterEach
hook. Note that this affects the test timeout that is shared withbeforeEach
/afterEach
hooks.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
orafterAll
hook. Note this affects the hook's timeout, not the test timeout.test.beforeAll(async () => {
// Set timeout for this hook.
test.setTimeout(60000);
}); - Changing timeout for all tests in a
test.describe([title, details, callback]) group.
test.describe('group', () => {
// Applies to all tests in this group.
test.describe.configure({ timeout: 60000 });
test('test one', async () => { /* ... */ });
test('test two', async () => { /* ... */ });
test('test three', async () => { /* ... */ });
});
Parameters
externaltimeout: number
Timeout in milliseconds.
Returns void
- Changing test timeout.
externalbeforeEach
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, details, callback]) group, runs before 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 navigate the page before starting the test.
You can use test.afterEach([title, hookFunction]) to teardown any resources set up in
beforeEach
.test.beforeEach(hookFunction)
test.beforeEach(title, hookFunction)
Details
When multiple
beforeEach
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.
Usage
// example.spec.ts
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/');
});Alternatively, you can declare a hook with a title.
// example.spec.ts
test.beforeEach('Open start URL', async ({ page }) => {
console.log(`Running ${test.info().title}`);
await page.goto('https://my.start.url/');
});Parameters
externalinner: (args: PlaywrightTestArgs & PlaywrightTestOptions & Omit<SerenityOptions, actors> & SerenityFixtures & PlaywrightWorkerArgs & PlaywrightWorkerOptions & object, testInfo: TestInfo) => any
Returns void
externalafterEach
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, details, callback]) 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)
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.
Usage
// example.spec.ts
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.
// example.spec.ts
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()}`);
});Parameters
externalinner: (args: PlaywrightTestArgs & PlaywrightTestOptions & Omit<SerenityOptions, actors> & SerenityFixtures & PlaywrightWorkerArgs & PlaywrightWorkerOptions & object, testInfo: TestInfo) => any
Returns void
externalbeforeAll
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, details, callback]) group, runs before all tests in the group.
You can use test.afterAll([title, hookFunction]) to teardown any resources set up in
beforeAll
.test.beforeAll(hookFunction)
test.beforeAll(title, hookFunction)
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.
Usage
// 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 }) => {
// ...
});Alternatively, you can declare a hook with a title.
// example.spec.ts
test.beforeAll('Setup', async () => {
console.log('Before tests');
});Parameters
externalinner: (args: PlaywrightTestArgs & PlaywrightTestOptions & Omit<SerenityOptions, actors> & SerenityFixtures & PlaywrightWorkerArgs & PlaywrightWorkerOptions & object, testInfo: TestInfo) => any
Returns void
externalafterAll
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, details, callback]) group, runs after all tests in the group.
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)
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');
// ...
});Parameters
externalinner: (args: PlaywrightTestArgs & PlaywrightTestOptions & Omit<SerenityOptions, actors> & SerenityFixtures & PlaywrightWorkerArgs & PlaywrightWorkerOptions & object, testInfo: TestInfo) => any
Returns void
externaluse
Specifies options or fixtures to use in a single test file or a test.describe([title, details, callback]) group. Most useful to set an option, for example set
locale
to configurecontext
fixture.Usage
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
});Details
test.use
can be called either in the global scope or insidetest.describe
. It is an error to call it withinbeforeEach
orbeforeAll
.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
});Parameters
externalfixtures: Fixtures<{}, {}, PlaywrightTestArgs & PlaywrightTestOptions & Omit<SerenityOptions, actors> & SerenityFixtures, PlaywrightWorkerArgs & PlaywrightWorkerOptions & object>
Returns void
externalstep
Declares a test step that is shown in the report.
Usage
import { test, expect } from '@playwright/test';
test('test', async ({ page }) => {
await test.step('Log in', async () => {
// ...
});
await test.step('Outer step', async () => {
// ...
// You can nest steps inside each other.
await test.step('Inner step', async () => {
// ...
});
});
});Details
The method returns the value returned 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');
});Decorator
You can use TypeScript method decorators to turn a method into a step. Each call to the decorated method will show up as a step in the report.
function step(target: Function, context: ClassMethodDecoratorContext) {
return function replacementMethod(...args: any) {
const name = this.constructor.name + '.' + (context.name as string);
return test.step(name, async () => {
return await target.call(this, ...args);
});
};
}
class LoginPage {
constructor(readonly page: Page) {}
@step
async login() {
const account = { username: 'Alice', password: 's3cr3t' };
await this.page.getByLabel('Username or email address').fill(account.username);
await this.page.getByLabel('Password').fill(account.password);
await this.page.getByRole('button', { name: 'Sign in' }).click();
await expect(this.page.getByRole('button', { name: 'View profile and more' })).toBeVisible();
}
}
test('example', async ({ page }) => {
const loginPage = new LoginPage(page);
await loginPage.login();
});Boxing
When something inside a step fails, you would usually see the error pointing to the exact action that failed. For example, consider the following login step:
async function login(page) {
await test.step('login', async () => {
const account = { username: 'Alice', password: 's3cr3t' };
await page.getByLabel('Username or email address').fill(account.username);
await page.getByLabel('Password').fill(account.password);
await page.getByRole('button', { name: 'Sign in' }).click();
await expect(page.getByRole('button', { name: 'View profile and more' })).toBeVisible();
});
}
test('example', async ({ page }) => {
await page.goto('https://github.com/login');
await login(page);
});Error: Timed out 5000ms waiting for expect(locator).toBeVisible()
... error details omitted ...
8 | await page.getByRole('button', { name: 'Sign in' }).click();
> 9 | await expect(page.getByRole('button', { name: 'View profile and more' })).toBeVisible();
| ^
10 | });As we see above, the test may fail with an error pointing inside the step. If you would like the error to highlight the "login" step instead of its internals, use the
box
option. An error inside a boxed step points to the step call site.async function login(page) {
await test.step('login', async () => {
// ...
}, { box: true }); // Note the "box" option here.
}Error: Timed out 5000ms waiting for expect(locator).toBeVisible()
... error details omitted ...
14 | await page.goto('https://github.com/login');
> 15 | await login(page);
| ^
16 | });You can also create a TypeScript decorator for a boxed step, similar to a regular step decorator above:
function boxedStep(target: Function, context: ClassMethodDecoratorContext) {
return function replacementMethod(...args: any) {
const name = this.constructor.name + '.' + (context.name as string);
return test.step(name, async () => {
return await target.call(this, ...args);
}, { box: true }); // Note the "box" option here.
};
}
class LoginPage {
constructor(readonly page: Page) {}
@boxedStep
async login() {
// ....
}
}
test('example', async ({ page }) => {
const loginPage = new LoginPage(page);
await loginPage.login(); // <-- Error will be reported on this line.
});Type parameters
- T
Parameters
externaltitle: string
Step name.
externalbody: () => T | Promise<T>
Step body.
externaloptionaloptions: { box?: boolean; location?: Location }
externaloptionalbox: boolean
externaloptionallocation: Location
Returns Promise<T>
externalextend
Extends the
test
object by defining fixtures and/or options that can be used in the tests.Usage
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 { defineConfig } from '@playwright/test';
import type { Options } from './my-test';
export default defineConfig<Options>({
projects: [
{
name: 'shopping',
use: { defaultItem: 'Buy milk' },
},
{
name: 'wellbeing',
use: { defaultItem: 'Exercise!' },
},
]
});Learn more about fixtures and parametrizing tests.
Type parameters
- T: KeyValue
- W: KeyValue = {}
Parameters
externalfixtures: Fixtures<T, W, PlaywrightTestArgs & PlaywrightTestOptions & Omit<SerenityOptions, actors> & SerenityFixtures, PlaywrightWorkerArgs & PlaywrightWorkerOptions & object>
An object containing fixtures and/or options. Learn more about fixtures format.
Returns TestType<PlaywrightTestArgs & PlaywrightTestOptions & Omit<SerenityOptions, actors> & SerenityFixtures & T, PlaywrightWorkerArgs & PlaywrightWorkerOptions & object & W>
externalinfo
Returns information about the currently running test. This method can only be called during the test execution, otherwise it throws.
Usage
test('example test', async ({ page }) => {
// ...
await test.info().attach('screenshot', {
body: await page.screenshot(),
contentType: 'image/png',
});
});Returns TestInfo
Declares a single test scenario.
Example
Learn more
SerenityFixtures
test
function