test organization and control

28 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

test.abort for failing tests immediately

The `test.abort(message)` method aborts the currently running test by throwing an error. The test is immediately marked as failed and execution stops. Takes optional `message` parameter describing the reason for abort, which is included in the failure error. Useful from inside a fixture or route handler when an unrecoverable misuse is detected.

Basic test declaration syntax

Tests are declared using the `test()` function imported from '@playwright/test'. The function takes a test title (string) and an async body function that receives fixtures as parameters. Example: `test('basic test', async ({ page }) => { await page.goto('https://playwright.dev/'); });`

Test tagging with @symbol

Tests can be tagged by passing a `tag` property in the details object or by including tags directly in the test title. Each tag must start with the `@` symbol. Tags are displayed in the test report and accessible via `TestCase.tags` property. Tags can be used to filter tests during execution via command line, config with `TestConfig.grep`, or `TestProject.grep`.

Test annotations

Tests can be annotated by providing an `annotation` property in the details object with `type` (required string) and optional `description` fields. Annotations are displayed in test reports and accessible via `TestCase.annotations` property. Annotations can also be added at runtime by manipulating `TestInfo.annotations`.

Test locks for serial execution

Tests can declare named locks using the `lock` property (string or array of strings) to prevent specific tests from running concurrently. Tests that share a lock name never run concurrently, even when in different files or projects. This is useful when tests access a shared resource that does not support concurrent access.

Test describe groups

Tests can be grouped using `test.describe(title, callback)` where the title will appear in test reports as part of each test's title. Groups can also be declared without a title using `test.describe(callback)`. Groups can have tags, annotations, and locks applied to all tests within them.

Anonymous describe groups

Test groups can be declared without a title using `test.describe(callback)`. This is convenient for giving a group of tests common options with `test.use()`.

Test execution modes with describe.configure

The `test.describe.configure()` method configures execution mode for a scope. The `mode` option accepts 'parallel', 'default', or 'serial'. 'parallel' runs tests concurrently using parallel workers. 'default' (the default) runs tests in order with retries run independently. 'serial' runs tests serially and if one fails, subsequent tests are skipped. All tests in a group are retried together in serial mode. Configuration applies to the entire scope regardless of declaration order. This is the preferred way to configure execution modes.

describe.configure retries and timeout options

The `test.describe.configure()` method accepts `retries` (int) for the number of retries per test and `timeout` (int in milliseconds) for timeout per test. These override `TestProject.timeout` and `TestConfig.timeout`.

describe.skip for skipped test groups

The `test.describe.skip()` method declares a group of tests that will not be executed. Tests in skipped groups are never run. Can be called with or without a title.

describe.fixme for broken test groups

The `test.describe.fixme()` method declares a group of tests that are marked as 'fixme' and will not be executed. Tests in fixme groups are not run. Can be called with or without a title.

describe.only for focused test groups

The `test.describe.only()` method declares a focused group of tests. If there are any focused tests or groups, all focused ones will run but nothing else.

describe.parallel for concurrent tests (discouraged)

The `test.describe.parallel()` method is discouraged. Use `test.describe.configure({ mode: 'parallel' })` instead. It declares a group of tests that run in parallel. Parallel tests execute in separate processes and cannot share state or global variables. Each parallel test executes all relevant hooks.

describe.serial for sequential tests (discouraged)

The `test.describe.serial()` method is discouraged. Use `test.describe.configure({ mode: 'serial' })` instead. It declares a group of tests that run serially. If one serial test fails, all subsequent tests are skipped. All tests in a group are retried together. Serial execution is not recommended as isolated tests are usually better.

test.fail for marking tests as should fail

The `test.fail()` method marks a test as 'should fail'. Playwright ensures the test actually fails. Can be declared as `test.fail(title, body)`, `test.fail(title, details, body)`, or called at runtime as `test.fail(condition, description)` or `test.fail(callback, description)` or `test.fail()` without arguments.

test.fail.only for focused failing tests

The `test.fail.only()` method declares a focused test that is expected to fail. It runs only this test and ensures it actually fails. Can be called as `test.fail.only(title, body)` or `test.fail.only(title, details, body)`.

test.fixme for marking tests to be fixed

The `test.fixme()` method marks a test as 'fixme' with intention to fix it. Playwright will not run the test past the fixme() call. Can be declared as `test.fixme(title, body)`, `test.fixme(title, details, body)`, or called at runtime as `test.fixme(condition, description)`, `test.fixme(callback, description)`, or `test.fixme()` without arguments.

test.skip for skipping tests

The `test.skip()` method skips a test and Playwright will not run it past the skip() call. Can be declared as `test.skip(title, body)`, `test.skip(title, details, body)`, or called at runtime as `test.skip(condition, description)`, `test.skip(callback, description)`, or `test.skip()` without arguments. Skipped tests are not supposed to be run; use fixme() if you intend to fix the test.

test.slow for marking slow tests

The `test.slow()` method marks a test as 'slow', giving it triple the default timeout. Can be called as `test.slow()`, `test.slow(condition, description)`, or `test.slow(callback, description)`. Cannot be used in beforeAll or afterAll hooks; use test.setTimeout() instead.

test.only for focusing a single test

The `test.only()` method declares a focused test. If there are any focused tests or groups, all focused ones will run but nothing else. Can be called as `test.only(title, body)` or `test.only(title, details, body)`.

test.setTimeout for changing test timeout

The `test.setTimeout(timeout)` method changes the timeout for the currently running test in milliseconds. Zero means no timeout. Can be called from within a test, beforeEach hook, or beforeAll/afterAll hook. When called from beforeEach, it affects the test timeout shared with beforeEach hooks. When called from beforeAll/afterAll, it affects the hook's timeout, not the test timeout.

test.step for declaring test steps

The `test.step(title, body)` async method declares a test step shown in the report. The title parameter is required (string). The body is a function that receives TestStepInfo and returns a Promise. The method returns the value returned by the step callback. Steps can be nested. Additional options include `box` (boolean, defaults to false), `location` (Location), `params` (Object with serializable parameters), `subtitle` (string), and `timeout` (float in milliseconds, defaults to 0 for no timeout).

test.step.skip for skipping steps

The `test.step.skip(title, body)` async method marks a test step as 'skip' to temporarily disable its execution. Takes a title (string) and body function. Supports options: `box` (boolean), `location` (Location), `params` (Object), and `subtitle` (string).

test.step boxing for error reporting

When `box: true` is set on a test step, errors thrown from inside the step internals point to the step call site instead of the specific action that failed. This makes errors appear at the line where the step is called rather than deep within the step implementation.

test.step decorator pattern

TypeScript method decorators can be used to turn a method into a step. Each call to the decorated method will show up as a step in the report. The decorator receives the target function and context, and should call test.step with the combined class name and method name.

Test details parameter structure

The optional `details` parameter in test declaration has structure: { tag?: string | Array<string>, annotation?: { type: string, description?: string } | Array<{ type: string, description?: string }>, lock?: string | Array<string> }. The annotation type field is required, description is optional.

Describe with multiple execution modes nesting

Describe groups can be nested with different execution modes. For example, an outer describe can use mode 'parallel' while inner describes use mode 'default', allowing multiple describes to run in parallel while tests inside each describe run in order.

Running tests sequentially in a describe block

To run tests in a describe block sequentially, use `test.describe.configure({ mode: 'serial' })` within the describe. Alternatively, use `test.describe.configure({ mode: 'default' })` to run in order with independent retries. Note that serial mode is discouraged; it is usually better to make tests isolated so they run independently.

Give your agent this brain