Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

feat: introduce `kind` option in TestInfo.snapshotPath() (#35734)

Dmitry Gozman508b1ccdcbbc
diff --git a/docs/src/test-api/class-testinfo.md b/docs/src/test-api/class-testinfo.md
index 93cbc93b75..541a547bc1 100644
--- a/docs/src/test-api/class-testinfo.md
+++ b/docs/src/test-api/class-testinfo.md
@@ -387,17 +387,45 @@ Optional description that will be reflected in a test report.
* since: v1.10
- returns: <[string]>
-Returns a path to a snapshot file with the given `pathSegments`. Learn more about [snapshots](../test-snapshots.md).
+Returns a path to a snapshot file with the given `name`. Pass [`option: kind`] to obtain a specific path:
+* `kind: 'screenshot'` for [`method: PageAssertions.toHaveScreenshot#1`];
+* `kind: 'aria'` for [`method: LocatorAssertions.toMatchAriaSnapshot`];
+* `kind: 'snapshot'` for [`method: SnapshotAssertions.toMatchSnapshot#1`].
-> Note that `pathSegments` accepts path segments to the snapshot file such as `testInfo.snapshotPath('relative', 'path', 'to', 'snapshot.png')`.
-> However, this path must stay within the snapshots directory for each test file (i.e. `a.spec.js-snapshots`), otherwise it will throw.
+**Usage**
-### param: TestInfo.snapshotPath.pathSegments
+```js
+await expect(page).toHaveScreenshot('header.png');
+// Screenshot assertion above expects screenshot at this path:
+const screenshotPath = test.info().snapshotPath('header.png', { kind: 'screenshot' });
+
+await expect(page.getByRole('main')).toMatchAriaSnapshot({ name: 'main.aria.yml' });
+// Aria snapshot assertion above expects snapshot at this path:
+const ariaSnapshotPath = test.info().snapshotPath('main.aria.yml', { kind: 'aria' });
+
+expect('some text').toMatchSnapshot('snapshot.txt');
+// Snapshot assertion above expects snapshot at this path:
+const snapshotPath = test.info().snapshotPath('snapshot.txt');
+
+expect('some text').toMatchSnapshot(['dir', 'subdir', 'snapshot.txt']);
+// Snapshot assertion above expects snapshot at this path:
+const nestedPath = test.info().snapshotPath('dir', 'subdir', 'snapshot.txt');
+```
+
+### param: TestInfo.snapshotPath.name
* since: v1.10
-- `...pathSegments` <[Array]<[string]>>
+- `...name` <[Array]<[string]>>
The name of the snapshot or the path segments to define the snapshot file path. Snapshots with the same name in the same test file are expected to be the same.
+When passing [`option: kind`], multiple name segments are not supported.
+
+### option: TestInfo.snapshotPath.kind
+* since: v1.53
+- `kind` <[SnapshotKind]<"snapshot"|"screenshot"|"aria">>
+
+The snapshot kind controls which snapshot path template is used. See [`property: TestConfig.snapshotPathTemplate`] for more details. Defaults to `'snapshot'`.
+
## property: TestInfo.snapshotSuffix
* since: v1.10
- type: <[string]>
diff --git a/packages/playwright/src/matchers/toMatchAriaSnapshot.ts b/packages/playwright/src/matchers/toMatchAriaSnapshot.ts
index 003b92ab83..adf3602afd 100644
--- a/packages/playwright/src/matchers/toMatchAriaSnapshot.ts
+++ b/packages/playwright/src/matchers/toMatchAriaSnapshot.ts
@@ -54,8 +54,6 @@ export async function toMatchAriaSnapshot(
return { pass: !this.isNot, message: () => '', name: 'toMatchAriaSnapshot', expected: '' };
const updateSnapshots = testInfo.config.updateSnapshots;
- const pathTemplate = testInfo._projectInternal.expect?.toMatchAriaSnapshot?.pathTemplate;
- const defaultTemplate = '{snapshotDir}/{testFileDir}/{testFileName}-snapshots/{arg}{ext}';
const matcherOptions = {
isNot: this.isNot,
@@ -70,8 +68,7 @@ export async function toMatchAriaSnapshot(
timeout = options.timeout ?? this.timeout;
} else {
if (expectedParam?.name) {
- const ext = expectedParam.name.endsWith('.aria.yml') ? '.aria.yml' : undefined;
- expectedPath = testInfo._resolveSnapshotPath(pathTemplate, defaultTemplate, [expectedParam.name], true, ext);
+ expectedPath = testInfo._resolveSnapshotPath('aria', [expectedParam.name], true);
} else {
let snapshotNames = (testInfo as any)[snapshotNamesSymbol] as SnapshotNames;
if (!snapshotNames) {
@@ -79,11 +76,11 @@ export async function toMatchAriaSnapshot(
(testInfo as any)[snapshotNamesSymbol] = snapshotNames;
}
const fullTitleWithoutSpec = [...testInfo.titlePath.slice(1), ++snapshotNames.anonymousSnapshotIndex].join(' ');
- expectedPath = testInfo._resolveSnapshotPath(pathTemplate, defaultTemplate, [trimLongString(fullTitleWithoutSpec) + '.aria.yml'], true, '.aria.yml');
+ expectedPath = testInfo._resolveSnapshotPath('aria', [trimLongString(fullTitleWithoutSpec) + '.aria.yml'], true);
// in 1.51, we changed the default template to use .aria.yml extension
// for backwards compatibility, we check for the legacy .yml extension
if (!(await fileExistsAsync(expectedPath))) {
- const legacyPath = testInfo._resolveSnapshotPath(pathTemplate, defaultTemplate, [trimLongString(fullTitleWithoutSpec) + '.yml'], true, '.yml');
+ const legacyPath = testInfo._resolveSnapshotPath('aria', [trimLongString(fullTitleWithoutSpec) + '.yml'], true);
if (await fileExistsAsync(legacyPath))
expectedPath = legacyPath;
}
diff --git a/packages/playwright/src/matchers/toMatchSnapshot.ts b/packages/playwright/src/matchers/toMatchSnapshot.ts
index fb05e4ce38..4ae27ae186 100644
--- a/packages/playwright/src/matchers/toMatchSnapshot.ts
+++ b/packages/playwright/src/matchers/toMatchSnapshot.ts
@@ -95,7 +95,7 @@ class SnapshotHelper {
constructor(
testInfo: TestInfoImpl,
- matcherName: string,
+ matcherName: 'toMatchSnapshot' | 'toHaveScreenshot',
locator: Locator | undefined,
anonymousSnapshotExtension: string,
configOptions: ToHaveScreenshotConfigOptions,
@@ -160,8 +160,7 @@ class SnapshotHelper {
outputBasePath = testInfo._getOutputPath(sanitizedName);
this.attachmentBaseName = sanitizedName;
}
- const defaultTemplate = '{snapshotDir}/{testFileDir}/{testFileName}-snapshots/{arg}{-projectName}{-snapshotSuffix}{ext}';
- this.expectedPath = testInfo._resolveSnapshotPath(configOptions.pathTemplate, defaultTemplate, expectedPathSegments, sanitizeFilePath);
+ this.expectedPath = testInfo._resolveSnapshotPath(matcherName === 'toHaveScreenshot' ? 'screenshot' : 'snapshot', expectedPathSegments, sanitizeFilePath);
this.legacyExpectedPath = addSuffixToFilePath(outputBasePath, '-expected');
this.previousPath = addSuffixToFilePath(outputBasePath, '-previous');
this.actualPath = addSuffixToFilePath(outputBasePath, '-actual');
diff --git a/packages/playwright/src/worker/testInfo.ts b/packages/playwright/src/worker/testInfo.ts
index f14a483a35..b26f91b60c 100644
--- a/packages/playwright/src/worker/testInfo.ts
+++ b/packages/playwright/src/worker/testInfo.ts
@@ -448,20 +448,33 @@ export class TestInfoImpl implements TestInfo {
return sanitizeForFilePath(trimLongString(fullTitleWithoutSpec));
}
- _resolveSnapshotPath(template: string | undefined, defaultTemplate: string, pathSegments: string[], sanitizeFilePath: boolean, extension?: string) {
+ _resolveSnapshotPath(kind: 'snapshot' | 'screenshot' | 'aria', pathSegments: string[], sanitizeFilePath: boolean) {
let subPath = path.join(...pathSegments);
+ let ext = path.extname(subPath);
+
+ const legacyTemplate = '{snapshotDir}/{testFileDir}/{testFileName}-snapshots/{arg}{-projectName}{-snapshotSuffix}{ext}';
+ let template: string;
+ if (kind === 'screenshot') {
+ template = this._projectInternal.expect?.toHaveScreenshot?.pathTemplate || this._projectInternal.snapshotPathTemplate || legacyTemplate;
+ } else if (kind === 'aria') {
+ const ariaDefaultTemplate = '{snapshotDir}/{testFileDir}/{testFileName}-snapshots/{arg}{ext}';
+ template = this._projectInternal.expect?.toMatchAriaSnapshot?.pathTemplate || this._projectInternal.snapshotPathTemplate || ariaDefaultTemplate;
+ if (subPath.endsWith('.aria.yml'))
+ ext = '.aria.yml';
+ } else {
+ template = this._projectInternal.snapshotPathTemplate || legacyTemplate;
+ }
+
if (sanitizeFilePath)
- subPath = sanitizeFilePathBeforeExtension(subPath, extension);
+ subPath = sanitizeFilePathBeforeExtension(subPath, ext);
const dir = path.dirname(subPath);
- const ext = extension ?? path.extname(subPath);
const name = path.basename(subPath, ext);
const relativeTestFilePath = path.relative(this.project.testDir, this._requireFile);
const parsedRelativeTestFilePath = path.parse(relativeTestFilePath);
const projectNamePathSegment = sanitizeForFilePath(this.project.name);
- const actualTemplate = (template || this._projectInternal.snapshotPathTemplate || defaultTemplate);
- const snapshotPath = actualTemplate
+ const snapshotPath = template
.replace(/\{(.)?testDir\}/g, '$1' + this.project.testDir)
.replace(/\{(.)?snapshotDir\}/g, '$1' + this.project.snapshotDir)
.replace(/\{(.)?snapshotSuffix\}/g, this.snapshotSuffix ? '$1' + this.snapshotSuffix : '')
@@ -477,12 +490,25 @@ export class TestInfoImpl implements TestInfo {
return path.normalize(path.resolve(this._configInternal.configDir, snapshotPath));
}
- snapshotPath(...pathSegments: string[]) {
+ snapshotPath(...name: string[]): string;
+ snapshotPath(name: string, options: { kind: 'snapshot' | 'screenshot' | 'aria' }): string;
+ snapshotPath(...args: any[]) {
+ let pathSegments: string[] = args;
+ let kind: 'snapshot' | 'screenshot' | 'aria' = 'snapshot';
+
+ const options = args[args.length - 1];
+ if (options && typeof options === 'object') {
+ kind = options.kind ?? kind;
+ pathSegments = args.slice(0, -1);
+ }
+
+ if (!['snapshot', 'screenshot', 'aria'].includes(kind))
+ throw new Error(`testInfo.snapshotPath: unknown kind "${kind}", must be one of "snapshot", "screenshot" or "aria"`);
+
// Assume a single path segment corresponds to `toHaveScreenshot(name)` and sanitize it,
// like we do in SnapshotHelper. See https://github.com/microsoft/playwright/pull/9156 for history.
const sanitizeFilePath = pathSegments.length === 1;
- const legacyTemplate = '{snapshotDir}/{testFileDir}/{testFileName}-snapshots/{arg}{-projectName}{-snapshotSuffix}{ext}';
- return this._resolveSnapshotPath(undefined, legacyTemplate, pathSegments, sanitizeFilePath);
+ return this._resolveSnapshotPath(kind, pathSegments, sanitizeFilePath);
}
skip(...args: [arg?: any, description?: string]) {
diff --git a/packages/playwright/types/test.d.ts b/packages/playwright/types/test.d.ts
index 7e4ec8f2c8..68a449530d 100644
--- a/packages/playwright/types/test.d.ts
+++ b/packages/playwright/types/test.d.ts
@@ -419,7 +419,7 @@ interface TestProject<TestArgs = {}, WorkerArgs = {}> {
*
* The directory for each test can be accessed by
* [testInfo.snapshotDir](https://playwright.dev/docs/api/class-testinfo#test-info-snapshot-dir) and
- * [testInfo.snapshotPath(...pathSegments)](https://playwright.dev/docs/api/class-testinfo#test-info-snapshot-path).
+ * [testInfo.snapshotPath(...name[, options])](https://playwright.dev/docs/api/class-testinfo#test-info-snapshot-path).
*
* This path will serve as the base directory for each test file snapshot directory. Setting `snapshotDir` to
* `'snapshots'`, the [testInfo.snapshotDir](https://playwright.dev/docs/api/class-testinfo#test-info-snapshot-dir)
@@ -1621,7 +1621,7 @@ interface TestConfig<TestArgs = {}, WorkerArgs = {}> {
*
* The directory for each test can be accessed by
* [testInfo.snapshotDir](https://playwright.dev/docs/api/class-testinfo#test-info-snapshot-dir) and
- * [testInfo.snapshotPath(...pathSegments)](https://playwright.dev/docs/api/class-testinfo#test-info-snapshot-path).
+ * [testInfo.snapshotPath(...name[, options])](https://playwright.dev/docs/api/class-testinfo#test-info-snapshot-path).
*
* This path will serve as the base directory for each test file snapshot directory. Setting `snapshotDir` to
* `'snapshots'`, the [testInfo.snapshotDir](https://playwright.dev/docs/api/class-testinfo#test-info-snapshot-dir)
@@ -2042,209 +2042,729 @@ export interface FullConfig<TestArgs = {}, WorkerArgs = {}> {
workers: number;
}
-export type TestStatus = 'passed' | 'failed' | 'timedOut' | 'skipped' | 'interrupted';
-
-export type TestDetailsAnnotation = {
- type: string;
- description?: string;
-};
-
-export type TestAnnotation = TestDetailsAnnotation;
-
-export type TestDetails = {
- tag?: string | string[];
- annotation?: TestDetailsAnnotation | TestDetailsAnnotation[];
-}
-
-type TestBody<TestArgs> = (args: TestArgs, testInfo: TestInfo) => Promise<void> | void;
-type ConditionBody<TestArgs> = (args: TestArgs) => boolean;
-
/**
- * Playwright Test provides a `test` function to declare tests and `expect` function to write assertions.
+ * `TestInfo` contains information about currently running test. It is available to test functions,
+ * [test.beforeEach([title, hookFunction])](https://playwright.dev/docs/api/class-test#test-before-each),
+ * [test.afterEach([title, hookFunction])](https://playwright.dev/docs/api/class-test#test-after-each),
+ * [test.beforeAll([title, hookFunction])](https://playwright.dev/docs/api/class-test#test-before-all) and
+ * [test.afterAll([title, hookFunction])](https://playwright.dev/docs/api/class-test#test-after-all) hooks, and
+ * test-scoped fixtures. `TestInfo` provides utilities to control test execution: attach files, update test timeout,
+ * determine which test is currently running and whether it was retried, etc.
*
* ```js
* 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('basic test', async ({ page }, testInfo) => {
+ * expect(testInfo.title).toBe('basic test');
+ * await page.screenshot(testInfo.outputPath('screenshot.png'));
* });
* ```
*
*/
-export interface TestType<TestArgs extends {}, WorkerArgs extends {}> {
+export interface TestInfo {
/**
- * Declares a test.
- * - `test(title, body)`
- * - `test(title, details, body)`
+ * Returns a path to a snapshot file with the given `name`. Pass
+ * [`kind`](https://playwright.dev/docs/api/class-testinfo#test-info-snapshot-path-option-kind) to obtain a specific
+ * path:
+ * - `kind: 'screenshot'` for
+ * [expect(page).toHaveScreenshot(name[, options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1);
+ * - `kind: 'aria'` for
+ * [expect(locator).toMatchAriaSnapshot(expected[, options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-match-aria-snapshot);
+ * - `kind: 'snapshot'` for
+ * [expect(value).toMatchSnapshot(name[, options])](https://playwright.dev/docs/api/class-snapshotassertions#snapshot-assertions-to-match-snapshot-1).
*
* **Usage**
*
* ```js
- * 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.
+ * await expect(page).toHaveScreenshot('header.png');
+ * // Screenshot assertion above expects screenshot at this path:
+ * const screenshotPath = test.info().snapshotPath('header.png', { kind: 'screenshot' });
*
- * ```js
- * import { test, expect } from '@playwright/test';
+ * await expect(page.getByRole('main')).toMatchAriaSnapshot({ name: 'main.aria.yml' });
+ * // Aria snapshot assertion above expects snapshot at this path:
+ * const ariaSnapshotPath = test.info().snapshotPath('main.aria.yml', { kind: 'aria' });
*
- * test('basic test', {
- * tag: '@smoke',
- * }, async ({ page }) => {
- * await page.goto('https://playwright.dev/');
- * // ...
- * });
+ * expect('some text').toMatchSnapshot('snapshot.txt');
+ * // Snapshot assertion above expects snapshot at this path:
+ * const snapshotPath = test.info().snapshotPath('snapshot.txt');
*
- * test('another test @smoke', async ({ page }) => {
- * await page.goto('https://playwright.dev/');
- * // ...
- * });
+ * expect('some text').toMatchSnapshot(['dir', 'subdir', 'snapshot.txt']);
+ * // Snapshot assertion above expects snapshot at this path:
+ * const nestedPath = test.info().snapshotPath('dir', 'subdir', 'snapshot.txt');
* ```
*
- * Test tags are displayed in the test report, and are available to a custom reporter via `TestCase.tags` property.
+ * @param name The name of the snapshot or the path segments to define the snapshot file path. Snapshots with the same name in the
+ * same test file are expected to be the same.
*
- * You can also filter tests by their tags during test execution:
- * - in the [command line](https://playwright.dev/docs/test-cli#reference);
- * - in the config with [testConfig.grep](https://playwright.dev/docs/api/class-testconfig#test-config-grep) and
- * [testProject.grep](https://playwright.dev/docs/api/class-testproject#test-project-grep);
+ * When passing [`kind`](https://playwright.dev/docs/api/class-testinfo#test-info-snapshot-path-option-kind), multiple
+ * name segments are not supported.
+ * @param options
+ */
+ snapshotPath(...name: ReadonlyArray<string>): string;
+ /**
+ * Returns a path to a snapshot file with the given `name`. Pass
+ * [`kind`](https://playwright.dev/docs/api/class-testinfo#test-info-snapshot-path-option-kind) to obtain a specific
+ * path:
+ * - `kind: 'screenshot'` for
+ * [expect(page).toHaveScreenshot(name[, options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1);
+ * - `kind: 'aria'` for
+ * [expect(locator).toMatchAriaSnapshot(expected[, options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-match-aria-snapshot);
+ * - `kind: 'snapshot'` for
+ * [expect(value).toMatchSnapshot(name[, options])](https://playwright.dev/docs/api/class-snapshotassertions#snapshot-assertions-to-match-snapshot-1).
*
- * Learn more about [tagging](https://playwright.dev/docs/test-annotations#tag-tests).
+ * **Usage**
*
- * **Annotations**
+ * ```js
+ * await expect(page).toHaveScreenshot('header.png');
+ * // Screenshot assertion above expects screenshot at this path:
+ * const screenshotPath = test.info().snapshotPath('header.png', { kind: 'screenshot' });
*
- * You can annotate tests by providing additional test details.
+ * await expect(page.getByRole('main')).toMatchAriaSnapshot({ name: 'main.aria.yml' });
+ * // Aria snapshot assertion above expects snapshot at this path:
+ * const ariaSnapshotPath = test.info().snapshotPath('main.aria.yml', { kind: 'aria' });
*
- * ```js
- * import { test, expect } from '@playwright/test';
+ * expect('some text').toMatchSnapshot('snapshot.txt');
+ * // Snapshot assertion above expects snapshot at this path:
+ * const snapshotPath = test.info().snapshotPath('snapshot.txt');
*
- * test('basic test', {
- * annotation: {
- * type: 'issue',
- * description: 'https://github.com/microsoft/playwright/issues/23180',
- * },
- * }, async ({ page }) => {
- * await page.goto('https://playwright.dev/');
- * // ...
- * });
+ * expect('some text').toMatchSnapshot(['dir', 'subdir', 'snapshot.txt']);
+ * // Snapshot assertion above expects snapshot at this path:
+ * const nestedPath = test.info().snapshotPath('dir', 'subdir', 'snapshot.txt');
* ```
*
- * 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](https://playwright.dev/docs/api/class-testinfo#test-info-annotations).
+ * @param name The name of the snapshot or the path segments to define the snapshot file path. Snapshots with the same name in the
+ * same test file are expected to be the same.
*
- * Learn more about [test annotations](https://playwright.dev/docs/test-annotations).
- * @param title Test title.
- * @param details Additional test details.
- * @param body Test body that takes one or two arguments: an object with fixtures and optional
- * [TestInfo](https://playwright.dev/docs/api/class-testinfo).
+ * When passing [`kind`](https://playwright.dev/docs/api/class-testinfo#test-info-snapshot-path-option-kind), multiple
+ * name segments are not supported.
+ * @param options
*/
- (title: string, body: TestBody<TestArgs & WorkerArgs>): void;
+ snapshotPath(name: string, options: { kind: 'snapshot' | 'screenshot' | 'aria' }): string;
/**
- * Declares a test.
- * - `test(title, body)`
- * - `test(title, details, body)`
+ * Attach a value or a file from disk to the current test. Some reporters show test attachments. Either
+ * [`path`](https://playwright.dev/docs/api/class-testinfo#test-info-attach-option-path) or
+ * [`body`](https://playwright.dev/docs/api/class-testinfo#test-info-attach-option-body) must be specified, but not
+ * both.
*
- * **Usage**
+ * For example, you can attach a screenshot to the test:
*
* ```js
* import { test, expect } from '@playwright/test';
*
- * test('basic test', async ({ page }) => {
- * await page.goto('https://playwright.dev/');
- * // ...
+ * test('basic test', async ({ page }, testInfo) => {
+ * await page.goto('https://playwright.dev');
+ * const screenshot = await page.screenshot();
+ * await testInfo.attach('screenshot', { body: screenshot, contentType: 'image/png' });
* });
* ```
*
- * **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.
+ * Or you can attach files returned by your APIs:
*
* ```js
* import { test, expect } from '@playwright/test';
+ * import { download } from './my-custom-helpers';
*
- * 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('basic test', async ({}, testInfo) => {
+ * const tmpPath = await download('a');
+ * await testInfo.attach('downloaded', { path: tmpPath });
* });
* ```
*
- * 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](https://playwright.dev/docs/test-cli#reference);
- * - in the config with [testConfig.grep](https://playwright.dev/docs/api/class-testconfig#test-config-grep) and
- * [testProject.grep](https://playwright.dev/docs/api/class-testproject#test-project-grep);
- *
- * Learn more about [tagging](https://playwright.dev/docs/test-annotations#tag-tests).
- *
- * **Annotations**
+ * **NOTE** [testInfo.attach(name[, options])](https://playwright.dev/docs/api/class-testinfo#test-info-attach)
+ * automatically takes care of copying attached files to a location that is accessible to reporters. You can safely
+ * remove the attachment after awaiting the attach call.
*
- * You can annotate tests by providing additional test details.
+ * @param name Attachment name. The name will also be sanitized and used as the prefix of file name when saving to disk.
+ * @param options
+ */
+ attach(name: string, options?: {
+ /**
+ * Attachment body. Mutually exclusive with
+ * [`path`](https://playwright.dev/docs/api/class-testinfo#test-info-attach-option-path).
+ */
+ body?: string|Buffer;
+
+ /**
+ * Content type of this attachment to properly present in the report, for example `'application/json'` or
+ * `'image/png'`. If omitted, content type is inferred based on the
+ * [`path`](https://playwright.dev/docs/api/class-testinfo#test-info-attach-option-path), or defaults to `text/plain`
+ * for [string] attachments and `application/octet-stream` for [Buffer] attachments.
+ */
+ contentType?: string;
+
+ /**
+ * Path on the filesystem to the attached file. Mutually exclusive with
+ * [`body`](https://playwright.dev/docs/api/class-testinfo#test-info-attach-option-body).
+ */
+ path?: string;
+ }): Promise<void>;
+
+ /**
+ * Marks the currently running 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. This is similar to
+ * [test.fail([title, details, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-fail).
+ */
+ fail(): void;
+
+ /**
+ * Conditionally mark the currently running test as "should fail" with an optional description. This is similar to
+ * [test.fail([title, details, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-fail).
+ * @param condition Test is marked as "should fail" when the condition is `true`.
+ * @param description Optional description that will be reflected in a test report.
+ */
+ fail(condition: boolean, description?: string): void;
+
+ /**
+ * Mark a test as "fixme", with the intention to fix it. Test is immediately aborted. This is similar to
+ * [test.fixme([title, details, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-fixme).
+ */
+ fixme(): void;
+
+ /**
+ * Conditionally mark the currently running test as "fixme" with an optional description. This is similar to
+ * [test.fixme([title, details, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-fixme).
+ * @param condition Test is marked as "fixme" when the condition is `true`.
+ * @param description Optional description that will be reflected in a test report.
+ */
+ fixme(condition: boolean, description?: string): void;
+
+ /**
+ * Returns a path inside the [testInfo.outputDir](https://playwright.dev/docs/api/class-testinfo#test-info-output-dir)
+ * where the test can safely put a temporary file. Guarantees that tests running in parallel will not interfere with
+ * each other.
*
* ```js
* import { test, expect } from '@playwright/test';
+ * import fs from 'fs';
*
- * test('basic test', {
- * annotation: {
- * type: 'issue',
- * description: 'https://github.com/microsoft/playwright/issues/23180',
- * },
- * }, async ({ page }) => {
- * await page.goto('https://playwright.dev/');
- * // ...
+ * test('example test', async ({}, testInfo) => {
+ * const file = testInfo.outputPath('dir', 'temporary-file.txt');
+ * await fs.promises.writeFile(file, 'Put some data to the dir/temporary-file.txt', 'utf8');
* });
* ```
*
- * 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](https://playwright.dev/docs/api/class-testinfo#test-info-annotations).
- *
- * Learn more about [test annotations](https://playwright.dev/docs/test-annotations).
- * @param title Test title.
- * @param details Additional test details.
- * @param body Test body that takes one or two arguments: an object with fixtures and optional
- * [TestInfo](https://playwright.dev/docs/api/class-testinfo).
+ * > Note that `pathSegments` accepts path segments to the test output directory such as
+ * `testInfo.outputPath('relative', 'path', 'to', 'output')`.
+ * > However, this path must stay within the
+ * [testInfo.outputDir](https://playwright.dev/docs/api/class-testinfo#test-info-output-dir) directory for each test
+ * (i.e. `test-results/a-test-title`), otherwise it will throw.
+ * @param pathSegments Path segments to append at the end of the resulting path.
*/
- (title: string, details: TestDetails, body: TestBody<TestArgs & WorkerArgs>): void;
+ outputPath(...pathSegments: ReadonlyArray<string>): string;
/**
- * 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)`
+ * Changes the timeout for the currently running test. Zero means no timeout. Learn more about
+ * [various timeouts](https://playwright.dev/docs/test-timeouts).
*
- * **Usage**
+ * Timeout is usually specified in the [configuration file](https://playwright.dev/docs/test-configuration), but it could be useful to
+ * change the timeout in certain scenarios:
*
* ```js
- * test.only('focus this test', async ({ page }) => {
- * // Run only focused tests in the entire project.
+ * import { test, expect } from '@playwright/test';
+ *
+ * test.beforeEach(async ({ page }, testInfo) => {
+ * // Extend timeout for all tests running this hook by 30 seconds.
+ * testInfo.setTimeout(testInfo.timeout + 30000);
* });
* ```
*
- * @param title Test title.
- * @param details See [test.(call)(title[, details, body])](https://playwright.dev/docs/api/class-test#test-call) for test details
- * description.
+ * @param timeout Timeout in milliseconds.
+ */
+ setTimeout(timeout: number): void;
+
+ /**
+ * Unconditionally skip the currently running test. Test is immediately aborted. This is similar to
+ * [test.skip([title, details, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-skip).
+ */
+ skip(): void;
+
+ /**
+ * Conditionally skips the currently running test with an optional description. This is similar to
+ * [test.skip([title, details, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-skip).
+ * @param condition A skip condition. Test is skipped when the condition is `true`.
+ * @param description Optional description that will be reflected in a test report.
+ */
+ skip(condition: boolean, description?: string): void;
+
+ /**
+ * Marks the currently running test as "slow", giving it triple the default timeout. This is similar to
+ * [test.slow([condition, callback, description])](https://playwright.dev/docs/api/class-test#test-slow).
+ */
+ slow(): void;
+
+ /**
+ * Conditionally mark the currently running test as "slow" with an optional description, giving it triple the default
+ * timeout. This is similar to
+ * [test.slow([condition, callback, description])](https://playwright.dev/docs/api/class-test#test-slow).
+ * @param condition Test is marked as "slow" when the condition is `true`.
+ * @param description Optional description that will be reflected in a test report.
+ */
+ slow(condition: boolean, description?: string): void;
+
+ /**
+ * The list of annotations applicable to the current test. Includes annotations from the test, annotations from all
+ * [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) groups the
+ * test belongs to and file-level annotations for the test file.
+ *
+ * Learn more about [test annotations](https://playwright.dev/docs/test-annotations).
+ */
+ annotations: Array<{
+ /**
+ * Annotation type, for example `'skip'` or `'fail'`.
+ */
+ type: string;
+
+ /**
+ * Optional description.
+ */
+ description?: string;
+ }>;
+
+ /**
+ * The list of files or buffers attached to the current test. Some reporters show test attachments.
+ *
+ * To add an attachment, use
+ * [testInfo.attach(name[, options])](https://playwright.dev/docs/api/class-testinfo#test-info-attach) instead of
+ * directly pushing onto this array.
+ */
+ attachments: Array<{
+ /**
+ * Attachment name.
+ */
+ name: string;
+
+ /**
+ * Content type of this attachment to properly present in the report, for example `'application/json'` or
+ * `'image/png'`.
+ */
+ contentType: string;
+
+ /**
+ * Optional path on the filesystem to the attached file.
+ */
+ path?: string;
+
+ /**
+ * Optional attachment body used instead of a file.
+ */
+ body?: Buffer;
+ }>;
+
+ /**
+ * Column number where the currently running test is declared.
+ */
+ column: number;
+
+ /**
+ * Processed configuration from the [configuration file](https://playwright.dev/docs/test-configuration).
+ */
+ config: FullConfig;
+
+ /**
+ * The number of milliseconds the test took to finish. Always zero before the test finishes, either successfully or
+ * not. Can be used in
+ * [test.afterEach([title, hookFunction])](https://playwright.dev/docs/api/class-test#test-after-each) hook.
+ */
+ duration: number;
+
+ /**
+ * First error thrown during test execution, if any. This is equal to the first element in
+ * [testInfo.errors](https://playwright.dev/docs/api/class-testinfo#test-info-errors).
+ */
+ error?: TestInfoError;
+
+ /**
+ * Errors thrown during test execution, if any.
+ */
+ errors: Array<TestInfoError>;
+
+ /**
+ * Expected status for the currently running test. This is usually `'passed'`, except for a few cases:
+ * - `'skipped'` for skipped tests, e.g. with
+ * [test.skip([title, details, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-skip);
+ * - `'failed'` for tests marked as failed with
+ * [test.fail([title, details, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-fail).
+ *
+ * Expected status is usually compared with the actual
+ * [testInfo.status](https://playwright.dev/docs/api/class-testinfo#test-info-status):
+ *
+ * ```js
+ * import { test, expect } from '@playwright/test';
+ *
+ * test.afterEach(async ({}, testInfo) => {
+ * if (testInfo.status !== testInfo.expectedStatus)
+ * console.log(`${testInfo.title} did not run as expected!`);
+ * });
+ * ```
+ *
+ */
+ expectedStatus: "passed"|"failed"|"timedOut"|"skipped"|"interrupted";
+
+ /**
+ * Absolute path to a file where the currently running test is declared.
+ */
+ file: string;
+
+ /**
+ * Test function as passed to `test(title, testFunction)`.
+ */
+ fn: Function;
+
+ /**
+ * Line number where the currently running test is declared.
+ */
+ line: number;
+
+ /**
+ * Absolute path to the output directory for this specific test run. Each test run gets its own directory so they
+ * cannot conflict.
+ */
+ outputDir: string;
+
+ /**
+ * The index of the worker between `0` and `workers - 1`. It is guaranteed that workers running at the same time have
+ * a different `parallelIndex`. When a worker is restarted, for example after a failure, the new worker process has
+ * the same `parallelIndex`.
+ *
+ * Also available as `process.env.TEST_PARALLEL_INDEX`. Learn more about
+ * [parallelism and sharding](https://playwright.dev/docs/test-parallel) with Playwright Test.
+ */
+ parallelIndex: number;
+
+ /**
+ * Processed project configuration from the [configuration file](https://playwright.dev/docs/test-configuration).
+ */
+ project: FullProject;
+
+ /**
+ * Specifies a unique repeat index when running in "repeat each" mode. This mode is enabled by passing `--repeat-each`
+ * to the [command line](https://playwright.dev/docs/test-cli).
+ */
+ repeatEachIndex: number;
+
+ /**
+ * Specifies the retry number when the test is retried after a failure. The first test run has
+ * [testInfo.retry](https://playwright.dev/docs/api/class-testinfo#test-info-retry) equal to zero, the first retry has
+ * it equal to one, and so on. Learn more about [retries](https://playwright.dev/docs/test-retries#retries).
+ *
+ * ```js
+ * import { test, expect } from '@playwright/test';
+ *
+ * test.beforeEach(async ({}, testInfo) => {
+ * // You can access testInfo.retry in any hook or fixture.
+ * if (testInfo.retry > 0)
+ * console.log(`Retrying!`);
+ * });
+ *
+ * test('my test', async ({ page }, testInfo) => {
+ * // Here we clear some server-side state when retrying.
+ * if (testInfo.retry)
+ * await cleanSomeCachesOnTheServer();
+ * // ...
+ * });
+ * ```
+ *
+ */
+ retry: number;
+
+ /**
+ * Absolute path to the snapshot output directory for this specific test. Each test suite gets its own directory so
+ * they cannot conflict.
+ *
+ * This property does not account for the
+ * [testProject.snapshotPathTemplate](https://playwright.dev/docs/api/class-testproject#test-project-snapshot-path-template)
+ * configuration.
+ */
+ snapshotDir: string;
+
+ /**
+ * **NOTE** Use of [testInfo.snapshotSuffix](https://playwright.dev/docs/api/class-testinfo#test-info-snapshot-suffix)
+ * is discouraged. Please use
+ * [testConfig.snapshotPathTemplate](https://playwright.dev/docs/api/class-testconfig#test-config-snapshot-path-template)
+ * to configure snapshot paths.
+ *
+ * Suffix used to differentiate snapshots between multiple test configurations. For example, if snapshots depend on
+ * the platform, you can set `testInfo.snapshotSuffix` equal to `process.platform`. In this case
+ * `expect(value).toMatchSnapshot(snapshotName)` will use different snapshots depending on the platform. Learn more
+ * about [snapshots](https://playwright.dev/docs/test-snapshots).
+ */
+ snapshotSuffix: string;
+
+ /**
+ * Actual status for the currently running test. Available after the test has finished in
+ * [test.afterEach([title, hookFunction])](https://playwright.dev/docs/api/class-test#test-after-each) hook and
+ * fixtures.
+ *
+ * Status is usually compared with the
+ * [testInfo.expectedStatus](https://playwright.dev/docs/api/class-testinfo#test-info-expected-status):
+ *
+ * ```js
+ * import { test, expect } from '@playwright/test';
+ *
+ * test.afterEach(async ({}, testInfo) => {
+ * if (testInfo.status !== testInfo.expectedStatus)
+ * console.log(`${testInfo.title} did not run as expected!`);
+ * });
+ * ```
+ *
+ */
+ status?: "passed"|"failed"|"timedOut"|"skipped"|"interrupted";
+
+ /**
+ * Tags that apply to the test. Learn more about [tags](https://playwright.dev/docs/test-annotations#tag-tests).
+ *
+ * **NOTE** Any changes made to this list while the test is running will not be visible to test reporters.
+ *
+ */
+ tags: Array<string>;
+
+ /**
+ * Test id matching the test case id in the reporter API.
+ */
+ testId: string;
+
+ /**
+ * Timeout in milliseconds for the currently running test. Zero means no timeout. Learn more about
+ * [various timeouts](https://playwright.dev/docs/test-timeouts).
+ *
+ * Timeout is usually specified in the [configuration file](https://playwright.dev/docs/test-configuration)
+ *
+ * ```js
+ * import { test, expect } from '@playwright/test';
+ *
+ * test.beforeEach(async ({ page }, testInfo) => {
+ * // Extend timeout for all tests running this hook by 30 seconds.
+ * testInfo.setTimeout(testInfo.timeout + 30000);
+ * });
+ * ```
+ *
+ */
+ timeout: number;
+
+ /**
+ * The title of the currently running test as passed to `test(title, testFunction)`.
+ */
+ title: string;
+
+ /**
+ * The full title path starting with the test file name.
+ */
+ titlePath: Array<string>;
+
+ /**
+ * The unique index of the worker process that is running the test. When a worker is restarted, for example after a
+ * failure, the new worker process gets a new unique `workerIndex`.
+ *
+ * Also available as `process.env.TEST_WORKER_INDEX`. Learn more about [parallelism and sharding](https://playwright.dev/docs/test-parallel)
+ * with Playwright Test.
+ */
+ workerIndex: number;
+}
+
+export type TestStatus = 'passed' | 'failed' | 'timedOut' | 'skipped' | 'interrupted';
+
+export type TestDetailsAnnotation = {
+ type: string;
+ description?: string;
+};
+
+export type TestAnnotation = TestDetailsAnnotation;
+
+export type TestDetails = {
+ tag?: string | string[];
+ annotation?: TestDetailsAnnotation | TestDetailsAnnotation[];
+}
+
+type TestBody<TestArgs> = (args: TestArgs, testInfo: TestInfo) => Promise<void> | void;
+type ConditionBody<TestArgs> = (args: TestArgs) => boolean;
+
+/**
+ * Playwright Test provides a `test` function to declare tests and `expect` function to write assertions.
+ *
+ * ```js
+ * 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');
+ * });
+ * ```
+ *
+ */
+export interface TestType<TestArgs extends {}, WorkerArgs extends {}> {
+ /**
+ * Declares a test.
+ * - `test(title, body)`
+ * - `test(title, details, body)`
+ *
+ * **Usage**
+ *
+ * ```js
+ * 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.
+ *
+ * ```js
+ * 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](https://playwright.dev/docs/test-cli#reference);
+ * - in the config with [testConfig.grep](https://playwright.dev/docs/api/class-testconfig#test-config-grep) and
+ * [testProject.grep](https://playwright.dev/docs/api/class-testproject#test-project-grep);
+ *
+ * Learn more about [tagging](https://playwright.dev/docs/test-annotations#tag-tests).
+ *
+ * **Annotations**
+ *
+ * You can annotate tests by providing additional test details.
+ *
+ * ```js
+ * 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](https://playwright.dev/docs/api/class-testinfo#test-info-annotations).
+ *
+ * Learn more about [test annotations](https://playwright.dev/docs/test-annotations).
+ * @param title Test title.
+ * @param details Additional test details.
+ * @param body Test body that takes one or two arguments: an object with fixtures and optional
+ * [TestInfo](https://playwright.dev/docs/api/class-testinfo).
+ */
+ (title: string, body: TestBody<TestArgs & WorkerArgs>): void;
+ /**
+ * Declares a test.
+ * - `test(title, body)`
+ * - `test(title, details, body)`
+ *
+ * **Usage**
+ *
+ * ```js
+ * 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.
+ *
+ * ```js
+ * 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](https://playwright.dev/docs/test-cli#reference);
+ * - in the config with [testConfig.grep](https://playwright.dev/docs/api/class-testconfig#test-config-grep) and
+ * [testProject.grep](https://playwright.dev/docs/api/class-testproject#test-project-grep);
+ *
+ * Learn more about [tagging](https://playwright.dev/docs/test-annotations#tag-tests).
+ *
+ * **Annotations**
+ *
+ * You can annotate tests by providing additional test details.
+ *
+ * ```js
+ * 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](https://playwright.dev/docs/api/class-testinfo#test-info-annotations).
+ *
+ * Learn more about [test annotations](https://playwright.dev/docs/test-annotations).
+ * @param title Test title.
+ * @param details Additional test details.
+ * @param body Test body that takes one or two arguments: an object with fixtures and optional
+ * [TestInfo](https://playwright.dev/docs/api/class-testinfo).
+ */
+ (title: string, details: TestDetails, body: TestBody<TestArgs & WorkerArgs>): void;
+
+ /**
+ * 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**
+ *
+ * ```js
+ * test.only('focus this test', async ({ page }) => {
+ * // Run only focused tests in the entire project.
+ * });
+ * ```
+ *
+ * @param title Test title.
+ * @param details See [test.(call)(title[, details, body])](https://playwright.dev/docs/api/class-test#test-call) for test details
+ * description.
* @param body Test body that takes one or two arguments: an object with fixtures and optional
* [TestInfo](https://playwright.dev/docs/api/class-testinfo).
*/
@@ -7186,1212 +7706,786 @@ interface AsymmetricMatchers {
*
* ```js
* // Assert some of the properties.
- * expect({ foo: 1, bar: 2 }).toEqual(expect.objectContaining({ foo: 1 }));
- *
- * // Matchers can be used on the properties as well.
- * expect({ foo: 1, bar: 2 }).toEqual(expect.objectContaining({ bar: expect.any(Number) }));
- *
- * // Complex matching of sub-properties.
- * expect({
- * list: [1, 2, 3],
- * obj: { prop: 'Hello world!', another: 'some other value' },
- * extra: 'extra',
- * }).toEqual(expect.objectContaining({
- * list: expect.arrayContaining([2, 3]),
- * obj: expect.objectContaining({ prop: expect.stringContaining('Hello') }),
- * }));
- * ```
- *
- * @param expected Expected object pattern that contains a subset of the properties.
- */
- objectContaining(sample: Record<string, unknown>): AsymmetricMatcher;
- /**
- * `expect.stringContaining()` matches a string that contains the expected substring. Use this method inside
- * [expect(value).toEqual(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-equal)
- * to perform pattern matching.
- *
- * **Usage**
- *
- * ```js
- * expect('Hello world!').toEqual(expect.stringContaining('Hello'));
- * ```
- *
- * @param expected Expected substring.
- */
- stringContaining(sample: string): AsymmetricMatcher;
- /**
- * `expect.stringMatching()` matches a received string that in turn matches the expected pattern. Use this method
- * inside
- * [expect(value).toEqual(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-equal)
- * to perform pattern matching.
- *
- * **Usage**
- *
- * ```js
- * expect('123ms').toEqual(expect.stringMatching(/\d+m?s/));
- *
- * // Inside another matcher.
- * expect({
- * status: 'passed',
- * time: '123ms',
- * }).toEqual({
- * status: expect.stringMatching(/passed|failed/),
- * time: expect.stringMatching(/\d+m?s/),
- * });
- * ```
- *
- * @param expected Pattern that expected string should match.
- */
- stringMatching(sample: string | RegExp): AsymmetricMatcher;
-}
-
-/**
- * The [GenericAssertions](https://playwright.dev/docs/api/class-genericassertions) class provides assertion methods
- * that can be used to make assertions about any values in the tests. A new instance of
- * [GenericAssertions](https://playwright.dev/docs/api/class-genericassertions) is created by calling
- * [expect(value)](https://playwright.dev/docs/api/class-playwrightassertions#playwright-assertions-expect-generic):
- *
- * ```js
- * import { test, expect } from '@playwright/test';
- *
- * test('assert a value', async ({ page }) => {
- * const value = 1;
- * expect(value).toBe(2);
- * });
- * ```
- *
- */
-interface GenericAssertions<R> {
- /**
- * Makes the assertion check for the opposite condition. For example, the following code passes:
- *
- * ```js
- * const value = 1;
- * expect(value).not.toBe(2);
- * ```
- *
- */
- not: GenericAssertions<R>;
- /**
- * Compares value with
- * [`expected`](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-be-option-expected) by
- * calling `Object.is`. This method compares objects by reference instead of their contents, similarly to the strict
- * equality operator `===`.
- *
- * **Usage**
- *
- * ```js
- * const value = { prop: 1 };
- * expect(value).toBe(value);
- * expect(value).not.toBe({});
- * expect(value.prop).toBe(1);
- * ```
- *
- * @param expected Expected value.
- */
- toBe(expected: unknown): R;
- /**
- * Compares floating point numbers for approximate equality. Use this method instead of
- * [expect(value).toBe(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-be)
- * when comparing floating point numbers.
- *
- * **Usage**
- *
- * ```js
- * expect(0.1 + 0.2).not.toBe(0.3);
- * expect(0.1 + 0.2).toBeCloseTo(0.3, 5);
- * ```
- *
- * @param expected Expected value.
- * @param numDigits The number of decimal digits after the decimal point that must be equal.
- */
- toBeCloseTo(expected: number, numDigits?: number): R;
- /**
- * Ensures that value is not `undefined`.
- *
- * **Usage**
- *
- * ```js
- * const value = null;
- * expect(value).toBeDefined();
- * ```
- *
- */
- toBeDefined(): R;
- /**
- * Ensures that value is false in a boolean context, one of `false`, `0`, `''`, `null`, `undefined` or `NaN`. Use this
- * method when you don't care about the specific value.
- *
- * **Usage**
- *
- * ```js
- * const value = null;
- * expect(value).toBeFalsy();
- * ```
- *
- */
- toBeFalsy(): R;
- /**
- * Ensures that `value > expected` for number or big integer values.
- *
- * **Usage**
- *
- * ```js
- * const value = 42;
- * expect(value).toBeGreaterThan(1);
- * ```
- *
- * @param expected The value to compare to.
- */
- toBeGreaterThan(expected: number | bigint): R;
- /**
- * Ensures that `value >= expected` for number or big integer values.
- *
- * **Usage**
- *
- * ```js
- * const value = 42;
- * expect(value).toBeGreaterThanOrEqual(42);
- * ```
- *
- * @param expected The value to compare to.
- */
- toBeGreaterThanOrEqual(expected: number | bigint): R;
- /**
- * Ensures that value is an instance of a class. Uses `instanceof` operator.
- *
- * **Usage**
- *
- * ```js
- * expect(page).toBeInstanceOf(Page);
- *
- * class Example {}
- * expect(new Example()).toBeInstanceOf(Example);
- * ```
- *
- * @param expected The class or constructor function.
- */
- toBeInstanceOf(expected: Function): R;
- /**
- * Ensures that `value < expected` for number or big integer values.
- *
- * **Usage**
- *
- * ```js
- * const value = 42;
- * expect(value).toBeLessThan(100);
- * ```
- *
- * @param expected The value to compare to.
- */
- toBeLessThan(expected: number | bigint): R;
- /**
- * Ensures that `value <= expected` for number or big integer values.
- *
- * **Usage**
- *
- * ```js
- * const value = 42;
- * expect(value).toBeLessThanOrEqual(42);
- * ```
- *
- * @param expected The value to compare to.
- */
- toBeLessThanOrEqual(expected: number | bigint): R;
- /**
- * Ensures that value is `NaN`.
- *
- * **Usage**
- *
- * ```js
- * const value = NaN;
- * expect(value).toBeNaN();
- * ```
- *
- */
- toBeNaN(): R;
- /**
- * Ensures that value is `null`.
- *
- * **Usage**
- *
- * ```js
- * const value = null;
- * expect(value).toBeNull();
- * ```
- *
- */
- toBeNull(): R;
- /**
- * Ensures that value is true in a boolean context, **anything but** `false`, `0`, `''`, `null`, `undefined` or `NaN`.
- * Use this method when you don't care about the specific value.
- *
- * **Usage**
- *
- * ```js
- * const value = { example: 'value' };
- * expect(value).toBeTruthy();
- * ```
- *
- */
- toBeTruthy(): R;
- /**
- * Ensures that value is `undefined`.
+ * expect({ foo: 1, bar: 2 }).toEqual(expect.objectContaining({ foo: 1 }));
*
- * **Usage**
+ * // Matchers can be used on the properties as well.
+ * expect({ foo: 1, bar: 2 }).toEqual(expect.objectContaining({ bar: expect.any(Number) }));
*
- * ```js
- * const value = undefined;
- * expect(value).toBeUndefined();
+ * // Complex matching of sub-properties.
+ * expect({
+ * list: [1, 2, 3],
+ * obj: { prop: 'Hello world!', another: 'some other value' },
+ * extra: 'extra',
+ * }).toEqual(expect.objectContaining({
+ * list: expect.arrayContaining([2, 3]),
+ * obj: expect.objectContaining({ prop: expect.stringContaining('Hello') }),
+ * }));
* ```
*
+ * @param expected Expected object pattern that contains a subset of the properties.
*/
- toBeUndefined(): R;
+ objectContaining(sample: Record<string, unknown>): AsymmetricMatcher;
/**
- * Ensures that string value contains an expected substring. Comparison is case-sensitive.
+ * `expect.stringContaining()` matches a string that contains the expected substring. Use this method inside
+ * [expect(value).toEqual(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-equal)
+ * to perform pattern matching.
*
* **Usage**
*
* ```js
- * const value = 'Hello, World';
- * expect(value).toContain('World');
- * expect(value).toContain(',');
+ * expect('Hello world!').toEqual(expect.stringContaining('Hello'));
* ```
*
* @param expected Expected substring.
*/
- toContain(expected: string): R;
+ stringContaining(sample: string): AsymmetricMatcher;
/**
- * Ensures that value is an `Array` or `Set` and contains an expected item.
+ * `expect.stringMatching()` matches a received string that in turn matches the expected pattern. Use this method
+ * inside
+ * [expect(value).toEqual(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-equal)
+ * to perform pattern matching.
*
* **Usage**
*
* ```js
- * const value = [1, 2, 3];
- * expect(value).toContain(2);
- * expect(new Set(value)).toContain(2);
+ * expect('123ms').toEqual(expect.stringMatching(/\d+m?s/));
+ *
+ * // Inside another matcher.
+ * expect({
+ * status: 'passed',
+ * time: '123ms',
+ * }).toEqual({
+ * status: expect.stringMatching(/passed|failed/),
+ * time: expect.stringMatching(/\d+m?s/),
+ * });
* ```
*
- * @param expected Expected value in the collection.
+ * @param expected Pattern that expected string should match.
*/
- toContain(expected: unknown): R;
+ stringMatching(sample: string | RegExp): AsymmetricMatcher;
+}
+
+/**
+ * The [GenericAssertions](https://playwright.dev/docs/api/class-genericassertions) class provides assertion methods
+ * that can be used to make assertions about any values in the tests. A new instance of
+ * [GenericAssertions](https://playwright.dev/docs/api/class-genericassertions) is created by calling
+ * [expect(value)](https://playwright.dev/docs/api/class-playwrightassertions#playwright-assertions-expect-generic):
+ *
+ * ```js
+ * import { test, expect } from '@playwright/test';
+ *
+ * test('assert a value', async ({ page }) => {
+ * const value = 1;
+ * expect(value).toBe(2);
+ * });
+ * ```
+ *
+ */
+interface GenericAssertions<R> {
/**
- * Ensures that value is an `Array` or `Set` and contains an item equal to the expected.
- *
- * For objects, this method recursively checks equality of all fields, rather than comparing objects by reference as
- * performed by
- * [expect(value).toContain(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-contain-2).
- *
- * For primitive values, this method is equivalent to
- * [expect(value).toContain(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-contain-2).
- *
- * **Usage**
+ * Makes the assertion check for the opposite condition. For example, the following code passes:
*
* ```js
- * const value = [
- * { example: 1 },
- * { another: 2 },
- * { more: 3 },
- * ];
- * expect(value).toContainEqual({ another: 2 });
- * expect(new Set(value)).toContainEqual({ another: 2 });
+ * const value = 1;
+ * expect(value).not.toBe(2);
* ```
*
- * @param expected Expected value in the collection.
*/
- toContainEqual(expected: unknown): R;
+ not: GenericAssertions<R>;
/**
- * Compares contents of the value with contents of
- * [`expected`](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-equal-option-expected),
- * performing "deep equality" check.
- *
- * For objects, this method recursively checks equality of all fields, rather than comparing objects by reference as
- * performed by
- * [expect(value).toBe(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-be).
- *
- * For primitive values, this method is equivalent to
- * [expect(value).toBe(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-be).
+ * Compares value with
+ * [`expected`](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-be-option-expected) by
+ * calling `Object.is`. This method compares objects by reference instead of their contents, similarly to the strict
+ * equality operator `===`.
*
* **Usage**
*
* ```js
* const value = { prop: 1 };
- * expect(value).toEqual({ prop: 1 });
+ * expect(value).toBe(value);
+ * expect(value).not.toBe({});
+ * expect(value.prop).toBe(1);
* ```
*
- * **Non-strict equality**
- *
- * [expect(value).toEqual(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-equal)
- * performs deep equality check that compares contents of the received and expected values. To ensure two objects
- * reference the same instance, use
+ * @param expected Expected value.
+ */
+ toBe(expected: unknown): R;
+ /**
+ * Compares floating point numbers for approximate equality. Use this method instead of
* [expect(value).toBe(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-be)
- * instead.
- *
- * [expect(value).toEqual(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-equal)
- * ignores `undefined` properties and array items, and does not insist on object types being equal. For stricter
- * matching, use
- * [expect(value).toStrictEqual(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-strict-equal).
- *
- * **Pattern matching**
- *
- * [expect(value).toEqual(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-equal)
- * can be also used to perform pattern matching on objects, arrays and primitive types, with the help of the following
- * matchers:
- * - [expect(value).any(constructor)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-any)
- * - [expect(value).anything()](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-anything)
- * - [expect(value).arrayContaining(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-array-containing)
- * - [expect(value).closeTo(expected[, numDigits])](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-close-to)
- * - [expect(value).objectContaining(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-object-containing)
- * - [expect(value).stringContaining(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-string-containing)
- * - [expect(value).stringMatching(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-string-matching)
+ * when comparing floating point numbers.
*
- * Here is an example that asserts some of the values inside a complex object:
+ * **Usage**
*
* ```js
- * expect({
- * list: [1, 2, 3],
- * obj: { prop: 'Hello world!', another: 'some other value' },
- * extra: 'extra',
- * }).toEqual(expect.objectContaining({
- * list: expect.arrayContaining([2, 3]),
- * obj: expect.objectContaining({ prop: expect.stringContaining('Hello') }),
- * }));
+ * expect(0.1 + 0.2).not.toBe(0.3);
+ * expect(0.1 + 0.2).toBeCloseTo(0.3, 5);
* ```
*
* @param expected Expected value.
+ * @param numDigits The number of decimal digits after the decimal point that must be equal.
*/
- toEqual(expected: unknown): R;
+ toBeCloseTo(expected: number, numDigits?: number): R;
/**
- * Ensures that value has a `.length` property equal to
- * [`expected`](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-have-length-option-expected).
- * Useful for arrays and strings.
+ * Ensures that value is not `undefined`.
*
* **Usage**
*
* ```js
- * expect('Hello, World').toHaveLength(12);
- * expect([1, 2, 3]).toHaveLength(3);
+ * const value = null;
+ * expect(value).toBeDefined();
* ```
*
- * @param expected Expected length.
*/
- toHaveLength(expected: number): R;
+ toBeDefined(): R;
/**
- * Ensures that property at provided `keyPath` exists on the object and optionally checks that property is equal to
- * the
- * [`expected`](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-have-property-option-expected).
- * Equality is checked recursively, similarly to
- * [expect(value).toEqual(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-equal).
+ * Ensures that value is false in a boolean context, one of `false`, `0`, `''`, `null`, `undefined` or `NaN`. Use this
+ * method when you don't care about the specific value.
*
* **Usage**
*
* ```js
- * const value = {
- * a: {
- * b: [42],
- * },
- * c: true,
- * };
- * expect(value).toHaveProperty('a.b');
- * expect(value).toHaveProperty('a.b', [42]);
- * expect(value).toHaveProperty('a.b[0]', 42);
- * expect(value).toHaveProperty('c');
- * expect(value).toHaveProperty('c', true);
+ * const value = null;
+ * expect(value).toBeFalsy();
* ```
*
- * @param keyPath Path to the property. Use dot notation `a.b` to check nested properties and indexed `a[2]` notation to check nested
- * array items.
- * @param expected Optional expected value to compare the property to.
*/
- toHaveProperty(keyPath: string | Array<string>, value?: unknown): R;
+ toBeFalsy(): R;
/**
- * Ensures that string value matches a regular expression.
+ * Ensures that `value > expected` for number or big integer values.
*
* **Usage**
*
* ```js
- * const value = 'Is 42 enough?';
- * expect(value).toMatch(/Is \d+ enough/);
+ * const value = 42;
+ * expect(value).toBeGreaterThan(1);
* ```
*
- * @param expected Regular expression to match against.
+ * @param expected The value to compare to.
*/
- toMatch(expected: RegExp | string): R;
+ toBeGreaterThan(expected: number | bigint): R;
/**
- * Compares contents of the value with contents of
- * [`expected`](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-match-object-option-expected),
- * performing "deep equality" check. Allows extra properties to be present in the value, unlike
- * [expect(value).toEqual(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-equal),
- * so you can check just a subset of object properties.
- *
- * When comparing arrays, the number of items must match, and each item is checked recursively.
+ * Ensures that `value >= expected` for number or big integer values.
*
* **Usage**
*
* ```js
- * const value = {
- * a: 1,
- * b: 2,
- * c: true,
- * };
- * expect(value).toMatchObject({ a: 1, c: true });
- * expect(value).toMatchObject({ b: 2, c: true });
- *
- * expect([{ a: 1, b: 2 }]).toMatchObject([{ a: 1 }]);
+ * const value = 42;
+ * expect(value).toBeGreaterThanOrEqual(42);
* ```
*
- * @param expected The expected object value to match against.
+ * @param expected The value to compare to.
*/
- toMatchObject(expected: Record<string, unknown> | Array<unknown>): R;
+ toBeGreaterThanOrEqual(expected: number | bigint): R;
/**
- * Compares contents of the value with contents of
- * [`expected`](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-strict-equal-option-expected)
- * **and** their types.
- *
- * Differences from
- * [expect(value).toEqual(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-equal):
- * - Keys with undefined properties are checked. For example, `{ a: undefined, b: 2 }` does not match `{ b: 2 }`.
- * - Array sparseness is checked. For example, `[, 1]` does not match `[undefined, 1]`.
- * - Object types are checked to be equal. For example, a class instance with fields `a` and `b` will not equal a
- * literal object with fields `a` and `b`.
+ * Ensures that value is an instance of a class. Uses `instanceof` operator.
*
* **Usage**
*
* ```js
- * const value = { prop: 1 };
- * expect(value).toStrictEqual({ prop: 1 });
- * ```
+ * expect(page).toBeInstanceOf(Page);
*
- * @param expected Expected value.
- */
- toStrictEqual(expected: unknown): R;
- /**
- * Calls the function and ensures it throws an error.
+ * class Example {}
+ * expect(new Example()).toBeInstanceOf(Example);
+ * ```
*
- * Optionally compares the error with
- * [`expected`](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-throw-option-expected).
- * Allowed expected values:
- * - Regular expression - error message should **match** the pattern.
- * - String - error message should **include** the substring.
- * - Error object - error message should be **equal to** the message property of the object.
- * - Error class - error object should be an **instance of** the class.
+ * @param expected The class or constructor function.
+ */
+ toBeInstanceOf(expected: Function): R;
+ /**
+ * Ensures that `value < expected` for number or big integer values.
*
* **Usage**
*
* ```js
- * expect(() => {
- * throw new Error('Something bad');
- * }).toThrow();
- *
- * expect(() => {
- * throw new Error('Something bad');
- * }).toThrow(/something/);
- *
- * expect(() => {
- * throw new Error('Something bad');
- * }).toThrow(Error);
+ * const value = 42;
+ * expect(value).toBeLessThan(100);
* ```
*
- * @param expected Expected error message or error object.
+ * @param expected The value to compare to.
*/
- toThrow(error?: unknown): R;
+ toBeLessThan(expected: number | bigint): R;
/**
- * An alias for
- * [expect(value).toThrow([expected])](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-throw).
+ * Ensures that `value <= expected` for number or big integer values.
*
* **Usage**
*
* ```js
- * expect(() => {
- * throw new Error('Something bad');
- * }).toThrowError();
+ * const value = 42;
+ * expect(value).toBeLessThanOrEqual(42);
* ```
*
- * @param expected Expected error message or error object.
+ * @param expected The value to compare to.
*/
- toThrowError(error?: unknown): R;
-
-}
-
-type FunctionAssertions = {
+ toBeLessThanOrEqual(expected: number | bigint): R;
/**
- * Retries the callback until all assertions within it pass or the `timeout` value is reached.
- * The `intervals` parameter can be used to establish the probing frequency or pattern.
+ * Ensures that value is `NaN`.
*
* **Usage**
+ *
* ```js
- * await expect(async () => {
- * const response = await page.request.get('https://api.example.com');
- * expect(response.status()).toBe(200);
- * }).toPass({
- * // Probe, wait 1s, probe, wait 2s, probe, wait 10s, probe, wait 10s, probe
- * intervals: [1_000, 2_000, 10_000], // Defaults to [100, 250, 500, 1000].
- * timeout: 60_000 // Defaults to 0
- * });
+ * const value = NaN;
+ * expect(value).toBeNaN();
* ```
*
- * Note that by default `toPass` does not respect custom expect timeout.
- *
- * @param options
- */
- toPass(options?: { timeout?: number, intervals?: number[] }): Promise<void>;
-};
-
-type BaseMatchers<R, T> = GenericAssertions<R> & PlaywrightTest.Matchers<R, T> & SnapshotAssertions;
-type AllowedGenericMatchers<R, T> = PlaywrightTest.Matchers<R, T> & Pick<GenericAssertions<R>, 'toBe' | 'toBeDefined' | 'toBeFalsy' | 'toBeNull' | 'toBeTruthy' | 'toBeUndefined'>;
-
-type SpecificMatchers<R, T> =
- T extends Page ? PageAssertions & AllowedGenericMatchers<R, T> :
- T extends Locator ? LocatorAssertions & AllowedGenericMatchers<R, T> :
- T extends APIResponse ? APIResponseAssertions & AllowedGenericMatchers<R, T> :
- BaseMatchers<R, T> & (T extends Function ? FunctionAssertions : {});
-type AllMatchers<R, T> = PageAssertions & LocatorAssertions & APIResponseAssertions & FunctionAssertions & BaseMatchers<R, T>;
-
-type IfAny<T, Y, N> = 0 extends (1 & T) ? Y : N;
-type Awaited<T> = T extends PromiseLike<infer U> ? U : T;
-type ToUserMatcher<F, DefaultReturnType> = F extends (first: any, ...args: infer Rest) => infer R ? (...args: Rest) => (R extends PromiseLike<infer U> ? Promise<void> : DefaultReturnType) : never;
-type ToUserMatcherObject<T, DefaultReturnType, ArgType> = {
- [K in keyof T as T[K] extends (arg: ArgType, ...rest: any[]) => any ? K : never]: ToUserMatcher<T[K], DefaultReturnType>;
-};
-
-type MatcherHintColor = (arg: string) => string;
-
-export type MatcherHintOptions = {
- comment?: string;
- expectedColor?: MatcherHintColor;
- isDirectExpectCall?: boolean;
- isNot?: boolean;
- promise?: string;
- receivedColor?: MatcherHintColor;
- secondArgument?: string;
- secondArgumentColor?: MatcherHintColor;
-};
-
-export interface ExpectMatcherUtils {
- matcherHint(matcherName: string, received: unknown, expected: unknown, options?: MatcherHintOptions): string;
- printDiffOrStringify(expected: unknown, received: unknown, expectedLabel: string, receivedLabel: string, expand: boolean): string;
- printExpected(value: unknown): string;
- printReceived(object: unknown): string;
- printWithType<T>(name: string, value: T, print: (value: T) => string): string;
- diff(a: unknown, b: unknown): string | null;
- stringify(object: unknown, maxDepth?: number, maxWidth?: number): string;
-}
-
-export type ExpectMatcherState = {
- /**
- * Whether this matcher was called with the negated .not modifier.
- */
- isNot: boolean;
- /**
- * - 'rejects' if matcher was called with the promise .rejects modifier
- * - 'resolves' if matcher was called with the promise .resolves modifier
- * - '' if matcher was not called with a promise modifier
- */
- promise: 'rejects' | 'resolves' | '';
- utils: ExpectMatcherUtils;
- /**
- * Timeout in milliseconds for the assertion to be fulfilled.
- */
- timeout: number;
-};
-
-export type MatcherReturnType = {
- message: () => string;
- pass: boolean;
- name?: string;
- expected?: unknown;
- actual?: any;
- log?: string[];
- timeout?: number;
-};
-
-type MakeMatchers<R, T, ExtendedMatchers> = {
- /**
- * If you know how to test something, `.not` lets you test its opposite.
- */
- not: MakeMatchers<R, T, ExtendedMatchers>;
- /**
- * Use resolves to unwrap the value of a fulfilled promise so any other
- * matcher can be chained. If the promise is rejected the assertion fails.
- */
- resolves: MakeMatchers<Promise<R>, Awaited<T>, ExtendedMatchers>;
- /**
- * Unwraps the reason of a rejected promise so any other matcher can be chained.
- * If the promise is fulfilled the assertion fails.
*/
- rejects: MakeMatchers<Promise<R>, any, ExtendedMatchers>;
-} & IfAny<T, AllMatchers<R, T>, SpecificMatchers<R, T> & ToUserMatcherObject<ExtendedMatchers, R, T>>;
-
-type PollMatchers<R, T, ExtendedMatchers> = {
+ toBeNaN(): R;
/**
- * If you know how to test something, `.not` lets you test its opposite.
+ * Ensures that value is `null`.
+ *
+ * **Usage**
+ *
+ * ```js
+ * const value = null;
+ * expect(value).toBeNull();
+ * ```
+ *
*/
- not: PollMatchers<R, T, ExtendedMatchers>;
-} & BaseMatchers<R, T> & ToUserMatcherObject<ExtendedMatchers, R, T>;
-
-export type Expect<ExtendedMatchers = {}> = {
- <T = unknown>(actual: T, messageOrOptions?: string | { message?: string }): MakeMatchers<void, T, ExtendedMatchers>;
- soft: <T = unknown>(actual: T, messageOrOptions?: string | { message?: string }) => MakeMatchers<void, T, ExtendedMatchers>;
- poll: <T = unknown>(actual: () => T | Promise<T>, messageOrOptions?: string | { message?: string, timeout?: number, intervals?: number[] }) => PollMatchers<Promise<void>, T, ExtendedMatchers>;
- extend<MoreMatchers extends Record<string, (this: ExpectMatcherState, receiver: any, ...args: any[]) => MatcherReturnType | Promise<MatcherReturnType>>>(matchers: MoreMatchers): Expect<ExtendedMatchers & MoreMatchers>;
- configure: (configuration: {
- message?: string,
- timeout?: number,
- soft?: boolean,
- }) => Expect<ExtendedMatchers>;
- getState(): unknown;
- not: Omit<AsymmetricMatchers, 'any' | 'anything'>;
-} & AsymmetricMatchers;
-
-// --- BEGINGLOBAL ---
-declare global {
- export namespace PlaywrightTest {
- export interface Matchers<R, T = unknown> {
- }
- }
-}
-// --- ENDGLOBAL ---
-
-/**
- * These tests are executed in Playwright environment that launches the browser
- * and provides a fresh page to each test.
- */
-export const test: TestType<PlaywrightTestArgs & PlaywrightTestOptions, PlaywrightWorkerArgs & PlaywrightWorkerOptions>;
-export default test;
-
-export const _baseTest: TestType<{}, {}>;
-export const expect: Expect<{}>;
-
-/**
- * Defines Playwright config
- */
-export function defineConfig(config: PlaywrightTestConfig): PlaywrightTestConfig;
-export function defineConfig<T>(config: PlaywrightTestConfig<T>): PlaywrightTestConfig<T>;
-export function defineConfig<T, W>(config: PlaywrightTestConfig<T, W>): PlaywrightTestConfig<T, W>;
-export function defineConfig(config: PlaywrightTestConfig, ...configs: PlaywrightTestConfig[]): PlaywrightTestConfig;
-export function defineConfig<T>(config: PlaywrightTestConfig<T>, ...configs: PlaywrightTestConfig<T>[]): PlaywrightTestConfig<T>;
-export function defineConfig<T, W>(config: PlaywrightTestConfig<T, W>, ...configs: PlaywrightTestConfig<T, W>[]): PlaywrightTestConfig<T, W>;
-
-type MergedT<List> = List extends [TestType<infer T, any>, ...(infer Rest)] ? T & MergedT<Rest> : {};
-type MergedW<List> = List extends [TestType<any, infer W>, ...(infer Rest)] ? W & MergedW<Rest> : {};
-type MergedTestType<List> = TestType<MergedT<List>, MergedW<List>>;
-
-/**
- * Merges fixtures
- */
-export function mergeTests<List extends any[]>(...tests: List): MergedTestType<List>;
-
-type MergedExpectMatchers<List> = List extends [Expect<infer M>, ...(infer Rest)] ? M & MergedExpectMatchers<Rest> : {};
-type MergedExpect<List> = Expect<MergedExpectMatchers<List>>;
-
-/**
- * Merges expects
- */
-export function mergeExpects<List extends any[]>(...expects: List): MergedExpect<List>;
-
-// This is required to not export everything by default. See https://github.com/Microsoft/TypeScript/issues/19545#issuecomment-340490459
-export { };
-
-
-
-/**
- * The [APIResponseAssertions](https://playwright.dev/docs/api/class-apiresponseassertions) class provides assertion
- * methods that can be used to make assertions about the
- * [APIResponse](https://playwright.dev/docs/api/class-apiresponse) in the tests.
- *
- * ```js
- * import { test, expect } from '@playwright/test';
- *
- * test('navigates to login', async ({ page }) => {
- * // ...
- * const response = await page.request.get('https://playwright.dev');
- * await expect(response).toBeOK();
- * });
- * ```
- *
- */
-interface APIResponseAssertions {
+ toBeNull(): R;
/**
- * Ensures the response status code is within `200..299` range.
+ * Ensures that value is true in a boolean context, **anything but** `false`, `0`, `''`, `null`, `undefined` or `NaN`.
+ * Use this method when you don't care about the specific value.
*
* **Usage**
*
* ```js
- * await expect(response).toBeOK();
+ * const value = { example: 'value' };
+ * expect(value).toBeTruthy();
* ```
*
*/
- toBeOK(): Promise<void>;
-
+ toBeTruthy(): R;
/**
- * Makes the assertion check for the opposite condition. For example, this code tests that the response status is not
- * successful:
+ * Ensures that value is `undefined`.
+ *
+ * **Usage**
*
* ```js
- * await expect(response).not.toBeOK();
+ * const value = undefined;
+ * expect(value).toBeUndefined();
* ```
*
*/
- not: APIResponseAssertions;
-}
-
-/**
- * The [LocatorAssertions](https://playwright.dev/docs/api/class-locatorassertions) class provides assertion methods
- * that can be used to make assertions about the [Locator](https://playwright.dev/docs/api/class-locator) state in the
- * tests.
- *
- * ```js
- * import { test, expect } from '@playwright/test';
- *
- * test('status becomes submitted', async ({ page }) => {
- * // ...
- * await page.getByRole('button').click();
- * await expect(page.locator('.status')).toHaveText('Submitted');
- * });
- * ```
- *
- */
-interface LocatorAssertions {
+ toBeUndefined(): R;
/**
- * Ensures that [Locator](https://playwright.dev/docs/api/class-locator) points to an element that is
- * [connected](https://developer.mozilla.org/en-US/docs/Web/API/Node/isConnected) to a Document or a ShadowRoot.
+ * Ensures that string value contains an expected substring. Comparison is case-sensitive.
*
* **Usage**
*
* ```js
- * await expect(page.getByText('Hidden text')).toBeAttached();
+ * const value = 'Hello, World';
+ * expect(value).toContain('World');
+ * expect(value).toContain(',');
* ```
*
- * @param options
+ * @param expected Expected substring.
*/
- toBeAttached(options?: {
- attached?: boolean;
-
- /**
- * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
- */
- timeout?: number;
- }): Promise<void>;
-
+ toContain(expected: string): R;
/**
- * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to a checked input.
+ * Ensures that value is an `Array` or `Set` and contains an expected item.
*
* **Usage**
*
* ```js
- * const locator = page.getByLabel('Subscribe to newsletter');
- * await expect(locator).toBeChecked();
+ * const value = [1, 2, 3];
+ * expect(value).toContain(2);
+ * expect(new Set(value)).toContain(2);
* ```
*
- * @param options
+ * @param expected Expected value in the collection.
*/
- toBeChecked(options?: {
- /**
- * Provides state to assert for. Asserts for input to be checked by default. This option can't be used when
- * [`indeterminate`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-be-checked-option-indeterminate)
- * is set to true.
- */
- checked?: boolean;
-
- /**
- * Asserts that the element is in the indeterminate (mixed) state. Only supported for checkboxes and radio buttons.
- * This option can't be true when
- * [`checked`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-be-checked-option-checked)
- * is provided.
- */
- indeterminate?: boolean;
-
- /**
- * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
- */
- timeout?: number;
- }): Promise<void>;
-
+ toContain(expected: unknown): R;
/**
- * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to a disabled element. Element is
- * disabled if it has "disabled" attribute or is disabled via
- * ['aria-disabled'](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-disabled). Note
- * that only native control elements such as HTML `button`, `input`, `select`, `textarea`, `option`, `optgroup` can be
- * disabled by setting "disabled" attribute. "disabled" attribute on other elements is ignored by the browser.
+ * Ensures that value is an `Array` or `Set` and contains an item equal to the expected.
+ *
+ * For objects, this method recursively checks equality of all fields, rather than comparing objects by reference as
+ * performed by
+ * [expect(value).toContain(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-contain-2).
+ *
+ * For primitive values, this method is equivalent to
+ * [expect(value).toContain(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-contain-2).
*
* **Usage**
*
* ```js
- * const locator = page.locator('button.submit');
- * await expect(locator).toBeDisabled();
+ * const value = [
+ * { example: 1 },
+ * { another: 2 },
+ * { more: 3 },
+ * ];
+ * expect(value).toContainEqual({ another: 2 });
+ * expect(new Set(value)).toContainEqual({ another: 2 });
* ```
*
- * @param options
+ * @param expected Expected value in the collection.
*/
- toBeDisabled(options?: {
- /**
- * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
- */
- timeout?: number;
- }): Promise<void>;
-
+ toContainEqual(expected: unknown): R;
/**
- * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an editable element.
+ * Compares contents of the value with contents of
+ * [`expected`](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-equal-option-expected),
+ * performing "deep equality" check.
+ *
+ * For objects, this method recursively checks equality of all fields, rather than comparing objects by reference as
+ * performed by
+ * [expect(value).toBe(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-be).
+ *
+ * For primitive values, this method is equivalent to
+ * [expect(value).toBe(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-be).
*
* **Usage**
*
* ```js
- * const locator = page.getByRole('textbox');
- * await expect(locator).toBeEditable();
+ * const value = { prop: 1 };
+ * expect(value).toEqual({ prop: 1 });
* ```
*
- * @param options
+ * **Non-strict equality**
+ *
+ * [expect(value).toEqual(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-equal)
+ * performs deep equality check that compares contents of the received and expected values. To ensure two objects
+ * reference the same instance, use
+ * [expect(value).toBe(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-be)
+ * instead.
+ *
+ * [expect(value).toEqual(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-equal)
+ * ignores `undefined` properties and array items, and does not insist on object types being equal. For stricter
+ * matching, use
+ * [expect(value).toStrictEqual(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-strict-equal).
+ *
+ * **Pattern matching**
+ *
+ * [expect(value).toEqual(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-equal)
+ * can be also used to perform pattern matching on objects, arrays and primitive types, with the help of the following
+ * matchers:
+ * - [expect(value).any(constructor)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-any)
+ * - [expect(value).anything()](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-anything)
+ * - [expect(value).arrayContaining(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-array-containing)
+ * - [expect(value).closeTo(expected[, numDigits])](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-close-to)
+ * - [expect(value).objectContaining(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-object-containing)
+ * - [expect(value).stringContaining(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-string-containing)
+ * - [expect(value).stringMatching(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-string-matching)
+ *
+ * Here is an example that asserts some of the values inside a complex object:
+ *
+ * ```js
+ * expect({
+ * list: [1, 2, 3],
+ * obj: { prop: 'Hello world!', another: 'some other value' },
+ * extra: 'extra',
+ * }).toEqual(expect.objectContaining({
+ * list: expect.arrayContaining([2, 3]),
+ * obj: expect.objectContaining({ prop: expect.stringContaining('Hello') }),
+ * }));
+ * ```
+ *
+ * @param expected Expected value.
*/
- toBeEditable(options?: {
- editable?: boolean;
-
- /**
- * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
- */
- timeout?: number;
- }): Promise<void>;
-
+ toEqual(expected: unknown): R;
/**
- * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an empty editable element or to a
- * DOM node that has no text.
+ * Ensures that value has a `.length` property equal to
+ * [`expected`](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-have-length-option-expected).
+ * Useful for arrays and strings.
*
* **Usage**
*
* ```js
- * const locator = page.locator('div.warning');
- * await expect(locator).toBeEmpty();
+ * expect('Hello, World').toHaveLength(12);
+ * expect([1, 2, 3]).toHaveLength(3);
* ```
*
- * @param options
+ * @param expected Expected length.
*/
- toBeEmpty(options?: {
- /**
- * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
- */
- timeout?: number;
- }): Promise<void>;
-
+ toHaveLength(expected: number): R;
/**
- * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an enabled element.
+ * Ensures that property at provided `keyPath` exists on the object and optionally checks that property is equal to
+ * the
+ * [`expected`](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-have-property-option-expected).
+ * Equality is checked recursively, similarly to
+ * [expect(value).toEqual(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-equal).
*
* **Usage**
*
* ```js
- * const locator = page.locator('button.submit');
- * await expect(locator).toBeEnabled();
+ * const value = {
+ * a: {
+ * b: [42],
+ * },
+ * c: true,
+ * };
+ * expect(value).toHaveProperty('a.b');
+ * expect(value).toHaveProperty('a.b', [42]);
+ * expect(value).toHaveProperty('a.b[0]', 42);
+ * expect(value).toHaveProperty('c');
+ * expect(value).toHaveProperty('c', true);
* ```
*
- * @param options
+ * @param keyPath Path to the property. Use dot notation `a.b` to check nested properties and indexed `a[2]` notation to check nested
+ * array items.
+ * @param expected Optional expected value to compare the property to.
*/
- toBeEnabled(options?: {
- enabled?: boolean;
-
- /**
- * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
- */
- timeout?: number;
- }): Promise<void>;
-
+ toHaveProperty(keyPath: string | Array<string>, value?: unknown): R;
/**
- * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to a focused DOM node.
+ * Ensures that string value matches a regular expression.
*
* **Usage**
*
* ```js
- * const locator = page.getByRole('textbox');
- * await expect(locator).toBeFocused();
+ * const value = 'Is 42 enough?';
+ * expect(value).toMatch(/Is \d+ enough/);
* ```
*
- * @param options
+ * @param expected Regular expression to match against.
*/
- toBeFocused(options?: {
- /**
- * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
- */
- timeout?: number;
- }): Promise<void>;
-
+ toMatch(expected: RegExp | string): R;
/**
- * Ensures that [Locator](https://playwright.dev/docs/api/class-locator) either does not resolve to any DOM node, or
- * resolves to a [non-visible](https://playwright.dev/docs/actionability#visible) one.
+ * Compares contents of the value with contents of
+ * [`expected`](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-match-object-option-expected),
+ * performing "deep equality" check. Allows extra properties to be present in the value, unlike
+ * [expect(value).toEqual(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-equal),
+ * so you can check just a subset of object properties.
+ *
+ * When comparing arrays, the number of items must match, and each item is checked recursively.
*
* **Usage**
*
* ```js
- * const locator = page.locator('.my-element');
- * await expect(locator).toBeHidden();
+ * const value = {
+ * a: 1,
+ * b: 2,
+ * c: true,
+ * };
+ * expect(value).toMatchObject({ a: 1, c: true });
+ * expect(value).toMatchObject({ b: 2, c: true });
+ *
+ * expect([{ a: 1, b: 2 }]).toMatchObject([{ a: 1 }]);
* ```
*
- * @param options
+ * @param expected The expected object value to match against.
*/
- toBeHidden(options?: {
- /**
- * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
- */
- timeout?: number;
- }): Promise<void>;
-
+ toMatchObject(expected: Record<string, unknown> | Array<unknown>): R;
/**
- * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an element that intersects viewport,
- * according to the
- * [intersection observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API).
+ * Compares contents of the value with contents of
+ * [`expected`](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-strict-equal-option-expected)
+ * **and** their types.
+ *
+ * Differences from
+ * [expect(value).toEqual(expected)](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-equal):
+ * - Keys with undefined properties are checked. For example, `{ a: undefined, b: 2 }` does not match `{ b: 2 }`.
+ * - Array sparseness is checked. For example, `[, 1]` does not match `[undefined, 1]`.
+ * - Object types are checked to be equal. For example, a class instance with fields `a` and `b` will not equal a
+ * literal object with fields `a` and `b`.
*
* **Usage**
*
* ```js
- * const locator = page.getByRole('button');
- * // Make sure at least some part of element intersects viewport.
- * await expect(locator).toBeInViewport();
- * // Make sure element is fully outside of viewport.
- * await expect(locator).not.toBeInViewport();
- * // Make sure that at least half of the element intersects viewport.
- * await expect(locator).toBeInViewport({ ratio: 0.5 });
+ * const value = { prop: 1 };
+ * expect(value).toStrictEqual({ prop: 1 });
* ```
*
- * @param options
+ * @param expected Expected value.
*/
- toBeInViewport(options?: {
- /**
- * The minimal ratio of the element to intersect viewport. If equals to `0`, then element should intersect viewport at
- * any positive ratio. Defaults to `0`.
- */
- ratio?: number;
-
- /**
- * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
- */
- timeout?: number;
- }): Promise<void>;
-
+ toStrictEqual(expected: unknown): R;
/**
- * Ensures that [Locator](https://playwright.dev/docs/api/class-locator) points to an attached and
- * [visible](https://playwright.dev/docs/actionability#visible) DOM node.
+ * Calls the function and ensures it throws an error.
*
- * To check that at least one element from the list is visible, use
- * [locator.first()](https://playwright.dev/docs/api/class-locator#locator-first).
+ * Optionally compares the error with
+ * [`expected`](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-throw-option-expected).
+ * Allowed expected values:
+ * - Regular expression - error message should **match** the pattern.
+ * - String - error message should **include** the substring.
+ * - Error object - error message should be **equal to** the message property of the object.
+ * - Error class - error object should be an **instance of** the class.
*
* **Usage**
*
* ```js
- * // A specific element is visible.
- * await expect(page.getByText('Welcome')).toBeVisible();
+ * expect(() => {
+ * throw new Error('Something bad');
+ * }).toThrow();
*
- * // At least one item in the list is visible.
- * await expect(page.getByTestId('todo-item').first()).toBeVisible();
+ * expect(() => {
+ * throw new Error('Something bad');
+ * }).toThrow(/something/);
*
- * // At least one of the two elements is visible, possibly both.
- * await expect(
- * page.getByRole('button', { name: 'Sign in' })
- * .or(page.getByRole('button', { name: 'Sign up' }))
- * .first()
- * ).toBeVisible();
+ * expect(() => {
+ * throw new Error('Something bad');
+ * }).toThrow(Error);
* ```
*
- * @param options
+ * @param expected Expected error message or error object.
*/
- toBeVisible(options?: {
- /**
- * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
- */
- timeout?: number;
-
- visible?: boolean;
- }): Promise<void>;
-
+ toThrow(error?: unknown): R;
/**
- * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an element with given CSS classes.
- * All classes from the asserted value, separated by spaces, must be present in the
- * [Element.classList](https://developer.mozilla.org/en-US/docs/Web/API/Element/classList) in any order.
+ * An alias for
+ * [expect(value).toThrow([expected])](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-throw).
*
* **Usage**
*
- * ```html
- * <div class='middle selected row' id='component'></div>
- * ```
- *
- * ```js
- * const locator = page.locator('#component');
- * await expect(locator).toContainClass('middle selected row');
- * await expect(locator).toContainClass('selected');
- * await expect(locator).toContainClass('row middle');
- * ```
- *
- * When an array is passed, the method asserts that the list of elements located matches the corresponding list of
- * expected class lists. Each element's class attribute is matched against the corresponding class in the array:
- *
- * ```html
- * <div class='list'></div>
- * <div class='component inactive'></div>
- * <div class='component active'></div>
- * <div class='component inactive'></div>
- * </div>
- * ```
- *
* ```js
- * const locator = page.locator('list > .component');
- * await expect(locator).toContainClass(['inactive', 'active', 'inactive']);
+ * expect(() => {
+ * throw new Error('Something bad');
+ * }).toThrowError();
* ```
*
- * @param expected A string containing expected class names, separated by spaces, or a list of such strings to assert multiple
- * elements.
- * @param options
+ * @param expected Expected error message or error object.
*/
- toContainClass(expected: string|ReadonlyArray<string>, options?: {
- /**
- * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
- */
- timeout?: number;
- }): Promise<void>;
+ toThrowError(error?: unknown): R;
+
+}
+type FunctionAssertions = {
/**
- * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an element that contains the given
- * text. All nested elements will be considered when computing the text content of the element. You can use regular
- * expressions for the value as well.
- *
- * **Details**
- *
- * When `expected` parameter is a string, Playwright will normalize whitespaces and line breaks both in the actual
- * text and in the expected string before matching. When regular expression is used, the actual text is matched as is.
+ * Retries the callback until all assertions within it pass or the `timeout` value is reached.
+ * The `intervals` parameter can be used to establish the probing frequency or pattern.
*
* **Usage**
- *
* ```js
- * const locator = page.locator('.title');
- * await expect(locator).toContainText('substring');
- * await expect(locator).toContainText(/\d messages/);
- * ```
- *
- * If you pass an array as an expected value, the expectations are:
- * 1. Locator resolves to a list of elements.
- * 1. Elements from a **subset** of this list contain text from the expected array, respectively.
- * 1. The matching subset of elements has the same order as the expected array.
- * 1. Each text value from the expected array is matched by some element from the list.
- *
- * For example, consider the following list:
- *
- * ```html
- * <ul>
- * <li>Item Text 1</li>
- * <li>Item Text 2</li>
- * <li>Item Text 3</li>
- * </ul>
+ * await expect(async () => {
+ * const response = await page.request.get('https://api.example.com');
+ * expect(response.status()).toBe(200);
+ * }).toPass({
+ * // Probe, wait 1s, probe, wait 2s, probe, wait 10s, probe, wait 10s, probe
+ * intervals: [1_000, 2_000, 10_000], // Defaults to [100, 250, 500, 1000].
+ * timeout: 60_000 // Defaults to 0
+ * });
* ```
*
- * Let's see how we can use the assertion:
- *
- * ```js
- * // ✓ Contains the right items in the right order
- * await expect(page.locator('ul > li')).toContainText(['Text 1', 'Text 3']);
- *
- * // ✖ Wrong order
- * await expect(page.locator('ul > li')).toContainText(['Text 3', 'Text 2']);
- *
- * // ✖ No item contains this text
- * await expect(page.locator('ul > li')).toContainText(['Some 33']);
- *
- * // ✖ Locator points to the outer list element, not to the list items
- * await expect(page.locator('ul')).toContainText(['Text 3']);
- * ```
+ * Note that by default `toPass` does not respect custom expect timeout.
*
- * @param expected Expected substring or RegExp or a list of those.
* @param options
*/
- toContainText(expected: string|RegExp|ReadonlyArray<string|RegExp>, options?: {
- /**
- * Whether to perform case-insensitive match.
- * [`ignoreCase`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-contain-text-option-ignore-case)
- * option takes precedence over the corresponding regular expression flag if specified.
- */
- ignoreCase?: boolean;
+ toPass(options?: { timeout?: number, intervals?: number[] }): Promise<void>;
+};
+
+type BaseMatchers<R, T> = GenericAssertions<R> & PlaywrightTest.Matchers<R, T> & SnapshotAssertions;
+type AllowedGenericMatchers<R, T> = PlaywrightTest.Matchers<R, T> & Pick<GenericAssertions<R>, 'toBe' | 'toBeDefined' | 'toBeFalsy' | 'toBeNull' | 'toBeTruthy' | 'toBeUndefined'>;
+
+type SpecificMatchers<R, T> =
+ T extends Page ? PageAssertions & AllowedGenericMatchers<R, T> :
+ T extends Locator ? LocatorAssertions & AllowedGenericMatchers<R, T> :
+ T extends APIResponse ? APIResponseAssertions & AllowedGenericMatchers<R, T> :
+ BaseMatchers<R, T> & (T extends Function ? FunctionAssertions : {});
+type AllMatchers<R, T> = PageAssertions & LocatorAssertions & APIResponseAssertions & FunctionAssertions & BaseMatchers<R, T>;
+
+type IfAny<T, Y, N> = 0 extends (1 & T) ? Y : N;
+type Awaited<T> = T extends PromiseLike<infer U> ? U : T;
+type ToUserMatcher<F, DefaultReturnType> = F extends (first: any, ...args: infer Rest) => infer R ? (...args: Rest) => (R extends PromiseLike<infer U> ? Promise<void> : DefaultReturnType) : never;
+type ToUserMatcherObject<T, DefaultReturnType, ArgType> = {
+ [K in keyof T as T[K] extends (arg: ArgType, ...rest: any[]) => any ? K : never]: ToUserMatcher<T[K], DefaultReturnType>;
+};
+
+type MatcherHintColor = (arg: string) => string;
+
+export type MatcherHintOptions = {
+ comment?: string;
+ expectedColor?: MatcherHintColor;
+ isDirectExpectCall?: boolean;
+ isNot?: boolean;
+ promise?: string;
+ receivedColor?: MatcherHintColor;
+ secondArgument?: string;
+ secondArgumentColor?: MatcherHintColor;
+};
+
+export interface ExpectMatcherUtils {
+ matcherHint(matcherName: string, received: unknown, expected: unknown, options?: MatcherHintOptions): string;
+ printDiffOrStringify(expected: unknown, received: unknown, expectedLabel: string, receivedLabel: string, expand: boolean): string;
+ printExpected(value: unknown): string;
+ printReceived(object: unknown): string;
+ printWithType<T>(name: string, value: T, print: (value: T) => string): string;
+ diff(a: unknown, b: unknown): string | null;
+ stringify(object: unknown, maxDepth?: number, maxWidth?: number): string;
+}
+
+export type ExpectMatcherState = {
+ /**
+ * Whether this matcher was called with the negated .not modifier.
+ */
+ isNot: boolean;
+ /**
+ * - 'rejects' if matcher was called with the promise .rejects modifier
+ * - 'resolves' if matcher was called with the promise .resolves modifier
+ * - '' if matcher was not called with a promise modifier
+ */
+ promise: 'rejects' | 'resolves' | '';
+ utils: ExpectMatcherUtils;
+ /**
+ * Timeout in milliseconds for the assertion to be fulfilled.
+ */
+ timeout: number;
+};
+
+export type MatcherReturnType = {
+ message: () => string;
+ pass: boolean;
+ name?: string;
+ expected?: unknown;
+ actual?: any;
+ log?: string[];
+ timeout?: number;
+};
+
+type MakeMatchers<R, T, ExtendedMatchers> = {
+ /**
+ * If you know how to test something, `.not` lets you test its opposite.
+ */
+ not: MakeMatchers<R, T, ExtendedMatchers>;
+ /**
+ * Use resolves to unwrap the value of a fulfilled promise so any other
+ * matcher can be chained. If the promise is rejected the assertion fails.
+ */
+ resolves: MakeMatchers<Promise<R>, Awaited<T>, ExtendedMatchers>;
+ /**
+ * Unwraps the reason of a rejected promise so any other matcher can be chained.
+ * If the promise is fulfilled the assertion fails.
+ */
+ rejects: MakeMatchers<Promise<R>, any, ExtendedMatchers>;
+} & IfAny<T, AllMatchers<R, T>, SpecificMatchers<R, T> & ToUserMatcherObject<ExtendedMatchers, R, T>>;
+
+type PollMatchers<R, T, ExtendedMatchers> = {
+ /**
+ * If you know how to test something, `.not` lets you test its opposite.
+ */
+ not: PollMatchers<R, T, ExtendedMatchers>;
+} & BaseMatchers<R, T> & ToUserMatcherObject<ExtendedMatchers, R, T>;
+
+export type Expect<ExtendedMatchers = {}> = {
+ <T = unknown>(actual: T, messageOrOptions?: string | { message?: string }): MakeMatchers<void, T, ExtendedMatchers>;
+ soft: <T = unknown>(actual: T, messageOrOptions?: string | { message?: string }) => MakeMatchers<void, T, ExtendedMatchers>;
+ poll: <T = unknown>(actual: () => T | Promise<T>, messageOrOptions?: string | { message?: string, timeout?: number, intervals?: number[] }) => PollMatchers<Promise<void>, T, ExtendedMatchers>;
+ extend<MoreMatchers extends Record<string, (this: ExpectMatcherState, receiver: any, ...args: any[]) => MatcherReturnType | Promise<MatcherReturnType>>>(matchers: MoreMatchers): Expect<ExtendedMatchers & MoreMatchers>;
+ configure: (configuration: {
+ message?: string,
+ timeout?: number,
+ soft?: boolean,
+ }) => Expect<ExtendedMatchers>;
+ getState(): unknown;
+ not: Omit<AsymmetricMatchers, 'any' | 'anything'>;
+} & AsymmetricMatchers;
+
+// --- BEGINGLOBAL ---
+declare global {
+ export namespace PlaywrightTest {
+ export interface Matchers<R, T = unknown> {
+ }
+ }
+}
+// --- ENDGLOBAL ---
+
+/**
+ * These tests are executed in Playwright environment that launches the browser
+ * and provides a fresh page to each test.
+ */
+export const test: TestType<PlaywrightTestArgs & PlaywrightTestOptions, PlaywrightWorkerArgs & PlaywrightWorkerOptions>;
+export default test;
+
+export const _baseTest: TestType<{}, {}>;
+export const expect: Expect<{}>;
+
+/**
+ * Defines Playwright config
+ */
+export function defineConfig(config: PlaywrightTestConfig): PlaywrightTestConfig;
+export function defineConfig<T>(config: PlaywrightTestConfig<T>): PlaywrightTestConfig<T>;
+export function defineConfig<T, W>(config: PlaywrightTestConfig<T, W>): PlaywrightTestConfig<T, W>;
+export function defineConfig(config: PlaywrightTestConfig, ...configs: PlaywrightTestConfig[]): PlaywrightTestConfig;
+export function defineConfig<T>(config: PlaywrightTestConfig<T>, ...configs: PlaywrightTestConfig<T>[]): PlaywrightTestConfig<T>;
+export function defineConfig<T, W>(config: PlaywrightTestConfig<T, W>, ...configs: PlaywrightTestConfig<T, W>[]): PlaywrightTestConfig<T, W>;
+
+type MergedT<List> = List extends [TestType<infer T, any>, ...(infer Rest)] ? T & MergedT<Rest> : {};
+type MergedW<List> = List extends [TestType<any, infer W>, ...(infer Rest)] ? W & MergedW<Rest> : {};
+type MergedTestType<List> = TestType<MergedT<List>, MergedW<List>>;
+
+/**
+ * Merges fixtures
+ */
+export function mergeTests<List extends any[]>(...tests: List): MergedTestType<List>;
+
+type MergedExpectMatchers<List> = List extends [Expect<infer M>, ...(infer Rest)] ? M & MergedExpectMatchers<Rest> : {};
+type MergedExpect<List> = Expect<MergedExpectMatchers<List>>;
+
+/**
+ * Merges expects
+ */
+export function mergeExpects<List extends any[]>(...expects: List): MergedExpect<List>;
+
+// This is required to not export everything by default. See https://github.com/Microsoft/TypeScript/issues/19545#issuecomment-340490459
+export { };
- /**
- * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
- */
- timeout?: number;
- /**
- * Whether to use `element.innerText` instead of `element.textContent` when retrieving DOM node text.
- */
- useInnerText?: boolean;
- }): Promise<void>;
+/**
+ * The [APIResponseAssertions](https://playwright.dev/docs/api/class-apiresponseassertions) class provides assertion
+ * methods that can be used to make assertions about the
+ * [APIResponse](https://playwright.dev/docs/api/class-apiresponse) in the tests.
+ *
+ * ```js
+ * import { test, expect } from '@playwright/test';
+ *
+ * test('navigates to login', async ({ page }) => {
+ * // ...
+ * const response = await page.request.get('https://playwright.dev');
+ * await expect(response).toBeOK();
+ * });
+ * ```
+ *
+ */
+interface APIResponseAssertions {
/**
- * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an element with a given
- * [accessible description](https://w3c.github.io/accname/#dfn-accessible-description).
+ * Ensures the response status code is within `200..299` range.
*
* **Usage**
*
* ```js
- * const locator = page.getByTestId('save-button');
- * await expect(locator).toHaveAccessibleDescription('Save results to disk');
+ * await expect(response).toBeOK();
* ```
*
- * @param description Expected accessible description.
- * @param options
*/
- toHaveAccessibleDescription(description: string|RegExp, options?: {
- /**
- * Whether to perform case-insensitive match.
- * [`ignoreCase`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-accessible-description-option-ignore-case)
- * option takes precedence over the corresponding regular expression flag if specified.
- */
- ignoreCase?: boolean;
-
- /**
- * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
- */
- timeout?: number;
- }): Promise<void>;
+ toBeOK(): Promise<void>;
/**
- * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an element with a given
- * [aria errormessage](https://w3c.github.io/aria/#aria-errormessage).
- *
- * **Usage**
+ * Makes the assertion check for the opposite condition. For example, this code tests that the response status is not
+ * successful:
*
* ```js
- * const locator = page.getByTestId('username-input');
- * await expect(locator).toHaveAccessibleErrorMessage('Username is required.');
+ * await expect(response).not.toBeOK();
* ```
*
- * @param errorMessage Expected accessible error message.
- * @param options
*/
- toHaveAccessibleErrorMessage(errorMessage: string|RegExp, options?: {
- /**
- * Whether to perform case-insensitive match.
- * [`ignoreCase`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-accessible-error-message-option-ignore-case)
- * option takes precedence over the corresponding regular expression flag if specified.
- */
- ignoreCase?: boolean;
-
- /**
- * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
- */
- timeout?: number;
- }): Promise<void>;
+ not: APIResponseAssertions;
+}
+/**
+ * The [LocatorAssertions](https://playwright.dev/docs/api/class-locatorassertions) class provides assertion methods
+ * that can be used to make assertions about the [Locator](https://playwright.dev/docs/api/class-locator) state in the
+ * tests.
+ *
+ * ```js
+ * import { test, expect } from '@playwright/test';
+ *
+ * test('status becomes submitted', async ({ page }) => {
+ * // ...
+ * await page.getByRole('button').click();
+ * await expect(page.locator('.status')).toHaveText('Submitted');
+ * });
+ * ```
+ *
+ */
+interface LocatorAssertions {
/**
- * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an element with a given
- * [accessible name](https://w3c.github.io/accname/#dfn-accessible-name).
+ * Ensures that [Locator](https://playwright.dev/docs/api/class-locator) points to an element that is
+ * [connected](https://developer.mozilla.org/en-US/docs/Web/API/Node/isConnected) to a Document or a ShadowRoot.
*
* **Usage**
*
* ```js
- * const locator = page.getByTestId('save-button');
- * await expect(locator).toHaveAccessibleName('Save to disk');
+ * await expect(page.getByText('Hidden text')).toBeAttached();
* ```
*
- * @param name Expected accessible name.
* @param options
*/
- toHaveAccessibleName(name: string|RegExp, options?: {
- /**
- * Whether to perform case-insensitive match.
- * [`ignoreCase`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-accessible-name-option-ignore-case)
- * option takes precedence over the corresponding regular expression flag if specified.
- */
- ignoreCase?: boolean;
+ toBeAttached(options?: {
+ attached?: boolean;
/**
* Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
@@ -8400,84 +8494,56 @@ interface LocatorAssertions {
}): Promise<void>;
/**
- * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an element with given attribute.
+ * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to a checked input.
*
* **Usage**
*
* ```js
- * const locator = page.locator('input');
- * await expect(locator).toHaveAttribute('type', 'text');
+ * const locator = page.getByLabel('Subscribe to newsletter');
+ * await expect(locator).toBeChecked();
* ```
*
- * @param name Attribute name.
- * @param value Expected attribute value.
* @param options
*/
- toHaveAttribute(name: string, value: string|RegExp, options?: {
+ toBeChecked(options?: {
/**
- * Whether to perform case-insensitive match.
- * [`ignoreCase`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-attribute-option-ignore-case)
- * option takes precedence over the corresponding regular expression flag if specified.
+ * Provides state to assert for. Asserts for input to be checked by default. This option can't be used when
+ * [`indeterminate`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-be-checked-option-indeterminate)
+ * is set to true.
*/
- ignoreCase?: boolean;
+ checked?: boolean;
/**
- * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
+ * Asserts that the element is in the indeterminate (mixed) state. Only supported for checkboxes and radio buttons.
+ * This option can't be true when
+ * [`checked`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-be-checked-option-checked)
+ * is provided.
*/
- timeout?: number;
- }): Promise<void>;
+ indeterminate?: boolean;
- /**
- * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an element with given attribute. The
- * method will assert attribute presence.
- *
- * ```js
- * const locator = page.locator('input');
- * // Assert attribute existence.
- * await expect(locator).toHaveAttribute('disabled');
- * await expect(locator).not.toHaveAttribute('open');
- * ```
- *
- * @param name Attribute name.
- * @param options
- */
- toHaveAttribute(name: string, options?: {
/**
* Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
*/
timeout?: number;
}): Promise<void>;
- /**
- * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an element with given CSS classes.
- * When a string is provided, it must fully match the element's `class` attribute. To match individual classes use
- * [expect(locator).toContainClass(expected[, options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-contain-class).
+ /**
+ * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to a disabled element. Element is
+ * disabled if it has "disabled" attribute or is disabled via
+ * ['aria-disabled'](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-disabled). Note
+ * that only native control elements such as HTML `button`, `input`, `select`, `textarea`, `option`, `optgroup` can be
+ * disabled by setting "disabled" attribute. "disabled" attribute on other elements is ignored by the browser.
*
* **Usage**
*
- * ```html
- * <div class='middle selected row' id='component'></div>
- * ```
- *
- * ```js
- * const locator = page.locator('#component');
- * await expect(locator).toHaveClass('middle selected row');
- * await expect(locator).toHaveClass(/(^|\s)selected(\s|$)/);
- * ```
- *
- * When an array is passed, the method asserts that the list of elements located matches the corresponding list of
- * expected class values. Each element's class attribute is matched against the corresponding string or regular
- * expression in the array:
- *
* ```js
- * const locator = page.locator('list > .component');
- * await expect(locator).toHaveClass(['component', 'component selected', 'component']);
+ * const locator = page.locator('button.submit');
+ * await expect(locator).toBeDisabled();
* ```
*
- * @param expected Expected class or RegExp or a list of those.
* @param options
*/
- toHaveClass(expected: string|RegExp|ReadonlyArray<string|RegExp>, options?: {
+ toBeDisabled(options?: {
/**
* Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
*/
@@ -8485,19 +8551,20 @@ interface LocatorAssertions {
}): Promise<void>;
/**
- * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) resolves to an exact number of DOM nodes.
+ * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an editable element.
*
* **Usage**
*
* ```js
- * const list = page.locator('list > .component');
- * await expect(list).toHaveCount(3);
+ * const locator = page.getByRole('textbox');
+ * await expect(locator).toBeEditable();
* ```
*
- * @param count Expected count.
* @param options
*/
- toHaveCount(count: number, options?: {
+ toBeEditable(options?: {
+ editable?: boolean;
+
/**
* Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
*/
@@ -8505,21 +8572,19 @@ interface LocatorAssertions {
}): Promise<void>;
/**
- * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) resolves to an element with the given computed
- * CSS style.
+ * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an empty editable element or to a
+ * DOM node that has no text.
*
* **Usage**
*
* ```js
- * const locator = page.getByRole('button');
- * await expect(locator).toHaveCSS('display', 'flex');
+ * const locator = page.locator('div.warning');
+ * await expect(locator).toBeEmpty();
* ```
*
- * @param name CSS property name.
- * @param value CSS property value.
* @param options
*/
- toHaveCSS(name: string, value: string|RegExp, options?: {
+ toBeEmpty(options?: {
/**
* Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
*/
@@ -8527,20 +8592,20 @@ interface LocatorAssertions {
}): Promise<void>;
/**
- * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an element with the given DOM Node
- * ID.
+ * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an enabled element.
*
* **Usage**
*
* ```js
- * const locator = page.getByRole('textbox');
- * await expect(locator).toHaveId('lastname');
+ * const locator = page.locator('button.submit');
+ * await expect(locator).toBeEnabled();
* ```
*
- * @param id Element id.
* @param options
*/
- toHaveId(id: string|RegExp, options?: {
+ toBeEnabled(options?: {
+ enabled?: boolean;
+
/**
* Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
*/
@@ -8548,21 +8613,18 @@ interface LocatorAssertions {
}): Promise<void>;
/**
- * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an element with given JavaScript
- * property. Note that this property can be of a primitive type as well as a plain serializable JavaScript object.
+ * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to a focused DOM node.
*
* **Usage**
*
* ```js
- * const locator = page.locator('.component');
- * await expect(locator).toHaveJSProperty('loaded', true);
+ * const locator = page.getByRole('textbox');
+ * await expect(locator).toBeFocused();
* ```
*
- * @param name Property name.
- * @param value Property value.
* @param options
*/
- toHaveJSProperty(name: string, value: any, options?: {
+ toBeFocused(options?: {
/**
* Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
*/
@@ -8570,23 +8632,19 @@ interface LocatorAssertions {
}): Promise<void>;
/**
- * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an element with a given
- * [ARIA role](https://www.w3.org/TR/wai-aria-1.2/#roles).
- *
- * Note that role is matched as a string, disregarding the ARIA role hierarchy. For example, asserting a superclass
- * role `"checkbox"` on an element with a subclass role `"switch"` will fail.
+ * Ensures that [Locator](https://playwright.dev/docs/api/class-locator) either does not resolve to any DOM node, or
+ * resolves to a [non-visible](https://playwright.dev/docs/actionability#visible) one.
*
* **Usage**
*
* ```js
- * const locator = page.getByTestId('save-button');
- * await expect(locator).toHaveRole('button');
+ * const locator = page.locator('.my-element');
+ * await expect(locator).toBeHidden();
* ```
*
- * @param role Required aria role.
* @param options
*/
- toHaveRole(role: "alert"|"alertdialog"|"application"|"article"|"banner"|"blockquote"|"button"|"caption"|"cell"|"checkbox"|"code"|"columnheader"|"combobox"|"complementary"|"contentinfo"|"definition"|"deletion"|"dialog"|"directory"|"document"|"emphasis"|"feed"|"figure"|"form"|"generic"|"grid"|"gridcell"|"group"|"heading"|"img"|"insertion"|"link"|"list"|"listbox"|"listitem"|"log"|"main"|"marquee"|"math"|"meter"|"menu"|"menubar"|"menuitem"|"menuitemcheckbox"|"menuitemradio"|"navigation"|"none"|"note"|"option"|"paragraph"|"presentation"|"progressbar"|"radio"|"radiogroup"|"region"|"row"|"rowgroup"|"rowheader"|"scrollbar"|"search"|"searchbox"|"separator"|"slider"|"spinbutton"|"status"|"strong"|"subscript"|"superscript"|"switch"|"tab"|"table"|"tablist"|"tabpanel"|"term"|"textbox"|"time"|"timer"|"toolbar"|"tooltip"|"tree"|"treegrid"|"treeitem", options?: {
+ toBeHidden(options?: {
/**
* Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
*/
@@ -8594,92 +8652,30 @@ interface LocatorAssertions {
}): Promise<void>;
/**
- * This function will wait until two consecutive locator screenshots yield the same result, and then compare the last
- * screenshot with the expectation.
+ * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an element that intersects viewport,
+ * according to the
+ * [intersection observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API).
*
* **Usage**
*
* ```js
* const locator = page.getByRole('button');
- * await expect(locator).toHaveScreenshot('image.png');
+ * // Make sure at least some part of element intersects viewport.
+ * await expect(locator).toBeInViewport();
+ * // Make sure element is fully outside of viewport.
+ * await expect(locator).not.toBeInViewport();
+ * // Make sure that at least half of the element intersects viewport.
+ * await expect(locator).toBeInViewport({ ratio: 0.5 });
* ```
*
- * Note that screenshot assertions only work with Playwright test runner.
- * @param name Snapshot name.
* @param options
*/
- toHaveScreenshot(name: string|ReadonlyArray<string>, options?: {
- /**
- * When set to `"disabled"`, stops CSS animations, CSS transitions and Web Animations. Animations get different
- * treatment depending on their duration:
- * - finite animations are fast-forwarded to completion, so they'll fire `transitionend` event.
- * - infinite animations are canceled to initial state, and then played over after the screenshot.
- *
- * Defaults to `"disabled"` that disables animations.
- */
- animations?: "disabled"|"allow";
-
- /**
- * When set to `"hide"`, screenshot will hide text caret. When set to `"initial"`, text caret behavior will not be
- * changed. Defaults to `"hide"`.
- */
- caret?: "hide"|"initial";
-
- /**
- * Specify locators that should be masked when the screenshot is taken. Masked elements will be overlaid with a pink
- * box `#FF00FF` (customized by
- * [`maskColor`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-screenshot-1-option-mask-color))
- * that completely covers its bounding box. The mask is also applied to invisible elements, see
- * [Matching only visible elements](https://playwright.dev/docs/locators#matching-only-visible-elements) to disable that.
- */
- mask?: Array<Locator>;
-
- /**
- * Specify the color of the overlay box for masked elements, in
- * [CSS color format](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value). Default color is pink `#FF00FF`.
- */
- maskColor?: string;
-
- /**
- * An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1`. Default is
- * configurable with `TestConfig.expect`. Unset by default.
- */
- maxDiffPixelRatio?: number;
-
- /**
- * An acceptable amount of pixels that could be different. Default is configurable with `TestConfig.expect`. Unset by
- * default.
- */
- maxDiffPixels?: number;
-
- /**
- * Hides default white background and allows capturing screenshots with transparency. Not applicable to `jpeg` images.
- * Defaults to `false`.
- */
- omitBackground?: boolean;
-
- /**
- * When set to `"css"`, screenshot will have a single pixel per each css pixel on the page. For high-dpi devices, this
- * will keep screenshots small. Using `"device"` option will produce a single pixel per each device pixel, so
- * screenshots of high-dpi devices will be twice as large or even larger.
- *
- * Defaults to `"css"`.
- */
- scale?: "css"|"device";
-
- /**
- * File name containing the stylesheet to apply while making the screenshot. This is where you can hide dynamic
- * elements, make elements invisible or change their properties to help you creating repeatable screenshots. This
- * stylesheet pierces the Shadow DOM and applies to the inner frames.
- */
- stylePath?: string|Array<string>;
-
+ toBeInViewport(options?: {
/**
- * An acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between the
- * same pixel in compared images, between zero (strict) and one (lax), default is configurable with
- * `TestConfig.expect`. Defaults to `0.2`.
+ * The minimal ratio of the element to intersect viewport. If equals to `0`, then element should intersect viewport at
+ * any positive ratio. Defaults to `0`.
*/
- threshold?: number;
+ ratio?: number;
/**
* Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
@@ -8688,92 +8684,79 @@ interface LocatorAssertions {
}): Promise<void>;
/**
- * This function will wait until two consecutive locator screenshots yield the same result, and then compare the last
- * screenshot with the expectation.
+ * Ensures that [Locator](https://playwright.dev/docs/api/class-locator) points to an attached and
+ * [visible](https://playwright.dev/docs/actionability#visible) DOM node.
+ *
+ * To check that at least one element from the list is visible, use
+ * [locator.first()](https://playwright.dev/docs/api/class-locator#locator-first).
*
* **Usage**
*
* ```js
- * const locator = page.getByRole('button');
- * await expect(locator).toHaveScreenshot();
- * ```
+ * // A specific element is visible.
+ * await expect(page.getByText('Welcome')).toBeVisible();
*
- * Note that screenshot assertions only work with Playwright test runner.
- * @param options
- */
- toHaveScreenshot(options?: {
- /**
- * When set to `"disabled"`, stops CSS animations, CSS transitions and Web Animations. Animations get different
- * treatment depending on their duration:
- * - finite animations are fast-forwarded to completion, so they'll fire `transitionend` event.
- * - infinite animations are canceled to initial state, and then played over after the screenshot.
- *
- * Defaults to `"disabled"` that disables animations.
- */
- animations?: "disabled"|"allow";
-
- /**
- * When set to `"hide"`, screenshot will hide text caret. When set to `"initial"`, text caret behavior will not be
- * changed. Defaults to `"hide"`.
- */
- caret?: "hide"|"initial";
-
- /**
- * Specify locators that should be masked when the screenshot is taken. Masked elements will be overlaid with a pink
- * box `#FF00FF` (customized by
- * [`maskColor`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-screenshot-2-option-mask-color))
- * that completely covers its bounding box. The mask is also applied to invisible elements, see
- * [Matching only visible elements](https://playwright.dev/docs/locators#matching-only-visible-elements) to disable that.
- */
- mask?: Array<Locator>;
-
- /**
- * Specify the color of the overlay box for masked elements, in
- * [CSS color format](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value). Default color is pink `#FF00FF`.
- */
- maskColor?: string;
-
- /**
- * An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1`. Default is
- * configurable with `TestConfig.expect`. Unset by default.
- */
- maxDiffPixelRatio?: number;
-
- /**
- * An acceptable amount of pixels that could be different. Default is configurable with `TestConfig.expect`. Unset by
- * default.
- */
- maxDiffPixels?: number;
-
- /**
- * Hides default white background and allows capturing screenshots with transparency. Not applicable to `jpeg` images.
- * Defaults to `false`.
- */
- omitBackground?: boolean;
-
- /**
- * When set to `"css"`, screenshot will have a single pixel per each css pixel on the page. For high-dpi devices, this
- * will keep screenshots small. Using `"device"` option will produce a single pixel per each device pixel, so
- * screenshots of high-dpi devices will be twice as large or even larger.
- *
- * Defaults to `"css"`.
- */
- scale?: "css"|"device";
-
+ * // At least one item in the list is visible.
+ * await expect(page.getByTestId('todo-item').first()).toBeVisible();
+ *
+ * // At least one of the two elements is visible, possibly both.
+ * await expect(
+ * page.getByRole('button', { name: 'Sign in' })
+ * .or(page.getByRole('button', { name: 'Sign up' }))
+ * .first()
+ * ).toBeVisible();
+ * ```
+ *
+ * @param options
+ */
+ toBeVisible(options?: {
/**
- * File name containing the stylesheet to apply while making the screenshot. This is where you can hide dynamic
- * elements, make elements invisible or change their properties to help you creating repeatable screenshots. This
- * stylesheet pierces the Shadow DOM and applies to the inner frames.
+ * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
*/
- stylePath?: string|Array<string>;
+ timeout?: number;
- /**
- * An acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between the
- * same pixel in compared images, between zero (strict) and one (lax), default is configurable with
- * `TestConfig.expect`. Defaults to `0.2`.
- */
- threshold?: number;
+ visible?: boolean;
+ }): Promise<void>;
+ /**
+ * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an element with given CSS classes.
+ * All classes from the asserted value, separated by spaces, must be present in the
+ * [Element.classList](https://developer.mozilla.org/en-US/docs/Web/API/Element/classList) in any order.
+ *
+ * **Usage**
+ *
+ * ```html
+ * <div class='middle selected row' id='component'></div>
+ * ```
+ *
+ * ```js
+ * const locator = page.locator('#component');
+ * await expect(locator).toContainClass('middle selected row');
+ * await expect(locator).toContainClass('selected');
+ * await expect(locator).toContainClass('row middle');
+ * ```
+ *
+ * When an array is passed, the method asserts that the list of elements located matches the corresponding list of
+ * expected class lists. Each element's class attribute is matched against the corresponding class in the array:
+ *
+ * ```html
+ * <div class='list'></div>
+ * <div class='component inactive'></div>
+ * <div class='component active'></div>
+ * <div class='component inactive'></div>
+ * </div>
+ * ```
+ *
+ * ```js
+ * const locator = page.locator('list > .component');
+ * await expect(locator).toContainClass(['inactive', 'active', 'inactive']);
+ * ```
+ *
+ * @param expected A string containing expected class names, separated by spaces, or a list of such strings to assert multiple
+ * elements.
+ * @param options
+ */
+ toContainClass(expected: string|ReadonlyArray<string>, options?: {
/**
* Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
*/
@@ -8781,9 +8764,9 @@ interface LocatorAssertions {
}): Promise<void>;
/**
- * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an element with the given text. All
- * nested elements will be considered when computing the text content of the element. You can use regular expressions
- * for the value as well.
+ * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an element that contains the given
+ * text. All nested elements will be considered when computing the text content of the element. You can use regular
+ * expressions for the value as well.
*
* **Details**
*
@@ -8794,48 +8777,49 @@ interface LocatorAssertions {
*
* ```js
* const locator = page.locator('.title');
- * await expect(locator).toHaveText(/Welcome, Test User/);
- * await expect(locator).toHaveText(/Welcome, .*\/);
+ * await expect(locator).toContainText('substring');
+ * await expect(locator).toContainText(/\d messages/);
* ```
*
* If you pass an array as an expected value, the expectations are:
* 1. Locator resolves to a list of elements.
- * 1. The number of elements equals the number of expected values in the array.
- * 1. Elements from the list have text matching expected array values, one by one, in order.
+ * 1. Elements from a **subset** of this list contain text from the expected array, respectively.
+ * 1. The matching subset of elements has the same order as the expected array.
+ * 1. Each text value from the expected array is matched by some element from the list.
*
* For example, consider the following list:
*
* ```html
* <ul>
- * <li>Text 1</li>
- * <li>Text 2</li>
- * <li>Text 3</li>
+ * <li>Item Text 1</li>
+ * <li>Item Text 2</li>
+ * <li>Item Text 3</li>
* </ul>
* ```
*
* Let's see how we can use the assertion:
*
* ```js
- * // ✓ Has the right items in the right order
- * await expect(page.locator('ul > li')).toHaveText(['Text 1', 'Text 2', 'Text 3']);
+ * // ✓ Contains the right items in the right order
+ * await expect(page.locator('ul > li')).toContainText(['Text 1', 'Text 3']);
*
* // ✖ Wrong order
- * await expect(page.locator('ul > li')).toHaveText(['Text 3', 'Text 2', 'Text 1']);
+ * await expect(page.locator('ul > li')).toContainText(['Text 3', 'Text 2']);
*
- * // ✖ Last item does not match
- * await expect(page.locator('ul > li')).toHaveText(['Text 1', 'Text 2', 'Text']);
+ * // ✖ No item contains this text
+ * await expect(page.locator('ul > li')).toContainText(['Some 33']);
*
* // ✖ Locator points to the outer list element, not to the list items
- * await expect(page.locator('ul')).toHaveText(['Text 1', 'Text 2', 'Text 3']);
+ * await expect(page.locator('ul')).toContainText(['Text 3']);
* ```
*
- * @param expected Expected string or RegExp or a list of those.
+ * @param expected Expected substring or RegExp or a list of those.
* @param options
*/
- toHaveText(expected: string|RegExp|ReadonlyArray<string|RegExp>, options?: {
+ toContainText(expected: string|RegExp|ReadonlyArray<string|RegExp>, options?: {
/**
* Whether to perform case-insensitive match.
- * [`ignoreCase`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-text-option-ignore-case)
+ * [`ignoreCase`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-contain-text-option-ignore-case)
* option takes precedence over the corresponding regular expression flag if specified.
*/
ignoreCase?: boolean;
@@ -8852,20 +8836,27 @@ interface LocatorAssertions {
}): Promise<void>;
/**
- * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an element with the given input
- * value. You can use regular expressions for the value as well.
+ * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an element with a given
+ * [accessible description](https://w3c.github.io/accname/#dfn-accessible-description).
*
* **Usage**
*
* ```js
- * const locator = page.locator('input[type=number]');
- * await expect(locator).toHaveValue(/[0-9]/);
+ * const locator = page.getByTestId('save-button');
+ * await expect(locator).toHaveAccessibleDescription('Save results to disk');
* ```
*
- * @param value Expected value.
+ * @param description Expected accessible description.
* @param options
*/
- toHaveValue(value: string|RegExp, options?: {
+ toHaveAccessibleDescription(description: string|RegExp, options?: {
+ /**
+ * Whether to perform case-insensitive match.
+ * [`ignoreCase`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-accessible-description-option-ignore-case)
+ * option takes precedence over the corresponding regular expression flag if specified.
+ */
+ ignoreCase?: boolean;
+
/**
* Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
*/
@@ -8873,31 +8864,27 @@ interface LocatorAssertions {
}): Promise<void>;
/**
- * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to multi-select/combobox (i.e. a
- * `select` with the `multiple` attribute) and the specified values are selected.
+ * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an element with a given
+ * [aria errormessage](https://w3c.github.io/aria/#aria-errormessage).
*
* **Usage**
*
- * For example, given the following element:
- *
- * ```html
- * <select id="favorite-colors" multiple>
- * <option value="R">Red</option>
- * <option value="G">Green</option>
- * <option value="B">Blue</option>
- * </select>
- * ```
- *
* ```js
- * const locator = page.locator('id=favorite-colors');
- * await locator.selectOption(['R', 'G']);
- * await expect(locator).toHaveValues([/R/, /G/]);
+ * const locator = page.getByTestId('username-input');
+ * await expect(locator).toHaveAccessibleErrorMessage('Username is required.');
* ```
*
- * @param values Expected options currently selected.
+ * @param errorMessage Expected accessible error message.
* @param options
*/
- toHaveValues(values: ReadonlyArray<string|RegExp>, options?: {
+ toHaveAccessibleErrorMessage(errorMessage: string|RegExp, options?: {
+ /**
+ * Whether to perform case-insensitive match.
+ * [`ignoreCase`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-accessible-error-message-option-ignore-case)
+ * option takes precedence over the corresponding regular expression flag if specified.
+ */
+ ignoreCase?: boolean;
+
/**
* Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
*/
@@ -8905,22 +8892,27 @@ interface LocatorAssertions {
}): Promise<void>;
/**
- * Asserts that the target element matches the given [accessibility snapshot](https://playwright.dev/docs/aria-snapshots).
+ * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an element with a given
+ * [accessible name](https://w3c.github.io/accname/#dfn-accessible-name).
*
* **Usage**
*
* ```js
- * await page.goto('https://demo.playwright.dev/todomvc/');
- * await expect(page.locator('body')).toMatchAriaSnapshot(`
- * - heading "todos"
- * - textbox "What needs to be done?"
- * `);
+ * const locator = page.getByTestId('save-button');
+ * await expect(locator).toHaveAccessibleName('Save to disk');
* ```
*
- * @param expected
+ * @param name Expected accessible name.
* @param options
*/
- toMatchAriaSnapshot(expected: string, options?: {
+ toHaveAccessibleName(name: string|RegExp, options?: {
+ /**
+ * Whether to perform case-insensitive match.
+ * [`ignoreCase`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-accessible-name-option-ignore-case)
+ * option takes precedence over the corresponding regular expression flag if specified.
+ */
+ ignoreCase?: boolean;
+
/**
* Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
*/
@@ -8928,26 +8920,26 @@ interface LocatorAssertions {
}): Promise<void>;
/**
- * Asserts that the target element matches the given [accessibility snapshot](https://playwright.dev/docs/aria-snapshots).
- *
- * Snapshot is stored in a separate `.aria.yml` file in a location configured by
- * `expect.toMatchAriaSnapshot.pathTemplate` and/or `snapshotPathTemplate` properties in the configuration file.
+ * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an element with given attribute.
*
* **Usage**
*
* ```js
- * await expect(page.locator('body')).toMatchAriaSnapshot();
- * await expect(page.locator('body')).toMatchAriaSnapshot({ name: 'body.aria.yml' });
+ * const locator = page.locator('input');
+ * await expect(locator).toHaveAttribute('type', 'text');
* ```
*
+ * @param name Attribute name.
+ * @param value Expected attribute value.
* @param options
*/
- toMatchAriaSnapshot(options?: {
+ toHaveAttribute(name: string, value: string|RegExp, options?: {
/**
- * Name of the snapshot to store in the snapshot folder corresponding to this test. Generates sequential names if not
- * specified.
+ * Whether to perform case-insensitive match.
+ * [`ignoreCase`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-attribute-option-ignore-case)
+ * option takes precedence over the corresponding regular expression flag if specified.
*/
- name?: string;
+ ignoreCase?: boolean;
/**
* Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
@@ -8956,77 +8948,76 @@ interface LocatorAssertions {
}): Promise<void>;
/**
- * Makes the assertion check for the opposite condition. For example, this code tests that the Locator doesn't contain
- * text `"error"`:
+ * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an element with given attribute. The
+ * method will assert attribute presence.
*
* ```js
- * await expect(locator).not.toContainText('error');
+ * const locator = page.locator('input');
+ * // Assert attribute existence.
+ * await expect(locator).toHaveAttribute('disabled');
+ * await expect(locator).not.toHaveAttribute('open');
* ```
*
+ * @param name Attribute name.
+ * @param options
*/
- not: LocatorAssertions;
-}
+ toHaveAttribute(name: string, options?: {
+ /**
+ * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
+ */
+ timeout?: number;
+ }): Promise<void>;
-/**
- * The [PageAssertions](https://playwright.dev/docs/api/class-pageassertions) class provides assertion methods that
- * can be used to make assertions about the [Page](https://playwright.dev/docs/api/class-page) state in the tests.
- *
- * ```js
- * import { test, expect } from '@playwright/test';
- *
- * test('navigates to login', async ({ page }) => {
- * // ...
- * await page.getByText('Sign in').click();
- * await expect(page).toHaveURL(/.*\/login/);
- * });
- * ```
- *
- */
-interface PageAssertions {
/**
- * This function will wait until two consecutive page screenshots yield the same result, and then compare the last
- * screenshot with the expectation.
+ * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an element with given CSS classes.
+ * When a string is provided, it must fully match the element's `class` attribute. To match individual classes use
+ * [expect(locator).toContainClass(expected[, options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-contain-class).
*
* **Usage**
*
- * ```js
- * await expect(page).toHaveScreenshot('image.png');
+ * ```html
+ * <div class='middle selected row' id='component'></div>
* ```
*
- * Note that screenshot assertions only work with Playwright test runner.
- * @param name Snapshot name.
- * @param options
- */
- toHaveScreenshot(name: string|ReadonlyArray<string>, options?: PageAssertionsToHaveScreenshotOptions): Promise<void>;
-
- /**
- * This function will wait until two consecutive page screenshots yield the same result, and then compare the last
- * screenshot with the expectation.
+ * ```js
+ * const locator = page.locator('#component');
+ * await expect(locator).toHaveClass('middle selected row');
+ * await expect(locator).toHaveClass(/(^|\s)selected(\s|$)/);
+ * ```
*
- * **Usage**
+ * When an array is passed, the method asserts that the list of elements located matches the corresponding list of
+ * expected class values. Each element's class attribute is matched against the corresponding string or regular
+ * expression in the array:
*
* ```js
- * await expect(page).toHaveScreenshot();
+ * const locator = page.locator('list > .component');
+ * await expect(locator).toHaveClass(['component', 'component selected', 'component']);
* ```
*
- * Note that screenshot assertions only work with Playwright test runner.
+ * @param expected Expected class or RegExp or a list of those.
* @param options
*/
- toHaveScreenshot(options?: PageAssertionsToHaveScreenshotOptions): Promise<void>;
+ toHaveClass(expected: string|RegExp|ReadonlyArray<string|RegExp>, options?: {
+ /**
+ * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
+ */
+ timeout?: number;
+ }): Promise<void>;
/**
- * Ensures the page has the given title.
+ * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) resolves to an exact number of DOM nodes.
*
* **Usage**
*
* ```js
- * await expect(page).toHaveTitle(/.*checkout/);
+ * const list = page.locator('list > .component');
+ * await expect(list).toHaveCount(3);
* ```
*
- * @param titleOrRegExp Expected title or RegExp.
+ * @param count Expected count.
* @param options
*/
- toHaveTitle(titleOrRegExp: string|RegExp, options?: {
+ toHaveCount(count: number, options?: {
/**
* Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
*/
@@ -9034,41 +9025,21 @@ interface PageAssertions {
}): Promise<void>;
/**
- * Ensures the page is navigated to the given URL.
+ * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) resolves to an element with the given computed
+ * CSS style.
*
* **Usage**
*
* ```js
- * // Check for the page URL to be 'https://playwright.dev/docs/intro' (including query string)
- * await expect(page).toHaveURL('https://playwright.dev/docs/intro');
- *
- * // Check for the page URL to contain 'doc', followed by an optional 's', followed by '/'
- * await expect(page).toHaveURL(/docs?\//);
- *
- * // Check for the predicate to be satisfied
- * // For example: verify query strings
- * await expect(page).toHaveURL(url => {
- * const params = url.searchParams;
- * return params.has('search') && params.has('options') && params.get('id') === '5';
- * });
+ * const locator = page.getByRole('button');
+ * await expect(locator).toHaveCSS('display', 'flex');
* ```
*
- * @param url Expected URL string, RegExp, or predicate receiving [URL] to match. When
- * [`baseURL`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-base-url) is provided via the
- * context options and the `url` argument is a string, the two values are merged via the
- * [`new URL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) constructor and used for the comparison
- * against the current browser URL.
+ * @param name CSS property name.
+ * @param value CSS property value.
* @param options
*/
- toHaveURL(url: string|RegExp|((url: URL) => boolean), options?: {
- /**
- * Whether to perform case-insensitive match.
- * [`ignoreCase`](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-url-option-ignore-case)
- * option takes precedence over the corresponding regular expression parameter if specified. A provided predicate
- * ignores this flag.
- */
- ignoreCase?: boolean;
-
+ toHaveCSS(name: string, value: string|RegExp, options?: {
/**
* Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
*/
@@ -9076,611 +9047,705 @@ interface PageAssertions {
}): Promise<void>;
/**
- * Makes the assertion check for the opposite condition. For example, this code tests that the page URL doesn't
- * contain `"error"`:
+ * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an element with the given DOM Node
+ * ID.
+ *
+ * **Usage**
*
* ```js
- * await expect(page).not.toHaveURL('error');
+ * const locator = page.getByRole('textbox');
+ * await expect(locator).toHaveId('lastname');
* ```
*
+ * @param id Element id.
+ * @param options
*/
- not: PageAssertions;
-}
+ toHaveId(id: string|RegExp, options?: {
+ /**
+ * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
+ */
+ timeout?: number;
+ }): Promise<void>;
-/**
- * Playwright provides methods for comparing page and element screenshots with expected values stored in files.
- *
- * ```js
- * expect(screenshot).toMatchSnapshot('landing-page.png');
- * ```
- *
- */
-interface SnapshotAssertions {
/**
- * **NOTE** To compare screenshots, use
- * [expect(page).toHaveScreenshot(name[, options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1)
- * instead.
- *
- * Ensures that passed value, either a [string] or a [Buffer], matches the expected snapshot stored in the test
- * snapshots directory.
+ * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an element with given JavaScript
+ * property. Note that this property can be of a primitive type as well as a plain serializable JavaScript object.
*
* **Usage**
*
* ```js
- * // Basic usage.
- * expect(await page.screenshot()).toMatchSnapshot('landing-page.png');
- *
- * // Pass options to customize the snapshot comparison and have a generated name.
- * expect(await page.screenshot()).toMatchSnapshot('landing-page.png', {
- * maxDiffPixels: 27, // allow no more than 27 different pixels.
- * });
- *
- * // Configure image matching threshold.
- * expect(await page.screenshot()).toMatchSnapshot('landing-page.png', { threshold: 0.3 });
- *
- * // Bring some structure to your snapshot files by passing file path segments.
- * expect(await page.screenshot()).toMatchSnapshot(['landing', 'step2.png']);
- * expect(await page.screenshot()).toMatchSnapshot(['landing', 'step3.png']);
+ * const locator = page.locator('.component');
+ * await expect(locator).toHaveJSProperty('loaded', true);
* ```
*
- * Learn more about [visual comparisons](https://playwright.dev/docs/test-snapshots).
- *
- * Note that matching snapshots only work with Playwright test runner.
- * @param name Snapshot name.
+ * @param name Property name.
+ * @param value Property value.
* @param options
*/
- toMatchSnapshot(name: string|ReadonlyArray<string>, options?: {
- /**
- * An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1`. Default is
- * configurable with `TestConfig.expect`. Unset by default.
- */
- maxDiffPixelRatio?: number;
-
- /**
- * An acceptable amount of pixels that could be different. Default is configurable with `TestConfig.expect`. Unset by
- * default.
- */
- maxDiffPixels?: number;
-
+ toHaveJSProperty(name: string, value: any, options?: {
/**
- * An acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between the
- * same pixel in compared images, between zero (strict) and one (lax), default is configurable with
- * `TestConfig.expect`. Defaults to `0.2`.
+ * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
*/
- threshold?: number;
- }): void;
+ timeout?: number;
+ }): Promise<void>;
/**
- * **NOTE** To compare screenshots, use
- * [expect(page).toHaveScreenshot([options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-2)
- * instead.
+ * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an element with a given
+ * [ARIA role](https://www.w3.org/TR/wai-aria-1.2/#roles).
*
- * Ensures that passed value, either a [string] or a [Buffer], matches the expected snapshot stored in the test
- * snapshots directory.
+ * Note that role is matched as a string, disregarding the ARIA role hierarchy. For example, asserting a superclass
+ * role `"checkbox"` on an element with a subclass role `"switch"` will fail.
*
* **Usage**
*
* ```js
- * // Basic usage and the file name is derived from the test name.
- * expect(await page.screenshot()).toMatchSnapshot();
- *
- * // Pass options to customize the snapshot comparison and have a generated name.
- * expect(await page.screenshot()).toMatchSnapshot({
- * maxDiffPixels: 27, // allow no more than 27 different pixels.
- * });
- *
- * // Configure image matching threshold and snapshot name.
- * expect(await page.screenshot()).toMatchSnapshot({
- * name: 'landing-page.png',
- * threshold: 0.3,
- * });
+ * const locator = page.getByTestId('save-button');
+ * await expect(locator).toHaveRole('button');
* ```
*
- * Learn more about [visual comparisons](https://playwright.dev/docs/test-snapshots).
- *
- * Note that matching snapshots only work with Playwright test runner.
+ * @param role Required aria role.
* @param options
*/
- toMatchSnapshot(options?: {
- /**
- * An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1`. Default is
- * configurable with `TestConfig.expect`. Unset by default.
- */
- maxDiffPixelRatio?: number;
-
- /**
- * An acceptable amount of pixels that could be different. Default is configurable with `TestConfig.expect`. Unset by
- * default.
- */
- maxDiffPixels?: number;
-
- /**
- * Snapshot name. If not passed, the test name and ordinals are used when called multiple times.
- */
- name?: string|Array<string>;
-
+ toHaveRole(role: "alert"|"alertdialog"|"application"|"article"|"banner"|"blockquote"|"button"|"caption"|"cell"|"checkbox"|"code"|"columnheader"|"combobox"|"complementary"|"contentinfo"|"definition"|"deletion"|"dialog"|"directory"|"document"|"emphasis"|"feed"|"figure"|"form"|"generic"|"grid"|"gridcell"|"group"|"heading"|"img"|"insertion"|"link"|"list"|"listbox"|"listitem"|"log"|"main"|"marquee"|"math"|"meter"|"menu"|"menubar"|"menuitem"|"menuitemcheckbox"|"menuitemradio"|"navigation"|"none"|"note"|"option"|"paragraph"|"presentation"|"progressbar"|"radio"|"radiogroup"|"region"|"row"|"rowgroup"|"rowheader"|"scrollbar"|"search"|"searchbox"|"separator"|"slider"|"spinbutton"|"status"|"strong"|"subscript"|"superscript"|"switch"|"tab"|"table"|"tablist"|"tabpanel"|"term"|"textbox"|"time"|"timer"|"toolbar"|"tooltip"|"tree"|"treegrid"|"treeitem", options?: {
/**
- * An acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between the
- * same pixel in compared images, between zero (strict) and one (lax), default is configurable with
- * `TestConfig.expect`. Defaults to `0.2`.
+ * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
*/
- threshold?: number;
- }): void;
-}
-
-/**
- * Represents a location in the source code where [TestCase] or [Suite] is defined.
- */
-export interface Location {
- /**
- * Column number in the source file.
- */
- column: number;
-
- /**
- * Path to the source file.
- */
- file: string;
-
- /**
- * Line number in the source file.
- */
- line: number;
-}
+ timeout?: number;
+ }): Promise<void>;
-/**
- * `TestInfo` contains information about currently running test. It is available to test functions,
- * [test.beforeEach([title, hookFunction])](https://playwright.dev/docs/api/class-test#test-before-each),
- * [test.afterEach([title, hookFunction])](https://playwright.dev/docs/api/class-test#test-after-each),
- * [test.beforeAll([title, hookFunction])](https://playwright.dev/docs/api/class-test#test-before-all) and
- * [test.afterAll([title, hookFunction])](https://playwright.dev/docs/api/class-test#test-after-all) hooks, and
- * test-scoped fixtures. `TestInfo` provides utilities to control test execution: attach files, update test timeout,
- * determine which test is currently running and whether it was retried, etc.
- *
- * ```js
- * import { test, expect } from '@playwright/test';
- *
- * test('basic test', async ({ page }, testInfo) => {
- * expect(testInfo.title).toBe('basic test');
- * await page.screenshot(testInfo.outputPath('screenshot.png'));
- * });
- * ```
- *
- */
-export interface TestInfo {
/**
- * Attach a value or a file from disk to the current test. Some reporters show test attachments. Either
- * [`path`](https://playwright.dev/docs/api/class-testinfo#test-info-attach-option-path) or
- * [`body`](https://playwright.dev/docs/api/class-testinfo#test-info-attach-option-body) must be specified, but not
- * both.
- *
- * For example, you can attach a screenshot to the test:
- *
- * ```js
- * import { test, expect } from '@playwright/test';
- *
- * test('basic test', async ({ page }, testInfo) => {
- * await page.goto('https://playwright.dev');
- * const screenshot = await page.screenshot();
- * await testInfo.attach('screenshot', { body: screenshot, contentType: 'image/png' });
- * });
- * ```
- *
- * Or you can attach files returned by your APIs:
- *
- * ```js
- * import { test, expect } from '@playwright/test';
- * import { download } from './my-custom-helpers';
- *
- * test('basic test', async ({}, testInfo) => {
- * const tmpPath = await download('a');
- * await testInfo.attach('downloaded', { path: tmpPath });
- * });
- * ```
+ * This function will wait until two consecutive locator screenshots yield the same result, and then compare the last
+ * screenshot with the expectation.
*
- * **NOTE** [testInfo.attach(name[, options])](https://playwright.dev/docs/api/class-testinfo#test-info-attach)
- * automatically takes care of copying attached files to a location that is accessible to reporters. You can safely
- * remove the attachment after awaiting the attach call.
+ * **Usage**
*
- * @param name Attachment name. The name will also be sanitized and used as the prefix of file name when saving to disk.
+ * ```js
+ * const locator = page.getByRole('button');
+ * await expect(locator).toHaveScreenshot('image.png');
+ * ```
+ *
+ * Note that screenshot assertions only work with Playwright test runner.
+ * @param name Snapshot name.
* @param options
*/
- attach(name: string, options?: {
+ toHaveScreenshot(name: string|ReadonlyArray<string>, options?: {
/**
- * Attachment body. Mutually exclusive with
- * [`path`](https://playwright.dev/docs/api/class-testinfo#test-info-attach-option-path).
+ * When set to `"disabled"`, stops CSS animations, CSS transitions and Web Animations. Animations get different
+ * treatment depending on their duration:
+ * - finite animations are fast-forwarded to completion, so they'll fire `transitionend` event.
+ * - infinite animations are canceled to initial state, and then played over after the screenshot.
+ *
+ * Defaults to `"disabled"` that disables animations.
*/
- body?: string|Buffer;
+ animations?: "disabled"|"allow";
/**
- * Content type of this attachment to properly present in the report, for example `'application/json'` or
- * `'image/png'`. If omitted, content type is inferred based on the
- * [`path`](https://playwright.dev/docs/api/class-testinfo#test-info-attach-option-path), or defaults to `text/plain`
- * for [string] attachments and `application/octet-stream` for [Buffer] attachments.
+ * When set to `"hide"`, screenshot will hide text caret. When set to `"initial"`, text caret behavior will not be
+ * changed. Defaults to `"hide"`.
*/
- contentType?: string;
+ caret?: "hide"|"initial";
/**
- * Path on the filesystem to the attached file. Mutually exclusive with
- * [`body`](https://playwright.dev/docs/api/class-testinfo#test-info-attach-option-body).
+ * Specify locators that should be masked when the screenshot is taken. Masked elements will be overlaid with a pink
+ * box `#FF00FF` (customized by
+ * [`maskColor`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-screenshot-1-option-mask-color))
+ * that completely covers its bounding box. The mask is also applied to invisible elements, see
+ * [Matching only visible elements](https://playwright.dev/docs/locators#matching-only-visible-elements) to disable that.
*/
- path?: string;
- }): Promise<void>;
+ mask?: Array<Locator>;
- /**
- * Marks the currently running 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. This is similar to
- * [test.fail([title, details, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-fail).
- */
- fail(): void;
+ /**
+ * Specify the color of the overlay box for masked elements, in
+ * [CSS color format](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value). Default color is pink `#FF00FF`.
+ */
+ maskColor?: string;
- /**
- * Conditionally mark the currently running test as "should fail" with an optional description. This is similar to
- * [test.fail([title, details, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-fail).
- * @param condition Test is marked as "should fail" when the condition is `true`.
- * @param description Optional description that will be reflected in a test report.
- */
- fail(condition: boolean, description?: string): void;
+ /**
+ * An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1`. Default is
+ * configurable with `TestConfig.expect`. Unset by default.
+ */
+ maxDiffPixelRatio?: number;
- /**
- * Mark a test as "fixme", with the intention to fix it. Test is immediately aborted. This is similar to
- * [test.fixme([title, details, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-fixme).
- */
- fixme(): void;
+ /**
+ * An acceptable amount of pixels that could be different. Default is configurable with `TestConfig.expect`. Unset by
+ * default.
+ */
+ maxDiffPixels?: number;
- /**
- * Conditionally mark the currently running test as "fixme" with an optional description. This is similar to
- * [test.fixme([title, details, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-fixme).
- * @param condition Test is marked as "fixme" when the condition is `true`.
- * @param description Optional description that will be reflected in a test report.
- */
- fixme(condition: boolean, description?: string): void;
+ /**
+ * Hides default white background and allows capturing screenshots with transparency. Not applicable to `jpeg` images.
+ * Defaults to `false`.
+ */
+ omitBackground?: boolean;
- /**
- * Returns a path inside the [testInfo.outputDir](https://playwright.dev/docs/api/class-testinfo#test-info-output-dir)
- * where the test can safely put a temporary file. Guarantees that tests running in parallel will not interfere with
- * each other.
- *
- * ```js
- * import { test, expect } from '@playwright/test';
- * import fs from 'fs';
- *
- * test('example test', async ({}, testInfo) => {
- * const file = testInfo.outputPath('dir', 'temporary-file.txt');
- * await fs.promises.writeFile(file, 'Put some data to the dir/temporary-file.txt', 'utf8');
- * });
- * ```
- *
- * > Note that `pathSegments` accepts path segments to the test output directory such as
- * `testInfo.outputPath('relative', 'path', 'to', 'output')`.
- * > However, this path must stay within the
- * [testInfo.outputDir](https://playwright.dev/docs/api/class-testinfo#test-info-output-dir) directory for each test
- * (i.e. `test-results/a-test-title`), otherwise it will throw.
- * @param pathSegments Path segments to append at the end of the resulting path.
- */
- outputPath(...pathSegments: ReadonlyArray<string>): string;
+ /**
+ * When set to `"css"`, screenshot will have a single pixel per each css pixel on the page. For high-dpi devices, this
+ * will keep screenshots small. Using `"device"` option will produce a single pixel per each device pixel, so
+ * screenshots of high-dpi devices will be twice as large or even larger.
+ *
+ * Defaults to `"css"`.
+ */
+ scale?: "css"|"device";
+
+ /**
+ * File name containing the stylesheet to apply while making the screenshot. This is where you can hide dynamic
+ * elements, make elements invisible or change their properties to help you creating repeatable screenshots. This
+ * stylesheet pierces the Shadow DOM and applies to the inner frames.
+ */
+ stylePath?: string|Array<string>;
+
+ /**
+ * An acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between the
+ * same pixel in compared images, between zero (strict) and one (lax), default is configurable with
+ * `TestConfig.expect`. Defaults to `0.2`.
+ */
+ threshold?: number;
+
+ /**
+ * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
+ */
+ timeout?: number;
+ }): Promise<void>;
/**
- * Changes the timeout for the currently running test. Zero means no timeout. Learn more about
- * [various timeouts](https://playwright.dev/docs/test-timeouts).
+ * This function will wait until two consecutive locator screenshots yield the same result, and then compare the last
+ * screenshot with the expectation.
*
- * Timeout is usually specified in the [configuration file](https://playwright.dev/docs/test-configuration), but it could be useful to
- * change the timeout in certain scenarios:
+ * **Usage**
*
* ```js
- * import { test, expect } from '@playwright/test';
- *
- * test.beforeEach(async ({ page }, testInfo) => {
- * // Extend timeout for all tests running this hook by 30 seconds.
- * testInfo.setTimeout(testInfo.timeout + 30000);
- * });
+ * const locator = page.getByRole('button');
+ * await expect(locator).toHaveScreenshot();
* ```
*
- * @param timeout Timeout in milliseconds.
- */
- setTimeout(timeout: number): void;
-
- /**
- * Unconditionally skip the currently running test. Test is immediately aborted. This is similar to
- * [test.skip([title, details, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-skip).
+ * Note that screenshot assertions only work with Playwright test runner.
+ * @param options
*/
- skip(): void;
+ toHaveScreenshot(options?: {
+ /**
+ * When set to `"disabled"`, stops CSS animations, CSS transitions and Web Animations. Animations get different
+ * treatment depending on their duration:
+ * - finite animations are fast-forwarded to completion, so they'll fire `transitionend` event.
+ * - infinite animations are canceled to initial state, and then played over after the screenshot.
+ *
+ * Defaults to `"disabled"` that disables animations.
+ */
+ animations?: "disabled"|"allow";
- /**
- * Conditionally skips the currently running test with an optional description. This is similar to
- * [test.skip([title, details, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-skip).
- * @param condition A skip condition. Test is skipped when the condition is `true`.
- * @param description Optional description that will be reflected in a test report.
- */
- skip(condition: boolean, description?: string): void;
+ /**
+ * When set to `"hide"`, screenshot will hide text caret. When set to `"initial"`, text caret behavior will not be
+ * changed. Defaults to `"hide"`.
+ */
+ caret?: "hide"|"initial";
- /**
- * Marks the currently running test as "slow", giving it triple the default timeout. This is similar to
- * [test.slow([condition, callback, description])](https://playwright.dev/docs/api/class-test#test-slow).
- */
- slow(): void;
+ /**
+ * Specify locators that should be masked when the screenshot is taken. Masked elements will be overlaid with a pink
+ * box `#FF00FF` (customized by
+ * [`maskColor`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-screenshot-2-option-mask-color))
+ * that completely covers its bounding box. The mask is also applied to invisible elements, see
+ * [Matching only visible elements](https://playwright.dev/docs/locators#matching-only-visible-elements) to disable that.
+ */
+ mask?: Array<Locator>;
- /**
- * Conditionally mark the currently running test as "slow" with an optional description, giving it triple the default
- * timeout. This is similar to
- * [test.slow([condition, callback, description])](https://playwright.dev/docs/api/class-test#test-slow).
- * @param condition Test is marked as "slow" when the condition is `true`.
- * @param description Optional description that will be reflected in a test report.
- */
- slow(condition: boolean, description?: string): void;
+ /**
+ * Specify the color of the overlay box for masked elements, in
+ * [CSS color format](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value). Default color is pink `#FF00FF`.
+ */
+ maskColor?: string;
- /**
- * Returns a path to a snapshot file with the given `pathSegments`. Learn more about
- * [snapshots](https://playwright.dev/docs/test-snapshots).
- *
- * > Note that `pathSegments` accepts path segments to the snapshot file such as `testInfo.snapshotPath('relative',
- * 'path', 'to', 'snapshot.png')`.
- * > However, this path must stay within the snapshots directory for each test file (i.e. `a.spec.js-snapshots`),
- * otherwise it will throw.
- * @param pathSegments The name of the snapshot or the path segments to define the snapshot file path. Snapshots with the same name in the
- * same test file are expected to be the same.
- */
- snapshotPath(...pathSegments: ReadonlyArray<string>): string;
+ /**
+ * An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1`. Default is
+ * configurable with `TestConfig.expect`. Unset by default.
+ */
+ maxDiffPixelRatio?: number;
- /**
- * The list of annotations applicable to the current test. Includes annotations from the test, annotations from all
- * [test.describe([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe) groups the
- * test belongs to and file-level annotations for the test file.
- *
- * Learn more about [test annotations](https://playwright.dev/docs/test-annotations).
- */
- annotations: Array<{
/**
- * Annotation type, for example `'skip'` or `'fail'`.
+ * An acceptable amount of pixels that could be different. Default is configurable with `TestConfig.expect`. Unset by
+ * default.
*/
- type: string;
+ maxDiffPixels?: number;
/**
- * Optional description.
+ * Hides default white background and allows capturing screenshots with transparency. Not applicable to `jpeg` images.
+ * Defaults to `false`.
*/
- description?: string;
- }>;
+ omitBackground?: boolean;
- /**
- * The list of files or buffers attached to the current test. Some reporters show test attachments.
- *
- * To add an attachment, use
- * [testInfo.attach(name[, options])](https://playwright.dev/docs/api/class-testinfo#test-info-attach) instead of
- * directly pushing onto this array.
- */
- attachments: Array<{
/**
- * Attachment name.
+ * When set to `"css"`, screenshot will have a single pixel per each css pixel on the page. For high-dpi devices, this
+ * will keep screenshots small. Using `"device"` option will produce a single pixel per each device pixel, so
+ * screenshots of high-dpi devices will be twice as large or even larger.
+ *
+ * Defaults to `"css"`.
*/
- name: string;
+ scale?: "css"|"device";
/**
- * Content type of this attachment to properly present in the report, for example `'application/json'` or
- * `'image/png'`.
+ * File name containing the stylesheet to apply while making the screenshot. This is where you can hide dynamic
+ * elements, make elements invisible or change their properties to help you creating repeatable screenshots. This
+ * stylesheet pierces the Shadow DOM and applies to the inner frames.
*/
- contentType: string;
+ stylePath?: string|Array<string>;
/**
- * Optional path on the filesystem to the attached file.
+ * An acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between the
+ * same pixel in compared images, between zero (strict) and one (lax), default is configurable with
+ * `TestConfig.expect`. Defaults to `0.2`.
*/
- path?: string;
+ threshold?: number;
/**
- * Optional attachment body used instead of a file.
+ * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
*/
- body?: Buffer;
- }>;
-
- /**
- * Column number where the currently running test is declared.
- */
- column: number;
+ timeout?: number;
+ }): Promise<void>;
/**
- * Processed configuration from the [configuration file](https://playwright.dev/docs/test-configuration).
+ * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an element with the given text. All
+ * nested elements will be considered when computing the text content of the element. You can use regular expressions
+ * for the value as well.
+ *
+ * **Details**
+ *
+ * When `expected` parameter is a string, Playwright will normalize whitespaces and line breaks both in the actual
+ * text and in the expected string before matching. When regular expression is used, the actual text is matched as is.
+ *
+ * **Usage**
+ *
+ * ```js
+ * const locator = page.locator('.title');
+ * await expect(locator).toHaveText(/Welcome, Test User/);
+ * await expect(locator).toHaveText(/Welcome, .*\/);
+ * ```
+ *
+ * If you pass an array as an expected value, the expectations are:
+ * 1. Locator resolves to a list of elements.
+ * 1. The number of elements equals the number of expected values in the array.
+ * 1. Elements from the list have text matching expected array values, one by one, in order.
+ *
+ * For example, consider the following list:
+ *
+ * ```html
+ * <ul>
+ * <li>Text 1</li>
+ * <li>Text 2</li>
+ * <li>Text 3</li>
+ * </ul>
+ * ```
+ *
+ * Let's see how we can use the assertion:
+ *
+ * ```js
+ * // ✓ Has the right items in the right order
+ * await expect(page.locator('ul > li')).toHaveText(['Text 1', 'Text 2', 'Text 3']);
+ *
+ * // ✖ Wrong order
+ * await expect(page.locator('ul > li')).toHaveText(['Text 3', 'Text 2', 'Text 1']);
+ *
+ * // ✖ Last item does not match
+ * await expect(page.locator('ul > li')).toHaveText(['Text 1', 'Text 2', 'Text']);
+ *
+ * // ✖ Locator points to the outer list element, not to the list items
+ * await expect(page.locator('ul')).toHaveText(['Text 1', 'Text 2', 'Text 3']);
+ * ```
+ *
+ * @param expected Expected string or RegExp or a list of those.
+ * @param options
*/
- config: FullConfig;
+ toHaveText(expected: string|RegExp|ReadonlyArray<string|RegExp>, options?: {
+ /**
+ * Whether to perform case-insensitive match.
+ * [`ignoreCase`](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-text-option-ignore-case)
+ * option takes precedence over the corresponding regular expression flag if specified.
+ */
+ ignoreCase?: boolean;
- /**
- * The number of milliseconds the test took to finish. Always zero before the test finishes, either successfully or
- * not. Can be used in
- * [test.afterEach([title, hookFunction])](https://playwright.dev/docs/api/class-test#test-after-each) hook.
- */
- duration: number;
+ /**
+ * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
+ */
+ timeout?: number;
- /**
- * First error thrown during test execution, if any. This is equal to the first element in
- * [testInfo.errors](https://playwright.dev/docs/api/class-testinfo#test-info-errors).
- */
- error?: TestInfoError;
+ /**
+ * Whether to use `element.innerText` instead of `element.textContent` when retrieving DOM node text.
+ */
+ useInnerText?: boolean;
+ }): Promise<void>;
/**
- * Errors thrown during test execution, if any.
+ * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to an element with the given input
+ * value. You can use regular expressions for the value as well.
+ *
+ * **Usage**
+ *
+ * ```js
+ * const locator = page.locator('input[type=number]');
+ * await expect(locator).toHaveValue(/[0-9]/);
+ * ```
+ *
+ * @param value Expected value.
+ * @param options
*/
- errors: Array<TestInfoError>;
+ toHaveValue(value: string|RegExp, options?: {
+ /**
+ * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
+ */
+ timeout?: number;
+ }): Promise<void>;
/**
- * Expected status for the currently running test. This is usually `'passed'`, except for a few cases:
- * - `'skipped'` for skipped tests, e.g. with
- * [test.skip([title, details, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-skip);
- * - `'failed'` for tests marked as failed with
- * [test.fail([title, details, body, condition, callback, description])](https://playwright.dev/docs/api/class-test#test-fail).
+ * Ensures the [Locator](https://playwright.dev/docs/api/class-locator) points to multi-select/combobox (i.e. a
+ * `select` with the `multiple` attribute) and the specified values are selected.
*
- * Expected status is usually compared with the actual
- * [testInfo.status](https://playwright.dev/docs/api/class-testinfo#test-info-status):
+ * **Usage**
*
- * ```js
- * import { test, expect } from '@playwright/test';
+ * For example, given the following element:
*
- * test.afterEach(async ({}, testInfo) => {
- * if (testInfo.status !== testInfo.expectedStatus)
- * console.log(`${testInfo.title} did not run as expected!`);
- * });
+ * ```html
+ * <select id="favorite-colors" multiple>
+ * <option value="R">Red</option>
+ * <option value="G">Green</option>
+ * <option value="B">Blue</option>
+ * </select>
+ * ```
+ *
+ * ```js
+ * const locator = page.locator('id=favorite-colors');
+ * await locator.selectOption(['R', 'G']);
+ * await expect(locator).toHaveValues([/R/, /G/]);
* ```
*
+ * @param values Expected options currently selected.
+ * @param options
*/
- expectedStatus: "passed"|"failed"|"timedOut"|"skipped"|"interrupted";
+ toHaveValues(values: ReadonlyArray<string|RegExp>, options?: {
+ /**
+ * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
+ */
+ timeout?: number;
+ }): Promise<void>;
/**
- * Absolute path to a file where the currently running test is declared.
+ * Asserts that the target element matches the given [accessibility snapshot](https://playwright.dev/docs/aria-snapshots).
+ *
+ * **Usage**
+ *
+ * ```js
+ * await page.goto('https://demo.playwright.dev/todomvc/');
+ * await expect(page.locator('body')).toMatchAriaSnapshot(`
+ * - heading "todos"
+ * - textbox "What needs to be done?"
+ * `);
+ * ```
+ *
+ * @param expected
+ * @param options
*/
- file: string;
+ toMatchAriaSnapshot(expected: string, options?: {
+ /**
+ * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
+ */
+ timeout?: number;
+ }): Promise<void>;
/**
- * Test function as passed to `test(title, testFunction)`.
+ * Asserts that the target element matches the given [accessibility snapshot](https://playwright.dev/docs/aria-snapshots).
+ *
+ * Snapshot is stored in a separate `.aria.yml` file in a location configured by
+ * `expect.toMatchAriaSnapshot.pathTemplate` and/or `snapshotPathTemplate` properties in the configuration file.
+ *
+ * **Usage**
+ *
+ * ```js
+ * await expect(page.locator('body')).toMatchAriaSnapshot();
+ * await expect(page.locator('body')).toMatchAriaSnapshot({ name: 'body.aria.yml' });
+ * ```
+ *
+ * @param options
*/
- fn: Function;
+ toMatchAriaSnapshot(options?: {
+ /**
+ * Name of the snapshot to store in the snapshot folder corresponding to this test. Generates sequential names if not
+ * specified.
+ */
+ name?: string;
- /**
- * Line number where the currently running test is declared.
- */
- line: number;
+ /**
+ * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
+ */
+ timeout?: number;
+ }): Promise<void>;
/**
- * Absolute path to the output directory for this specific test run. Each test run gets its own directory so they
- * cannot conflict.
+ * Makes the assertion check for the opposite condition. For example, this code tests that the Locator doesn't contain
+ * text `"error"`:
+ *
+ * ```js
+ * await expect(locator).not.toContainText('error');
+ * ```
+ *
*/
- outputDir: string;
+ not: LocatorAssertions;
+}
+/**
+ * The [PageAssertions](https://playwright.dev/docs/api/class-pageassertions) class provides assertion methods that
+ * can be used to make assertions about the [Page](https://playwright.dev/docs/api/class-page) state in the tests.
+ *
+ * ```js
+ * import { test, expect } from '@playwright/test';
+ *
+ * test('navigates to login', async ({ page }) => {
+ * // ...
+ * await page.getByText('Sign in').click();
+ * await expect(page).toHaveURL(/.*\/login/);
+ * });
+ * ```
+ *
+ */
+interface PageAssertions {
/**
- * The index of the worker between `0` and `workers - 1`. It is guaranteed that workers running at the same time have
- * a different `parallelIndex`. When a worker is restarted, for example after a failure, the new worker process has
- * the same `parallelIndex`.
+ * This function will wait until two consecutive page screenshots yield the same result, and then compare the last
+ * screenshot with the expectation.
*
- * Also available as `process.env.TEST_PARALLEL_INDEX`. Learn more about
- * [parallelism and sharding](https://playwright.dev/docs/test-parallel) with Playwright Test.
+ * **Usage**
+ *
+ * ```js
+ * await expect(page).toHaveScreenshot('image.png');
+ * ```
+ *
+ * Note that screenshot assertions only work with Playwright test runner.
+ * @param name Snapshot name.
+ * @param options
*/
- parallelIndex: number;
+ toHaveScreenshot(name: string|ReadonlyArray<string>, options?: PageAssertionsToHaveScreenshotOptions): Promise<void>;
/**
- * Processed project configuration from the [configuration file](https://playwright.dev/docs/test-configuration).
+ * This function will wait until two consecutive page screenshots yield the same result, and then compare the last
+ * screenshot with the expectation.
+ *
+ * **Usage**
+ *
+ * ```js
+ * await expect(page).toHaveScreenshot();
+ * ```
+ *
+ * Note that screenshot assertions only work with Playwright test runner.
+ * @param options
*/
- project: FullProject;
+ toHaveScreenshot(options?: PageAssertionsToHaveScreenshotOptions): Promise<void>;
/**
- * Specifies a unique repeat index when running in "repeat each" mode. This mode is enabled by passing `--repeat-each`
- * to the [command line](https://playwright.dev/docs/test-cli).
+ * Ensures the page has the given title.
+ *
+ * **Usage**
+ *
+ * ```js
+ * await expect(page).toHaveTitle(/.*checkout/);
+ * ```
+ *
+ * @param titleOrRegExp Expected title or RegExp.
+ * @param options
*/
- repeatEachIndex: number;
+ toHaveTitle(titleOrRegExp: string|RegExp, options?: {
+ /**
+ * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
+ */
+ timeout?: number;
+ }): Promise<void>;
/**
- * Specifies the retry number when the test is retried after a failure. The first test run has
- * [testInfo.retry](https://playwright.dev/docs/api/class-testinfo#test-info-retry) equal to zero, the first retry has
- * it equal to one, and so on. Learn more about [retries](https://playwright.dev/docs/test-retries#retries).
+ * Ensures the page is navigated to the given URL.
+ *
+ * **Usage**
*
* ```js
- * import { test, expect } from '@playwright/test';
+ * // Check for the page URL to be 'https://playwright.dev/docs/intro' (including query string)
+ * await expect(page).toHaveURL('https://playwright.dev/docs/intro');
*
- * test.beforeEach(async ({}, testInfo) => {
- * // You can access testInfo.retry in any hook or fixture.
- * if (testInfo.retry > 0)
- * console.log(`Retrying!`);
- * });
+ * // Check for the page URL to contain 'doc', followed by an optional 's', followed by '/'
+ * await expect(page).toHaveURL(/docs?\//);
*
- * test('my test', async ({ page }, testInfo) => {
- * // Here we clear some server-side state when retrying.
- * if (testInfo.retry)
- * await cleanSomeCachesOnTheServer();
- * // ...
+ * // Check for the predicate to be satisfied
+ * // For example: verify query strings
+ * await expect(page).toHaveURL(url => {
+ * const params = url.searchParams;
+ * return params.has('search') && params.has('options') && params.get('id') === '5';
* });
* ```
*
+ * @param url Expected URL string, RegExp, or predicate receiving [URL] to match. When
+ * [`baseURL`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-base-url) is provided via the
+ * context options and the `url` argument is a string, the two values are merged via the
+ * [`new URL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) constructor and used for the comparison
+ * against the current browser URL.
+ * @param options
*/
- retry: number;
+ toHaveURL(url: string|RegExp|((url: URL) => boolean), options?: {
+ /**
+ * Whether to perform case-insensitive match.
+ * [`ignoreCase`](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-url-option-ignore-case)
+ * option takes precedence over the corresponding regular expression parameter if specified. A provided predicate
+ * ignores this flag.
+ */
+ ignoreCase?: boolean;
- /**
- * Absolute path to the snapshot output directory for this specific test. Each test suite gets its own directory so
- * they cannot conflict.
- *
- * This property does not account for the
- * [testProject.snapshotPathTemplate](https://playwright.dev/docs/api/class-testproject#test-project-snapshot-path-template)
- * configuration.
- */
- snapshotDir: string;
+ /**
+ * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
+ */
+ timeout?: number;
+ }): Promise<void>;
/**
- * **NOTE** Use of [testInfo.snapshotSuffix](https://playwright.dev/docs/api/class-testinfo#test-info-snapshot-suffix)
- * is discouraged. Please use
- * [testConfig.snapshotPathTemplate](https://playwright.dev/docs/api/class-testconfig#test-config-snapshot-path-template)
- * to configure snapshot paths.
+ * Makes the assertion check for the opposite condition. For example, this code tests that the page URL doesn't
+ * contain `"error"`:
+ *
+ * ```js
+ * await expect(page).not.toHaveURL('error');
+ * ```
*
- * Suffix used to differentiate snapshots between multiple test configurations. For example, if snapshots depend on
- * the platform, you can set `testInfo.snapshotSuffix` equal to `process.platform`. In this case
- * `expect(value).toMatchSnapshot(snapshotName)` will use different snapshots depending on the platform. Learn more
- * about [snapshots](https://playwright.dev/docs/test-snapshots).
*/
- snapshotSuffix: string;
+ not: PageAssertions;
+}
+/**
+ * Playwright provides methods for comparing page and element screenshots with expected values stored in files.
+ *
+ * ```js
+ * expect(screenshot).toMatchSnapshot('landing-page.png');
+ * ```
+ *
+ */
+interface SnapshotAssertions {
/**
- * Actual status for the currently running test. Available after the test has finished in
- * [test.afterEach([title, hookFunction])](https://playwright.dev/docs/api/class-test#test-after-each) hook and
- * fixtures.
+ * **NOTE** To compare screenshots, use
+ * [expect(page).toHaveScreenshot(name[, options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1)
+ * instead.
*
- * Status is usually compared with the
- * [testInfo.expectedStatus](https://playwright.dev/docs/api/class-testinfo#test-info-expected-status):
+ * Ensures that passed value, either a [string] or a [Buffer], matches the expected snapshot stored in the test
+ * snapshots directory.
+ *
+ * **Usage**
*
* ```js
- * import { test, expect } from '@playwright/test';
+ * // Basic usage.
+ * expect(await page.screenshot()).toMatchSnapshot('landing-page.png');
*
- * test.afterEach(async ({}, testInfo) => {
- * if (testInfo.status !== testInfo.expectedStatus)
- * console.log(`${testInfo.title} did not run as expected!`);
+ * // Pass options to customize the snapshot comparison and have a generated name.
+ * expect(await page.screenshot()).toMatchSnapshot('landing-page.png', {
+ * maxDiffPixels: 27, // allow no more than 27 different pixels.
* });
- * ```
*
- */
- status?: "passed"|"failed"|"timedOut"|"skipped"|"interrupted";
-
- /**
- * Tags that apply to the test. Learn more about [tags](https://playwright.dev/docs/test-annotations#tag-tests).
+ * // Configure image matching threshold.
+ * expect(await page.screenshot()).toMatchSnapshot('landing-page.png', { threshold: 0.3 });
*
- * **NOTE** Any changes made to this list while the test is running will not be visible to test reporters.
+ * // Bring some structure to your snapshot files by passing file path segments.
+ * expect(await page.screenshot()).toMatchSnapshot(['landing', 'step2.png']);
+ * expect(await page.screenshot()).toMatchSnapshot(['landing', 'step3.png']);
+ * ```
+ *
+ * Learn more about [visual comparisons](https://playwright.dev/docs/test-snapshots).
*
+ * Note that matching snapshots only work with Playwright test runner.
+ * @param name Snapshot name.
+ * @param options
*/
- tags: Array<string>;
+ toMatchSnapshot(name: string|ReadonlyArray<string>, options?: {
+ /**
+ * An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1`. Default is
+ * configurable with `TestConfig.expect`. Unset by default.
+ */
+ maxDiffPixelRatio?: number;
- /**
- * Test id matching the test case id in the reporter API.
- */
- testId: string;
+ /**
+ * An acceptable amount of pixels that could be different. Default is configurable with `TestConfig.expect`. Unset by
+ * default.
+ */
+ maxDiffPixels?: number;
+
+ /**
+ * An acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between the
+ * same pixel in compared images, between zero (strict) and one (lax), default is configurable with
+ * `TestConfig.expect`. Defaults to `0.2`.
+ */
+ threshold?: number;
+ }): void;
/**
- * Timeout in milliseconds for the currently running test. Zero means no timeout. Learn more about
- * [various timeouts](https://playwright.dev/docs/test-timeouts).
+ * **NOTE** To compare screenshots, use
+ * [expect(page).toHaveScreenshot([options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-2)
+ * instead.
*
- * Timeout is usually specified in the [configuration file](https://playwright.dev/docs/test-configuration)
+ * Ensures that passed value, either a [string] or a [Buffer], matches the expected snapshot stored in the test
+ * snapshots directory.
+ *
+ * **Usage**
*
* ```js
- * import { test, expect } from '@playwright/test';
+ * // Basic usage and the file name is derived from the test name.
+ * expect(await page.screenshot()).toMatchSnapshot();
*
- * test.beforeEach(async ({ page }, testInfo) => {
- * // Extend timeout for all tests running this hook by 30 seconds.
- * testInfo.setTimeout(testInfo.timeout + 30000);
+ * // Pass options to customize the snapshot comparison and have a generated name.
+ * expect(await page.screenshot()).toMatchSnapshot({
+ * maxDiffPixels: 27, // allow no more than 27 different pixels.
+ * });
+ *
+ * // Configure image matching threshold and snapshot name.
+ * expect(await page.screenshot()).toMatchSnapshot({
+ * name: 'landing-page.png',
+ * threshold: 0.3,
* });
* ```
*
+ * Learn more about [visual comparisons](https://playwright.dev/docs/test-snapshots).
+ *
+ * Note that matching snapshots only work with Playwright test runner.
+ * @param options
*/
- timeout: number;
+ toMatchSnapshot(options?: {
+ /**
+ * An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1`. Default is
+ * configurable with `TestConfig.expect`. Unset by default.
+ */
+ maxDiffPixelRatio?: number;
+
+ /**
+ * An acceptable amount of pixels that could be different. Default is configurable with `TestConfig.expect`. Unset by
+ * default.
+ */
+ maxDiffPixels?: number;
+
+ /**
+ * Snapshot name. If not passed, the test name and ordinals are used when called multiple times.
+ */
+ name?: string|Array<string>;
+
+ /**
+ * An acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between the
+ * same pixel in compared images, between zero (strict) and one (lax), default is configurable with
+ * `TestConfig.expect`. Defaults to `0.2`.
+ */
+ threshold?: number;
+ }): void;
+}
+/**
+ * Represents a location in the source code where [TestCase] or [Suite] is defined.
+ */
+export interface Location {
/**
- * The title of the currently running test as passed to `test(title, testFunction)`.
+ * Column number in the source file.
*/
- title: string;
+ column: number;
/**
- * The full title path starting with the test file name.
+ * Path to the source file.
*/
- titlePath: Array<string>;
+ file: string;
/**
- * The unique index of the worker process that is running the test. When a worker is restarted, for example after a
- * failure, the new worker process gets a new unique `workerIndex`.
- *
- * Also available as `process.env.TEST_WORKER_INDEX`. Learn more about [parallelism and sharding](https://playwright.dev/docs/test-parallel)
- * with Playwright Test.
+ * Line number in the source file.
*/
- workerIndex: number;
+ line: number;
}
/**
diff --git a/tests/playwright-test/aria-snapshot-file.spec.ts b/tests/playwright-test/aria-snapshot-file.spec.ts
index 9ccc37e3c0..a64945dfbe 100644
--- a/tests/playwright-test/aria-snapshot-file.spec.ts
+++ b/tests/playwright-test/aria-snapshot-file.spec.ts
@@ -201,14 +201,19 @@ test('should respect config.snapshotPathTemplate', async ({ runInlineTest }, tes
snapshotPathTemplate: 'my-snapshots/{testFilePath}/{arg}{ext}',
};
`,
- 'my-snapshots/dir/a.spec.ts/test.aria.yml': `
+ 'my-snapshots/dir/a.spec.ts/my-test.aria.yml': `
- heading "hello world"
`,
'dir/a.spec.ts': `
+ import path from 'path';
import { test, expect } from '@playwright/test';
test('test', async ({ page }) => {
+ const testDir = test.info().project.testDir;
+ const screenshotPath = path.join(testDir, 'my-snapshots/dir/a.spec.ts/my-test.aria.yml');
+ expect(test.info().snapshotPath('my_test.aria.yml', { kind: 'aria' })).toBe(screenshotPath);
+
await page.setContent(\`<h1>hello world</h1>\`);
- await expect(page.locator('body')).toMatchAriaSnapshot({ name: 'test.aria.yml' });
+ await expect(page.locator('body')).toMatchAriaSnapshot({ name: 'my_test.aria.yml' });
});
`
});
diff --git a/tests/playwright-test/snapshot-path-template.spec.ts b/tests/playwright-test/snapshot-path-template.spec.ts
index 2fd79403f4..f1224b9563 100644
--- a/tests/playwright-test/snapshot-path-template.spec.ts
+++ b/tests/playwright-test/snapshot-path-template.spec.ts
@@ -137,3 +137,18 @@ test('arg should receive default arg', async ({ runInlineTest }, testInfo) => {
expect(result.output).toContain(`A snapshot doesn't exist at ${snapshotOutputPath}, writing actual`);
expect(fs.existsSync(snapshotOutputPath)).toBe(true);
});
+
+test('should throw for unknown snapshot kind', async ({ runInlineTest }, testInfo) => {
+ const result = await runInlineTest({
+ 'a.spec.ts': `
+ import { test, expect } from '@playwright/test';
+ test('is a test', async ({}) => {
+ test.info().snapshotPath('foo', { kind: 'bar' });
+ });
+ `
+ });
+
+ expect(result.exitCode).toBe(1);
+ expect(result.passed).toBe(0);
+ expect(result.output).toContain(`testInfo.snapshotPath: unknown kind "bar"`);
+});
diff --git a/tests/playwright-test/to-have-screenshot.spec.ts b/tests/playwright-test/to-have-screenshot.spec.ts
index aedfb477e9..d57b7f04e2 100644
--- a/tests/playwright-test/to-have-screenshot.spec.ts
+++ b/tests/playwright-test/to-have-screenshot.spec.ts
@@ -782,8 +782,17 @@ test('should respect config.expect.toHaveScreenshot.pathTemplate', async ({ runI
'__screenshots__/a.spec.js/snapshot.png': blueImage,
'actual-screenshots/a.spec.js/snapshot.png': whiteImage,
'a.spec.js': `
+ const path = require('path');
const { test, expect } = require('@playwright/test');
test('is a test', async ({ page }) => {
+ const testDir = test.info().project.testDir;
+
+ const screenshotPath = path.join(testDir, 'actual-screenshots/a.spec.js/snapshot.png');
+ expect(test.info().snapshotPath('snapshot.png', { kind: 'screenshot' })).toBe(screenshotPath);
+
+ const snapshotPath = path.join(testDir, '__screenshots__/a.spec.js/snapshot.png');
+ expect(test.info().snapshotPath('snapshot.png', { kind: 'snapshot' })).toBe(snapshotPath);
+
await expect(page).toHaveScreenshot('snapshot.png');
});
`
diff --git a/tests/playwright-test/types-2.spec.ts b/tests/playwright-test/types-2.spec.ts
index 81959d51c8..93b941bd5e 100644
--- a/tests/playwright-test/types-2.spec.ts
+++ b/tests/playwright-test/types-2.spec.ts
@@ -29,6 +29,11 @@ test('basics should work', async ({ runTSC }) => {
expect(testInfo.title).toBe('my test');
testInfo.annotations[0].type;
test.setTimeout(123);
+ testInfo.snapshotPath('a', 'b');
+ testInfo.snapshotPath();
+ testInfo.snapshotPath('foo.png', { kind: 'screenshot' });
+ // @ts-expect-error
+ testInfo.snapshotPath('a', 'b', { kind: 'aria' });
});
test.skip('my test', async () => {});
test.fixme('my test', async () => {});
diff --git a/utils/generate_types/overrides-test.d.ts b/utils/generate_types/overrides-test.d.ts
index 30a16a04d9..c6d365b670 100644
--- a/utils/generate_types/overrides-test.d.ts
+++ b/utils/generate_types/overrides-test.d.ts
@@ -63,6 +63,11 @@ export interface FullConfig<TestArgs = {}, WorkerArgs = {}> {
webServer: TestConfigWebServer | null;
}
+export interface TestInfo {
+ snapshotPath(...name: ReadonlyArray<string>): string;
+ snapshotPath(name: string, options: { kind: 'snapshot' | 'screenshot' | 'aria' }): string;
+}
+
export type TestStatus = 'passed' | 'failed' | 'timedOut' | 'skipped' | 'interrupted';
export type TestDetailsAnnotation = {