yujunjun/playwright
1
0
Fork 0
mirror of https://github.com/microsoft/playwright.git synced 2025-06-26 21:40:17 +00:00
Code Issues Packages Projects Releases Wiki Activity

chore(docs): sort members instead of validating (#20755)

Browse Source
This commit is contained in:
Dmitry Gozman 2023-02-08 09:59:31 -08:00 committed by GitHub
parent 0678b6575f
commit 98e2fe184e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 477 additions and 508 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

80
packages/playwright-core/types/types.d.ts vendored
View File

@ -1748,13 +1748,6 @@ export interface Page {
*/ */
prependListener(event: 'worker', listener: (worker: Worker) => void): this; prependListener(event: 'worker', listener: (worker: Worker) => void): this;
/**
* @deprecated This property is discouraged. Please use other libraries such as [Axe](https://www.deque.com/axe/) if you need to
* test page accessibility. See our Node.js [guide](https://playwright.dev/docs/accessibility-testing) for integration
* with Axe.
*/
accessibility: Accessibility;
/** /**
* Adds a `<script>` tag into the page with the desired url or content. Returns the added tag when the script's onload * Adds a `<script>` tag into the page with the desired url or content. Returns the added tag when the script's onload
* fires or when the script content was injected into frame. * fires or when the script content was injected into frame.
@ -1990,13 +1983,6 @@ export interface Page {
*/ */
context(): BrowserContext; context(): BrowserContext;
/**
* **NOTE** Only available for Chromium atm.
*
* Browser-specific Coverage implementation. See [Coverage] for more details.
*/
coverage: Coverage;
/** /**
* **NOTE** Use locator-based [locator.dblclick([options])](https://playwright.dev/docs/api/class-locator#locator-dblclick) * **NOTE** Use locator-based [locator.dblclick([options])](https://playwright.dev/docs/api/class-locator#locator-dblclick)
* instead. Read more about [locators](https://playwright.dev/docs/locators). * instead. Read more about [locators](https://playwright.dev/docs/locators).
@ -3194,8 +3180,6 @@ export interface Page {
timeout?: number; timeout?: number;
}): Promise<boolean>; }): Promise<boolean>;
keyboard: Keyboard;
/** /**
* The method returns an element locator that can be used to perform actions on this page / frame. Locator is resolved * The method returns an element locator that can be used to perform actions on this page / frame. Locator is resolved
* to the element immediately before performing an action, so a series of actions on the same locator can in fact be * to the element immediately before performing an action, so a series of actions on the same locator can in fact be
@ -3227,8 +3211,6 @@ export interface Page {
*/ */
mainFrame(): Frame; mainFrame(): Frame;
mouse: Mouse;
/** /**
* Returns the opener for popup pages and `null` for others. If the opener has been closed already the returns `null`. * Returns the opener for popup pages and `null` for others. If the opener has been closed already the returns `null`.
*/ */
@ -3496,15 +3478,6 @@ export interface Page {
waitUntil?: "load"|"domcontentloaded"|"networkidle"|"commit"; waitUntil?: "load"|"domcontentloaded"|"networkidle"|"commit";
}): Promise<null|Response>; }): Promise<null|Response>;
/**
* API testing helper associated with this page. This method returns the same instance as
* [browserContext.request](https://playwright.dev/docs/api/class-browsercontext#browser-context-request) on the
* page's context. See
* [browserContext.request](https://playwright.dev/docs/api/class-browsercontext#browser-context-request) for more
* details.
*/
request: APIRequestContext;
/** /**
* Routing provides the capability to modify network requests that are made by a page. * Routing provides the capability to modify network requests that are made by a page.
* *
@ -4055,8 +4028,6 @@ export interface Page {
*/ */
title(): Promise<string>; title(): Promise<string>;
touchscreen: Touchscreen;
/** /**
* **NOTE** Use locator-based [locator.type(text[, options])](https://playwright.dev/docs/api/class-locator#locator-type) * **NOTE** Use locator-based [locator.type(text[, options])](https://playwright.dev/docs/api/class-locator#locator-type)
* instead. Read more about [locators](https://playwright.dev/docs/locators). * instead. Read more about [locators](https://playwright.dev/docs/locators).
@ -4620,7 +4591,36 @@ export interface Page {
* *
* **NOTE** This does not contain ServiceWorkers * **NOTE** This does not contain ServiceWorkers
*/ */
workers(): Array<Worker>;} workers(): Array<Worker>;
/**
* @deprecated This property is discouraged. Please use other libraries such as [Axe](https://www.deque.com/axe/) if you need to
* test page accessibility. See our Node.js [guide](https://playwright.dev/docs/accessibility-testing) for integration
* with Axe.
*/
accessibility: Accessibility;
/**
* **NOTE** Only available for Chromium atm.
*
* Browser-specific Coverage implementation. See [Coverage] for more details.
*/
coverage: Coverage;
keyboard: Keyboard;
mouse: Mouse;
/**
* API testing helper associated with this page. This method returns the same instance as
* [browserContext.request](https://playwright.dev/docs/api/class-browsercontext#browser-context-request) on the
* page's context. See
* [browserContext.request](https://playwright.dev/docs/api/class-browsercontext#browser-context-request) for more
* details.
*/
request: APIRequestContext;
touchscreen: Touchscreen;}
/** /**
* At every point of time, page exposes its current frame tree via the * At every point of time, page exposes its current frame tree via the
@ -7978,11 +7978,6 @@ export interface BrowserContext {
*/ */
pages(): Array<Page>; pages(): Array<Page>;
/**
* API testing helper associated with this context. Requests made with this API will use context cookies.
*/
request: APIRequestContext;
/** /**
* Routing provides the capability to modify network requests that are made by any page in the browser context. Once * Routing provides the capability to modify network requests that are made by any page in the browser context. Once
* route is enabled, every request matching the url pattern will stall unless it's continued, fulfilled or aborted. * route is enabled, every request matching the url pattern will stall unless it's continued, fulfilled or aborted.
@ -8223,8 +8218,6 @@ export interface BrowserContext {
}>; }>;
}>; }>;
tracing: Tracing;
/** /**
* Removes a route created with * Removes a route created with
* [browserContext.route(url, handler[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route). * [browserContext.route(url, handler[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-route).
@ -8323,7 +8316,14 @@ export interface BrowserContext {
* Emitted when new service worker is created in the context. * Emitted when new service worker is created in the context.
*/ */
waitForEvent(event: 'serviceworker', optionsOrPredicate?: { predicate?: (worker: Worker) => boolean | Promise<boolean>, timeout?: number } | ((worker: Worker) => boolean | Promise<boolean>)): Promise<Worker>; waitForEvent(event: 'serviceworker', optionsOrPredicate?: { predicate?: (worker: Worker) => boolean | Promise<boolean>, timeout?: number } | ((worker: Worker) => boolean | Promise<boolean>)): Promise<Worker>;
}
/**
* API testing helper associated with this context. Requests made with this API will use context cookies.
*/
request: APIRequestContext;
tracing: Tracing;}
/** /**
* The Worker class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). * The Worker class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API).
@ -13560,8 +13560,6 @@ export interface AndroidDevice {
*/ */
info(selector: AndroidSelector): Promise<AndroidElementInfo>; info(selector: AndroidSelector): Promise<AndroidElementInfo>;
input: AndroidInput;
/** /**
* Installs an apk on the device. * Installs an apk on the device.
* @param file Either a path to the apk file, or apk file content. * @param file Either a path to the apk file, or apk file content.
@ -14153,6 +14151,8 @@ export interface AndroidDevice {
* Currently open WebViews. * Currently open WebViews.
*/ */
webViews(): Array<AndroidWebView>; webViews(): Array<AndroidWebView>;
input: AndroidInput;
} }
export interface AndroidInput { export interface AndroidInput {

750
packages/playwright-test/types/test.d.ts vendored
View File

@ -879,135 +879,6 @@ interface TestConfig {
*/ */
outputDir?: string; outputDir?: string;
/**
* **NOTE** Use
* [testConfig.snapshotPathTemplate](https://playwright.dev/docs/api/class-testconfig#test-config-snapshot-path-template)
* to configure snapshot paths.
*
* The base directory, relative to the config file, for snapshot files created with `toMatchSnapshot`. Defaults to
* [testConfig.testDir](https://playwright.dev/docs/api/class-testconfig#test-config-test-dir).
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* snapshotDir: './snapshots',
* });
* ```
*
* **Details**
*
* 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).
*
* 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)
* would resolve to `snapshots/a.spec.js-snapshots`.
*/
snapshotDir?: string;
/**
* This option configures a template controlling location of snapshots generated by
* [pageAssertions.toHaveScreenshot(name[, options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1)
* and
* [snapshotAssertions.toMatchSnapshot(name[, options])](https://playwright.dev/docs/api/class-snapshotassertions#snapshot-assertions-to-match-snapshot-1).
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* testDir: './tests',
* snapshotPathTemplate: '{testDir}/__screenshots__/{testFilePath}/{arg}{ext}',
* });
* ```
*
* **Details**
*
* The value might include some "tokens" that will be replaced with actual values during test execution.
*
* Consider the following file structure:
*
* ```
* playwright.config.ts
* tests/
* └── page/
* └── page-click.spec.ts
* ```
*
* And the following `page-click.spec.ts` that uses `toHaveScreenshot()` call:
*
* ```js
* // page-click.spec.ts
* import { test, expect } from '@playwright/test';
*
* test.describe('suite', () => {
* test('test should work', async ({ page }) => {
* await expect(page).toHaveScreenshot(['foo', 'bar', 'baz.png']);
* });
* });
* ```
*
* The list of supported tokens:
* - `{testDir}` - Project's
* [testConfig.testDir](https://playwright.dev/docs/api/class-testconfig#test-config-test-dir).
* - Value: `/home/playwright/tests` (absolute path is since `testDir` is resolved relative to directory with
* config)
* - `{snapshotDir}` - Project's
* [testConfig.snapshotDir](https://playwright.dev/docs/api/class-testconfig#test-config-snapshot-dir).
* - Value: `/home/playwright/tests` (since `snapshotDir` is not provided in config, it defaults to `testDir`)
* - `{platform}` - The value of `process.platform`.
* - `{projectName}` - Project's file-system-sanitized name, if any.
* - Value: `''` (empty string).
* - `{testFileDir}` - Directories in relative path from `testDir` to **test file**.
* - Value: `page`
* - `{testFileName}` - Test file name with extension.
* - Value: `page-click.spec.ts`
* - `{testFilePath}` - Relative path from `testDir` to **test file**
* - Value: `page/page-click.spec.ts`
* - `{testName}` - File-system-sanitized test title, including parent describes but excluding file name.
* - Value: `suite-test-should-work`
* - `{arg}` - Relative snapshot path **without extension**. These come from the arguments passed to the
* `toHaveScreenshot()` and `toMatchSnapshot()` calls; if called without arguments, this will be an auto-generated
* snapshot name.
* - Value: `foo/bar/baz`
* - `{ext}` - snapshot extension (with dots)
* - Value: `.png`
*
* Each token can be preceded with a single character that will be used **only if** this token has non-empty value.
*
* Consider the following config:
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* snapshotPathTemplate: '__screenshots__{/projectName}/{testFilePath}/{arg}{ext}',
* testMatch: 'example.spec.ts',
* projects: [
* { use: { browserName: 'firefox' } },
* { name: 'chromium', use: { browserName: 'chromium' } },
* ],
* });
* ```
*
* In this config:
* 1. First project **does not** have a name, so its snapshots will be stored in
* `<configDir>/__screenshots__/example.spec.ts/...`.
* 1. Second project **does** have a name, so its snapshots will be stored in
* `<configDir>/__screenshots__/chromium/example.spec.ts/..`.
* 1. Since `snapshotPathTemplate` resolves to relative path, it will be resolved relative to `configDir`.
* 1. Forward slashes `"/"` can be used as path separators on any platform.
*/
snapshotPathTemplate?: string;
/** /**
* Whether to preserve test output in the * Whether to preserve test output in the
* [testConfig.outputDir](https://playwright.dev/docs/api/class-testconfig#test-config-output-dir). Defaults to * [testConfig.outputDir](https://playwright.dev/docs/api/class-testconfig#test-config-output-dir). Defaults to
@ -1161,6 +1032,135 @@ interface TestConfig {
current: number; current: number;
}; };
/**
* **NOTE** Use
* [testConfig.snapshotPathTemplate](https://playwright.dev/docs/api/class-testconfig#test-config-snapshot-path-template)
* to configure snapshot paths.
*
* The base directory, relative to the config file, for snapshot files created with `toMatchSnapshot`. Defaults to
* [testConfig.testDir](https://playwright.dev/docs/api/class-testconfig#test-config-test-dir).
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* snapshotDir: './snapshots',
* });
* ```
*
* **Details**
*
* 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).
*
* 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)
* would resolve to `snapshots/a.spec.js-snapshots`.
*/
snapshotDir?: string;
/**
* This option configures a template controlling location of snapshots generated by
* [pageAssertions.toHaveScreenshot(name[, options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1)
* and
* [snapshotAssertions.toMatchSnapshot(name[, options])](https://playwright.dev/docs/api/class-snapshotassertions#snapshot-assertions-to-match-snapshot-1).
*
* **Usage**
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* testDir: './tests',
* snapshotPathTemplate: '{testDir}/__screenshots__/{testFilePath}/{arg}{ext}',
* });
* ```
*
* **Details**
*
* The value might include some "tokens" that will be replaced with actual values during test execution.
*
* Consider the following file structure:
*
* ```
* playwright.config.ts
* tests/
* └── page/
* └── page-click.spec.ts
* ```
*
* And the following `page-click.spec.ts` that uses `toHaveScreenshot()` call:
*
* ```js
* // page-click.spec.ts
* import { test, expect } from '@playwright/test';
*
* test.describe('suite', () => {
* test('test should work', async ({ page }) => {
* await expect(page).toHaveScreenshot(['foo', 'bar', 'baz.png']);
* });
* });
* ```
*
* The list of supported tokens:
* - `{testDir}` - Project's
* [testConfig.testDir](https://playwright.dev/docs/api/class-testconfig#test-config-test-dir).
* - Value: `/home/playwright/tests` (absolute path is since `testDir` is resolved relative to directory with
* config)
* - `{snapshotDir}` - Project's
* [testConfig.snapshotDir](https://playwright.dev/docs/api/class-testconfig#test-config-snapshot-dir).
* - Value: `/home/playwright/tests` (since `snapshotDir` is not provided in config, it defaults to `testDir`)
* - `{platform}` - The value of `process.platform`.
* - `{projectName}` - Project's file-system-sanitized name, if any.
* - Value: `''` (empty string).
* - `{testFileDir}` - Directories in relative path from `testDir` to **test file**.
* - Value: `page`
* - `{testFileName}` - Test file name with extension.
* - Value: `page-click.spec.ts`
* - `{testFilePath}` - Relative path from `testDir` to **test file**
* - Value: `page/page-click.spec.ts`
* - `{testName}` - File-system-sanitized test title, including parent describes but excluding file name.
* - Value: `suite-test-should-work`
* - `{arg}` - Relative snapshot path **without extension**. These come from the arguments passed to the
* `toHaveScreenshot()` and `toMatchSnapshot()` calls; if called without arguments, this will be an auto-generated
* snapshot name.
* - Value: `foo/bar/baz`
* - `{ext}` - snapshot extension (with dots)
* - Value: `.png`
*
* Each token can be preceded with a single character that will be used **only if** this token has non-empty value.
*
* Consider the following config:
*
* ```js
* // playwright.config.ts
* import { defineConfig } from '@playwright/test';
*
* export default defineConfig({
* snapshotPathTemplate: '__screenshots__{/projectName}/{testFilePath}/{arg}{ext}',
* testMatch: 'example.spec.ts',
* projects: [
* { use: { browserName: 'firefox' } },
* { name: 'chromium', use: { browserName: 'chromium' } },
* ],
* });
* ```
*
* In this config:
* 1. First project **does not** have a name, so its snapshots will be stored in
* `<configDir>/__screenshots__/example.spec.ts/...`.
* 1. Second project **does** have a name, so its snapshots will be stored in
* `<configDir>/__screenshots__/chromium/example.spec.ts/..`.
* 1. Since `snapshotPathTemplate` resolves to relative path, it will be resolved relative to `configDir`.
* 1. Forward slashes `"/"` can be used as path separators on any platform.
*/
snapshotPathTemplate?: string;
/** /**
* Directory that will be recursively scanned for test files. Defaults to the directory of the configuration file. * Directory that will be recursively scanned for test files. Defaults to the directory of the configuration file.
* *
@ -1861,55 +1861,6 @@ export interface TestInfo {
* Processed project configuration from the [configuration file](https://playwright.dev/docs/test-configuration). * Processed project configuration from the [configuration file](https://playwright.dev/docs/test-configuration).
*/ */
project: FullProject; project: FullProject;
/**
* The list of annotations applicable to the current test. Includes annotations from the test, annotations from all
* [test.describe(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-1) 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;
}>;
/** /**
* Attach a value or a file from disk to the current test. Some reporters show test attachments. Either `path` or * Attach a value or a file from disk to the current test. Some reporters show test attachments. Either `path` or
* `body` must be specified, but not both. * `body` must be specified, but not both.
@ -1963,50 +1914,6 @@ export interface TestInfo {
path?: string; path?: string;
}): Promise<void>; }): Promise<void>;
/**
* Column number where the currently running test is declared.
*/
column: number;
/**
* 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(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()](https://playwright.dev/docs/api/class-test#test-skip-2);
* - `'failed'` for tests marked as failed with
* [test.fail()](https://playwright.dev/docs/api/class-test#test-fail-1).
*
* 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";
/** /**
* Marks the currently running test as "should fail". Playwright Test runs this test and ensures that it is actually * 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 * failing. This is useful for documentation purposes to acknowledge that some functionality is broken until it is
@ -2022,11 +1929,6 @@ export interface TestInfo {
*/ */
fail(condition: boolean, description?: string): void; fail(condition: boolean, description?: string): void;
/**
* Absolute path to a file where the currently running test is declared.
*/
file: string;
/** /**
* Mark a test as "fixme", with the intention to fix it. Test is immediately aborted. This is similar to * Mark a test as "fixme", with the intention to fix it. Test is immediately aborted. This is similar to
* [test.fixme()](https://playwright.dev/docs/api/class-test#test-fixme-2). * [test.fixme()](https://playwright.dev/docs/api/class-test#test-fixme-2).
@ -2041,32 +1943,6 @@ export interface TestInfo {
*/ */
fixme(condition: boolean, description?: string): void; fixme(condition: boolean, description?: string): void;
/**
* 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 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;
/**
* Absolute path to the output directory for this specific test run. Each test run gets its own directory so they
* cannot conflict.
*/
outputDir: string;
/** /**
* Returns a path inside the [testInfo.outputDir](https://playwright.dev/docs/api/class-testinfo#test-info-output-dir) * 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 * where the test can safely put a temporary file. Guarantees that tests running in parallel will not interfere with
@ -2091,47 +1967,6 @@ export interface TestInfo {
*/ */
outputPath(...pathSegments: Array<string>): string; outputPath(...pathSegments: Array<string>): 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;
/**
* 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;
/** /**
* Changes the timeout for the currently running test. Zero means no timeout. Learn more about * Changes the timeout for the currently running test. Zero means no timeout. Learn more about
* [various timeouts](https://playwright.dev/docs/test-timeouts). * [various timeouts](https://playwright.dev/docs/test-timeouts).
@ -2194,6 +2029,171 @@ export interface TestInfo {
*/ */
snapshotPath(...pathSegments: Array<string>): string; snapshotPath(...pathSegments: Array<string>): string;
/**
* The list of annotations applicable to the current test. Includes annotations from the test, annotations from all
* [test.describe(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-1) 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;
/**
* 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(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()](https://playwright.dev/docs/api/class-test#test-skip-2);
* - `'failed'` for tests marked as failed with
* [test.fail()](https://playwright.dev/docs/api/class-test#test-fail-1).
*
* 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;
/**
* 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) * **NOTE** Use of [testInfo.snapshotSuffix](https://playwright.dev/docs/api/class-testinfo#test-info-snapshot-suffix)
* is discouraged. Please use * is discouraged. Please use
@ -4291,17 +4291,6 @@ export {};
* *
*/ */
interface APIResponseAssertions { interface APIResponseAssertions {
/**
* Makes the assertion check for the opposite condition. For example, this code tests that the response status is not
* successful:
*
* ```js
* await expect(response).not.toBeOK();
* ```
*
*/
not: APIResponseAssertions;
/** /**
* Ensures the response status code is within `200..299` range. * Ensures the response status code is within `200..299` range.
* *
@ -4313,6 +4302,17 @@ interface APIResponseAssertions {
* *
*/ */
toBeOK(): Promise<void>; toBeOK(): Promise<void>;
/**
* Makes the assertion check for the opposite condition. For example, this code tests that the response status is not
* successful:
*
* ```js
* await expect(response).not.toBeOK();
* ```
*
*/
not: APIResponseAssertions;
} }
/** /**
@ -4332,17 +4332,6 @@ interface APIResponseAssertions {
* *
*/ */
interface LocatorAssertions { interface LocatorAssertions {
/**
* 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');
* ```
*
*/
not: LocatorAssertions;
/** /**
* Ensures the [Locator] points to a checked input. * Ensures the [Locator] points to a checked input.
* *
@ -4992,6 +4981,17 @@ interface LocatorAssertions {
*/ */
timeout?: number; timeout?: number;
}): Promise<void>; }): Promise<void>;
/**
* 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');
* ```
*
*/
not: LocatorAssertions;
} }
/** /**
@ -5011,17 +5011,6 @@ interface LocatorAssertions {
* *
*/ */
interface PageAssertions { interface PageAssertions {
/**
* 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');
* ```
*
*/
not: PageAssertions;
/** /**
* This function will wait until two consecutive page screenshots yield the same result, and then compare the last * This function will wait until two consecutive page screenshots yield the same result, and then compare the last
* screenshot with the expectation. * screenshot with the expectation.
@ -5284,6 +5273,17 @@ interface PageAssertions {
*/ */
timeout?: number; timeout?: number;
}): Promise<void>; }): Promise<void>;
/**
* 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');
* ```
*
*/
not: PageAssertions;
} }
/** /**
@ -5653,6 +5653,54 @@ interface TestProject {
*/ */
name?: string; name?: string;
/**
* The output directory for files created during test execution. Defaults to `<package.json-directory>/test-results`.
*
* This directory is cleaned at the start. When running a test, a unique subdirectory inside the
* [testProject.outputDir](https://playwright.dev/docs/api/class-testproject#test-project-output-dir) is created,
* guaranteeing that test running in parallel do not conflict. This directory can be accessed by
* [testInfo.outputDir](https://playwright.dev/docs/api/class-testinfo#test-info-output-dir) and
* [testInfo.outputPath(...pathSegments)](https://playwright.dev/docs/api/class-testinfo#test-info-output-path).
*
* Here is an example that uses
* [testInfo.outputPath(...pathSegments)](https://playwright.dev/docs/api/class-testinfo#test-info-output-path) to
* create a temporary file.
*
* ```js
* import { test, expect } from '@playwright/test';
* import fs from 'fs';
*
* test('example test', async ({}, testInfo) => {
* const file = testInfo.outputPath('temporary-file.txt');
* await fs.promises.writeFile(file, 'Put some data to the file', 'utf8');
* });
* ```
*
* Use [testConfig.outputDir](https://playwright.dev/docs/api/class-testconfig#test-config-output-dir) to change this
* option for all projects.
*/
outputDir?: string;
/**
* The number of times to repeat each test, useful for debugging flaky tests.
*
* Use [testConfig.repeatEach](https://playwright.dev/docs/api/class-testconfig#test-config-repeat-each) to change
* this option for all projects.
*/
repeatEach?: number;
/**
* The maximum number of retry attempts given to failed tests. Learn more about
* [test retries](https://playwright.dev/docs/test-retries#retries).
*
* Use [test.describe.configure([options])](https://playwright.dev/docs/api/class-test#test-describe-configure) to
* change the number of retries for a specific file or a group of tests.
*
* Use [testConfig.retries](https://playwright.dev/docs/api/class-testconfig#test-config-retries) to change this
* option for all projects.
*/
retries?: number;
/** /**
* The base directory, relative to the config file, for snapshot files created with `toMatchSnapshot`. Defaults to * The base directory, relative to the config file, for snapshot files created with `toMatchSnapshot`. Defaults to
* [testProject.testDir](https://playwright.dev/docs/api/class-testproject#test-project-test-dir). * [testProject.testDir](https://playwright.dev/docs/api/class-testproject#test-project-test-dir).
@ -5765,54 +5813,6 @@ interface TestProject {
*/ */
snapshotPathTemplate?: string; snapshotPathTemplate?: string;
/**
* The output directory for files created during test execution. Defaults to `<package.json-directory>/test-results`.
*
* This directory is cleaned at the start. When running a test, a unique subdirectory inside the
* [testProject.outputDir](https://playwright.dev/docs/api/class-testproject#test-project-output-dir) is created,
* guaranteeing that test running in parallel do not conflict. This directory can be accessed by
* [testInfo.outputDir](https://playwright.dev/docs/api/class-testinfo#test-info-output-dir) and
* [testInfo.outputPath(...pathSegments)](https://playwright.dev/docs/api/class-testinfo#test-info-output-path).
*
* Here is an example that uses
* [testInfo.outputPath(...pathSegments)](https://playwright.dev/docs/api/class-testinfo#test-info-output-path) to
* create a temporary file.
*
* ```js
* import { test, expect } from '@playwright/test';
* import fs from 'fs';
*
* test('example test', async ({}, testInfo) => {
* const file = testInfo.outputPath('temporary-file.txt');
* await fs.promises.writeFile(file, 'Put some data to the file', 'utf8');
* });
* ```
*
* Use [testConfig.outputDir](https://playwright.dev/docs/api/class-testconfig#test-config-output-dir) to change this
* option for all projects.
*/
outputDir?: string;
/**
* The number of times to repeat each test, useful for debugging flaky tests.
*
* Use [testConfig.repeatEach](https://playwright.dev/docs/api/class-testconfig#test-config-repeat-each) to change
* this option for all projects.
*/
repeatEach?: number;
/**
* The maximum number of retry attempts given to failed tests. Learn more about
* [test retries](https://playwright.dev/docs/test-retries#retries).
*
* Use [test.describe.configure([options])](https://playwright.dev/docs/api/class-test#test-describe-configure) to
* change the number of retries for a specific file or a group of tests.
*
* Use [testConfig.retries](https://playwright.dev/docs/api/class-testconfig#test-config-retries) to change this
* option for all projects.
*/
retries?: number;
/** /**
* Directory that will be recursively scanned for test files. Defaults to the directory of the configuration file. * Directory that will be recursively scanned for test files. Defaults to the directory of the configuration file.
* *

104
packages/playwright-test/types/testReporter.d.ts vendored
View File

@ -49,6 +49,11 @@ export interface Suite {
*/ */
allTests(): Array<TestCase>; allTests(): Array<TestCase>;
/**
* Returns a list of titles from the root down to this suite.
*/
titlePath(): Array<string>;
/** /**
* Location in the source where the suite is defined. Missing for root and project suites. * Location in the source where the suite is defined. Missing for root and project suites.
*/ */
@ -79,12 +84,7 @@ export interface Suite {
* - Title passed to [test.describe(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-1) * - Title passed to [test.describe(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-1)
* for a group suite. * for a group suite.
*/ */
title: string; title: string;}
/**
* Returns a list of titles from the root down to this suite.
*/
titlePath(): Array<string>;}
/** /**
* `TestCase` corresponds to every * `TestCase` corresponds to every
@ -107,6 +107,24 @@ export interface TestCase {
* status. * status.
*/ */
expectedStatus: TestStatus; expectedStatus: TestStatus;
/**
* Whether the test is considered running fine. Non-ok tests fail the test run with non-zero exit code.
*/
ok(): boolean;
/**
* Testing outcome for this test. Note that outcome is not the same as
* [testResult.status](https://playwright.dev/docs/api/class-testresult#test-result-status):
* - Test that is expected to fail and actually fails is `'expected'`.
* - Test that passes on a second retry is `'flaky'`.
*/
outcome(): "skipped"|"expected"|"unexpected"|"flaky";
/**
* Returns a list of titles from the root down to this test.
*/
titlePath(): Array<string>;
/** /**
* The list of annotations applicable to the current test. Includes annotations from the test, annotations from all * The list of annotations applicable to the current test. Includes annotations from the test, annotations from all
* [test.describe(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-1) groups the test * [test.describe(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-1) groups the test
@ -140,19 +158,6 @@ export interface TestCase {
*/ */
location: Location; location: Location;
/**
* Whether the test is considered running fine. Non-ok tests fail the test run with non-zero exit code.
*/
ok(): boolean;
/**
* Testing outcome for this test. Note that outcome is not the same as
* [testResult.status](https://playwright.dev/docs/api/class-testresult#test-result-status):
* - Test that is expected to fail and actually fails is `'expected'`.
* - Test that passes on a second retry is `'flaky'`.
*/
outcome(): "skipped"|"expected"|"unexpected"|"flaky";
/** /**
* Suite this test case belongs to. * Suite this test case belongs to.
*/ */
@ -190,12 +195,7 @@ export interface TestCase {
* Test title as passed to the * Test title as passed to the
* [test.(call)(title, testFunction)](https://playwright.dev/docs/api/class-test#test-call) call. * [test.(call)(title, testFunction)](https://playwright.dev/docs/api/class-test#test-call) call.
*/ */
title: string; title: string;}
/**
* Returns a list of titles from the root down to this test.
*/
titlePath(): Array<string>;}
/** /**
* A result of a single [TestCase] run. * A result of a single [TestCase] run.
@ -249,6 +249,12 @@ export interface TestResult {
*/ */
errors: Array<TestError>; errors: Array<TestError>;
/**
* The index of the worker between `0` and `workers - 1`. It is guaranteed that workers running at the same time have
* a different `parallelIndex`.
*/
parallelIndex: number;
/** /**
* When test is retries multiple times, each retry attempt is given a sequential number. * When test is retries multiple times, each retry attempt is given a sequential number.
* *
@ -282,13 +288,7 @@ export interface TestResult {
* *
* Learn more about [parallelism and sharding](https://playwright.dev/docs/test-parallel) with Playwright Test. * Learn more about [parallelism and sharding](https://playwright.dev/docs/test-parallel) with Playwright Test.
*/ */
workerIndex: number; workerIndex: number;}
/**
* The index of the worker between `0` and `workers - 1`. It is guaranteed that workers running at the same time have
* a different `parallelIndex`.
*/
parallelIndex: number;}
/** /**
* Result of the full test run. * Result of the full test run.
@ -546,6 +546,11 @@ export {};
* Represents a location in the source code where [TestCase] or [Suite] is defined. * Represents a location in the source code where [TestCase] or [Suite] is defined.
*/ */
export interface Location { export interface Location {
/**
* Column number in the source file.
*/
column: number;
/** /**
* Path to the source file. * Path to the source file.
*/ */
@ -555,17 +560,17 @@ export interface Location {
* Line number in the source file. * Line number in the source file.
*/ */
line: number; line: number;
/**
* Column number in the source file.
*/
column: number;
} }
/** /**
* Information about an error thrown during test execution. * Information about an error thrown during test execution.
*/ */
export interface TestError { export interface TestError {
/**
* Error location in the source code.
*/
location?: Location;
/** /**
* Error message. Set when [Error] (or its subclass) has been thrown. * Error message. Set when [Error] (or its subclass) has been thrown.
*/ */
@ -580,17 +585,17 @@ export interface TestError {
* The value that was thrown. Set when anything except the [Error] (or its subclass) has been thrown. * The value that was thrown. Set when anything except the [Error] (or its subclass) has been thrown.
*/ */
value?: string; value?: string;
/**
* Error location in the source code.
*/
location?: Location;
} }
/** /**
* Represents a step in the [TestRun]. * Represents a step in the [TestRun].
*/ */
export interface TestStep { export interface TestStep {
/**
* Returns a list of step titles from the root step down to this step.
*/
titlePath(): Array<string>;
/** /**
* Step category to differentiate steps with different origin and verbosity. Built-in categories are: * Step category to differentiate steps with different origin and verbosity. Built-in categories are:
* - `hook` for fixtures and hooks initialization and teardown * - `hook` for fixtures and hooks initialization and teardown
@ -605,16 +610,16 @@ export interface TestStep {
*/ */
duration: number; duration: number;
/**
* Optional location in the source where the step is defined.
*/
location?: Location;
/** /**
* Error thrown during the step execution, if any. * Error thrown during the step execution, if any.
*/ */
error?: TestError; error?: TestError;
/**
* Optional location in the source where the step is defined.
*/
location?: Location;
/** /**
* Parent step, if any. * Parent step, if any.
*/ */
@ -634,11 +639,6 @@ export interface TestStep {
* User-friendly test step title. * User-friendly test step title.
*/ */
title: string; title: string;
/**
* Returns a list of step titles from the root step down to this step.
*/
titlePath(): Array<string>;
} }

51
utils/doclint/documentation.js
View File

@ -97,7 +97,7 @@ class Documentation {
*/ */
copyDocsFromSuperclasses(errors) { copyDocsFromSuperclasses(errors) {
for (const [name, clazz] of this.classes.entries()) { for (const [name, clazz] of this.classes.entries()) {
clazz.validateOrder(errors, clazz); clazz.sortMembers();
if (!clazz.extends || ['EventEmitter', 'Error', 'Exception', 'RuntimeException'].includes(clazz.extends)) if (!clazz.extends || ['EventEmitter', 'Error', 'Exception', 'RuntimeException'].includes(clazz.extends))
continue; continue;
@ -317,48 +317,17 @@ class Documentation {
this.membersArray = membersArray; this.membersArray = membersArray;
} }
validateOrder(errors, cls) { sortMembers() {
const members = this.membersArray; /**
// Events should go first. * @param {Member} member
let eventIndex = 0; */
for (; eventIndex < members.length && members[eventIndex].kind === 'event'; ++eventIndex); function sortKey(member) {
for (; eventIndex < members.length && members[eventIndex].kind !== 'event'; ++eventIndex); return { 'event': 'a', 'method': 'b', 'property': 'c' }[member.kind] + member.alias;
if (eventIndex < members.length)
errors.push(`Events should go first. Event '${members[eventIndex].name}' in class ${cls.name} breaks order`);
// Constructor should be right after events and before all other members.
const constructorIndex = members.findIndex(member => member.kind === 'method' && member.name === 'constructor');
if (constructorIndex > 0 && members[constructorIndex - 1].kind !== 'event')
errors.push(`Constructor of ${cls.name} should go before other methods`);
// Events should be sorted alphabetically.
for (let i = 0; i < members.length - 1; ++i) {
const member1 = this.membersArray[i];
const member2 = this.membersArray[i + 1];
if (member1.kind !== 'event' || member2.kind !== 'event')
continue;
if (member1.name.localeCompare(member2.name, 'en', { sensitivity: 'base' }) > 0)
errors.push(`Event '${member1.name}' in class ${this.name} breaks alphabetic ordering of events`);
} }
// All other members should be sorted alphabetically. this.membersArray.sort((m1, m2) => {
for (let i = 0; i < members.length - 1; ++i) { return sortKey(m1).localeCompare(sortKey(m2), 'en', { sensitivity: 'base' });
const member1 = this.membersArray[i]; });
const member2 = this.membersArray[i + 1];
if (member1.kind === 'event' || member2.kind === 'event')
continue;
if (member1.kind === 'method' && member1.name === 'constructor')
continue;
if (member1.name.replace(/^\$+/, '$').localeCompare(member2.name.replace(/^\$+/, '$'), 'en', { sensitivity: 'base' }) > 0) {
let memberName1 = `${this.name}.${member1.name}`;
if (member1.kind === 'method')
memberName1 += '()';
let memberName2 = `${this.name}.${member2.name}`;
if (member2.kind === 'method')
memberName2 += '()';
errors.push(`Bad alphabetic ordering of ${this.name} members: ${memberName1} should go after ${memberName2}`);
}
}
} }
/** /**