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

docs: make sure usage comes after description when templating (#26420)

Browse Source
This commit is contained in:
Dmitry Gozman 2023-08-10 14:48:26 -07:00 committed by GitHub
parent 67962c58b4
commit c37dfb379b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 93 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -3480,6 +3480,11 @@ export interface PlaywrightWorkerOptions {
browserName: BrowserName; browserName: BrowserName;
defaultBrowserType: BrowserName; defaultBrowserType: BrowserName;
/** /**
* Whether to run browser in headless mode. More details for
* [Chromium](https://developers.google.com/web/updates/2017/04/headless-chrome) and
* [Firefox](https://developer.mozilla.org/en-US/docs/Mozilla/Firefox/Headless_mode). Defaults to `true` unless the
* `devtools` option is `true`.
*
* **Usage** * **Usage**
* *
* ```js * ```js
@ -3493,13 +3498,13 @@ export interface PlaywrightWorkerOptions {
* }); * });
* ``` * ```
* *
* Whether to run browser in headless mode. More details for
* [Chromium](https://developers.google.com/web/updates/2017/04/headless-chrome) and
* [Firefox](https://developer.mozilla.org/en-US/docs/Mozilla/Firefox/Headless_mode). Defaults to `true` unless the
* `devtools` option is `true`.
*/ */
headless: boolean; headless: boolean;
/** /**
* Browser distribution channel. Supported values are "chrome", "chrome-beta", "chrome-dev", "chrome-canary",
* "msedge", "msedge-beta", "msedge-dev", "msedge-canary". Read more about using
* [Google Chrome and Microsoft Edge](https://playwright.dev/docs/browsers#google-chrome--microsoft-edge).
*
* **Usage** * **Usage**
* *
* ```js * ```js
@ -3519,9 +3524,6 @@ export interface PlaywrightWorkerOptions {
* }); * });
* ``` * ```
* *
* Browser distribution channel. Supported values are "chrome", "chrome-beta", "chrome-dev", "chrome-canary",
* "msedge", "msedge-beta", "msedge-dev", "msedge-canary". Read more about using
* [Google Chrome and Microsoft Edge](https://playwright.dev/docs/browsers#google-chrome--microsoft-edge).
*/ */
channel: BrowserChannel | undefined; channel: BrowserChannel | undefined;
/** /**
@ -3700,6 +3702,8 @@ export type VideoMode = 'off' | 'on' | 'retain-on-failure' | 'on-first-retry';
*/ */
export interface PlaywrightTestOptions { export interface PlaywrightTestOptions {
/** /**
* Whether to automatically download all the attachments. Defaults to `true` where all the downloads are accepted.
*
* **Usage** * **Usage**
* *
* ```js * ```js
@ -3713,10 +3717,11 @@ export interface PlaywrightTestOptions {
* }); * });
* ``` * ```
* *
* Whether to automatically download all the attachments. Defaults to `true` where all the downloads are accepted.
*/ */
acceptDownloads: boolean; acceptDownloads: boolean;
/** /**
* Toggles bypassing page's Content-Security-Policy. Defaults to `false`.
*
* **Usage** * **Usage**
* *
* ```js * ```js
@ -3730,10 +3735,13 @@ export interface PlaywrightTestOptions {
* }); * });
* ``` * ```
* *
* Toggles bypassing page's Content-Security-Policy. Defaults to `false`.
*/ */
bypassCSP: boolean; bypassCSP: boolean;
/** /**
* Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See
* [page.emulateMedia([options])](https://playwright.dev/docs/api/class-page#page-emulate-media) for more details.
* Passing `null` resets emulation to system defaults. Defaults to `'light'`.
*
* **Usage** * **Usage**
* *
* ```js * ```js
@ -3747,12 +3755,12 @@ export interface PlaywrightTestOptions {
* }); * });
* ``` * ```
* *
* Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See
* [page.emulateMedia([options])](https://playwright.dev/docs/api/class-page#page-emulate-media) for more details.
* Passing `null` resets emulation to system defaults. Defaults to `'light'`.
*/ */
colorScheme: ColorScheme; colorScheme: ColorScheme;
/** /**
* Specify device scale factor (can be thought of as dpr). Defaults to `1`. Learn more about
* [emulating devices with device scale factor](https://playwright.dev/docs/emulation#devices).
*
* **Usage** * **Usage**
* *
* ```js * ```js
@ -3767,11 +3775,11 @@ export interface PlaywrightTestOptions {
* }); * });
* ``` * ```
* *
* Specify device scale factor (can be thought of as dpr). Defaults to `1`. Learn more about
* [emulating devices with device scale factor](https://playwright.dev/docs/emulation#devices).
*/ */
deviceScaleFactor: number | undefined; deviceScaleFactor: number | undefined;
/** /**
* An object containing additional HTTP headers to be sent with every request. Defaults to none.
*
* **Usage** * **Usage**
* *
* ```js * ```js
@ -3787,7 +3795,6 @@ export interface PlaywrightTestOptions {
* }); * });
* ``` * ```
* *
* An object containing additional HTTP headers to be sent with every request. Defaults to none.
*/ */
extraHTTPHeaders: ExtraHTTPHeaders | undefined; extraHTTPHeaders: ExtraHTTPHeaders | undefined;
/** /**
@ -3808,6 +3815,9 @@ export interface PlaywrightTestOptions {
*/ */
geolocation: Geolocation | undefined; geolocation: Geolocation | undefined;
/** /**
* Specifies if viewport supports touch events. Defaults to false. Learn more about
* [mobile emulation](https://playwright.dev/docs/emulation#devices).
*
* **Usage** * **Usage**
* *
* ```js * ```js
@ -3821,11 +3831,12 @@ export interface PlaywrightTestOptions {
* }); * });
* ``` * ```
* *
* Specifies if viewport supports touch events. Defaults to false. Learn more about
* [mobile emulation](https://playwright.dev/docs/emulation#devices).
*/ */
hasTouch: boolean; hasTouch: boolean;
/** /**
* Credentials for [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication). If no
* origin is specified, the username and password are sent to any servers upon unauthorized responses.
*
* **Usage** * **Usage**
* *
* ```js * ```js
@ -3842,11 +3853,11 @@ export interface PlaywrightTestOptions {
* }); * });
* ``` * ```
* *
* Credentials for [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication). If no
* origin is specified, the username and password are sent to any servers upon unauthorized responses.
*/ */
httpCredentials: HTTPCredentials | undefined; httpCredentials: HTTPCredentials | undefined;
/** /**
* Whether to ignore HTTPS errors when sending network requests. Defaults to `false`.
*
* **Usage** * **Usage**
* *
* ```js * ```js
@ -3860,10 +3871,13 @@ export interface PlaywrightTestOptions {
* }); * });
* ``` * ```
* *
* Whether to ignore HTTPS errors when sending network requests. Defaults to `false`.
*/ */
ignoreHTTPSErrors: boolean; ignoreHTTPSErrors: boolean;
/** /**
* Whether the `meta viewport` tag is taken into account and touch events are enabled. isMobile is a part of device,
* so you don't actually need to set it manually. Defaults to `false` and is not supported in Firefox. Learn more
* about [mobile emulation](https://playwright.dev/docs/emulation#ismobile).
*
* **Usage** * **Usage**
* *
* ```js * ```js
@ -3877,12 +3891,12 @@ export interface PlaywrightTestOptions {
* }); * });
* ``` * ```
* *
* Whether the `meta viewport` tag is taken into account and touch events are enabled. isMobile is a part of device,
* so you don't actually need to set it manually. Defaults to `false` and is not supported in Firefox. Learn more
* about [mobile emulation](https://playwright.dev/docs/emulation#ismobile).
*/ */
isMobile: boolean; isMobile: boolean;
/** /**
* Whether or not to enable JavaScript in the context. Defaults to `true`. Learn more about
* [disabling JavaScript](https://playwright.dev/docs/emulation#javascript-enabled).
*
* **Usage** * **Usage**
* *
* ```js * ```js
@ -3896,11 +3910,13 @@ export interface PlaywrightTestOptions {
* }); * });
* ``` * ```
* *
* Whether or not to enable JavaScript in the context. Defaults to `true`. Learn more about
* [disabling JavaScript](https://playwright.dev/docs/emulation#javascript-enabled).
*/ */
javaScriptEnabled: boolean; javaScriptEnabled: boolean;
/** /**
* Specify user locale, for example `en-GB`, `de-DE`, etc. Locale will affect `navigator.language` value,
* `Accept-Language` request header value as well as number and date formatting rules. Defaults to the system default
* locale. Learn more about emulation in our [emulation guide](https://playwright.dev/docs/emulation#locale--timezone).
*
* **Usage** * **Usage**
* *
* ```js * ```js
@ -3914,12 +3930,12 @@ export interface PlaywrightTestOptions {
* }); * });
* ``` * ```
* *
* Specify user locale, for example `en-GB`, `de-DE`, etc. Locale will affect `navigator.language` value,
* `Accept-Language` request header value as well as number and date formatting rules. Defaults to the system default
* locale. Learn more about emulation in our [emulation guide](https://playwright.dev/docs/emulation#locale--timezone).
*/ */
locale: string | undefined; locale: string | undefined;
/** /**
* Whether to emulate network being offline. Defaults to `false`. Learn more about
* [network emulation](https://playwright.dev/docs/emulation#offline).
*
* **Usage** * **Usage**
* *
* ```js * ```js
@ -3933,11 +3949,13 @@ export interface PlaywrightTestOptions {
* }); * });
* ``` * ```
* *
* Whether to emulate network being offline. Defaults to `false`. Learn more about
* [network emulation](https://playwright.dev/docs/emulation#offline).
*/ */
offline: boolean; offline: boolean;
/** /**
* A list of permissions to grant to all pages in this context. See
* [browserContext.grantPermissions(permissions[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-grant-permissions)
* for more details. Defaults to none.
*
* **Usage** * **Usage**
* *
* ```js * ```js
@ -3951,12 +3969,11 @@ export interface PlaywrightTestOptions {
* }); * });
* ``` * ```
* *
* A list of permissions to grant to all pages in this context. See
* [browserContext.grantPermissions(permissions[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-grant-permissions)
* for more details. Defaults to none.
*/ */
permissions: string[] | undefined; permissions: string[] | undefined;
/** /**
* Network proxy settings.
*
* **Usage** * **Usage**
* *
* ```js * ```js
@ -3973,10 +3990,15 @@ export interface PlaywrightTestOptions {
* }); * });
* ``` * ```
* *
* Network proxy settings.
*/ */
proxy: Proxy | undefined; proxy: Proxy | undefined;
/** /**
* Learn more about [storage state and auth](https://playwright.dev/docs/auth).
*
* Populates context with given storage state. This option can be used to initialize context with logged-in
* information obtained via
* [browserContext.storageState([options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-storage-state).
*
* **Usage** * **Usage**
* *
* ```js * ```js
@ -3990,14 +4012,13 @@ export interface PlaywrightTestOptions {
* }); * });
* ``` * ```
* *
* Learn more about [storage state and auth](https://playwright.dev/docs/auth).
*
* Populates context with given storage state. This option can be used to initialize context with logged-in
* information obtained via
* [browserContext.storageState([options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-storage-state).
*/ */
storageState: StorageState | undefined; storageState: StorageState | undefined;
/** /**
* Changes the timezone of the context. See
* [ICU's metaZones.txt](https://cs.chromium.org/chromium/src/third_party/icu/source/data/misc/metaZones.txt?rcl=faee8bc70570192d82d2978a71e2a615788597d1)
* for a list of supported timezone IDs. Defaults to the system timezone.
*
* **Usage** * **Usage**
* *
* ```js * ```js
@ -4011,12 +4032,11 @@ export interface PlaywrightTestOptions {
* }); * });
* ``` * ```
* *
* Changes the timezone of the context. See
* [ICU's metaZones.txt](https://cs.chromium.org/chromium/src/third_party/icu/source/data/misc/metaZones.txt?rcl=faee8bc70570192d82d2978a71e2a615788597d1)
* for a list of supported timezone IDs. Defaults to the system timezone.
*/ */
timezoneId: string | undefined; timezoneId: string | undefined;
/** /**
* Specific user agent to use in this context.
*
* **Usage** * **Usage**
* *
* ```js * ```js
@ -4030,10 +4050,15 @@ export interface PlaywrightTestOptions {
* }); * });
* ``` * ```
* *
* Specific user agent to use in this context.
*/ */
userAgent: string | undefined; userAgent: string | undefined;
/** /**
* Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `null` to disable the consistent
* viewport emulation. Learn more about [viewport emulation](https://playwright.dev/docs/emulation#viewport).
*
* **NOTE** The `null` value opts out from the default presets, makes viewport depend on the host window size defined
* by the operating system. It makes the execution of the tests non-deterministic.
*
* **Usage** * **Usage**
* *
* ```js * ```js
@ -4047,27 +4072,9 @@ export interface PlaywrightTestOptions {
* }); * });
* ``` * ```
* *
* Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `null` to disable the consistent
* viewport emulation. Learn more about [viewport emulation](https://playwright.dev/docs/emulation#viewport).
*
* **NOTE** The `null` value opts out from the default presets, makes viewport depend on the host window size defined
* by the operating system. It makes the execution of the tests non-deterministic.
*/ */
viewport: ViewportSize | null; viewport: ViewportSize | null;
/** /**
* **Usage**
*
* ```js
* import { defineConfig, devices } from '@playwright/test';
*
* export default defineConfig({
* use: {
* /* Base URL to use in actions like `await page.goto('/')`. *\/
* baseURL: 'http://localhost:3000',
* },
* });
* ```
*
* When using [page.goto(url[, options])](https://playwright.dev/docs/api/class-page#page-goto), * When using [page.goto(url[, options])](https://playwright.dev/docs/api/class-page#page-goto),
* [page.route(url, handler[, options])](https://playwright.dev/docs/api/class-page#page-route), * [page.route(url, handler[, options])](https://playwright.dev/docs/api/class-page#page-route),
* [page.waitForURL(url[, options])](https://playwright.dev/docs/api/class-page#page-wait-for-url), * [page.waitForURL(url[, options])](https://playwright.dev/docs/api/class-page#page-wait-for-url),
@ -4082,6 +4089,20 @@ export interface PlaywrightTestOptions {
* `http://localhost:3000/foo/bar.html` * `http://localhost:3000/foo/bar.html`
* - baseURL: `http://localhost:3000/foo` (without trailing slash) and navigating to `./bar.html` results in * - baseURL: `http://localhost:3000/foo` (without trailing slash) and navigating to `./bar.html` results in
* `http://localhost:3000/bar.html` * `http://localhost:3000/bar.html`
*
* **Usage**
*
* ```js
* import { defineConfig, devices } from '@playwright/test';
*
* export default defineConfig({
* use: {
* /* Base URL to use in actions like `await page.goto('/')`. *\/
* baseURL: 'http://localhost:3000',
* },
* });
* ```
*
*/ */
baseURL: string | undefined; baseURL: string | undefined;
/** /**
@ -4152,6 +4173,11 @@ export interface PlaywrightTestOptions {
*/ */
navigationTimeout: number; navigationTimeout: number;
/** /**
* Whether to allow sites to register Service workers. Defaults to `'allow'`.
* - `'allow'`: [Service Workers](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) can be
* registered.
* - `'block'`: Playwright will block all registration of Service Workers.
*
* **Usage** * **Usage**
* *
* ```js * ```js
@ -4165,10 +4191,6 @@ export interface PlaywrightTestOptions {
* }); * });
* ``` * ```
* *
* Whether to allow sites to register Service workers. Defaults to `'allow'`.
* - `'allow'`: [Service Workers](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) can be
* registered.
* - `'block'`: Playwright will block all registration of Service Workers.
*/ */
serviceWorkers: ServiceWorkerPolicy; serviceWorkers: ServiceWorkerPolicy;
/** /**

7
utils/doclint/api_parser.js
View File

@ -293,7 +293,12 @@ function applyTemplates(body, params) {
const template = paramsMap.get(key); const template = paramsMap.get(key);
if (!template) if (!template)
throw new Error('Bad template: ' + key); throw new Error('Bad template: ' + key);
node.children.push(...template.children.map(c => md.clone(c))); // Insert right after all metadata options like "* since",
// keeping any additional text like **Usage** below the template.
let index = node.children.findIndex(child => child.type !== 'li');
if (index === -1)
index = 0;
node.children.splice(index, 0, ...template.children.map(c => md.clone(c)));
} else if (node.text && node.text.includes('%%-template-')) { } else if (node.text && node.text.includes('%%-template-')) {
node.text.replace(/%%-template-[^%]+-%%/, templateName => { node.text.replace(/%%-template-[^%]+-%%/, templateName => {
const template = paramsMap.get(templateName); const template = paramsMap.get(templateName);