microsoft
/
playwright
зеркало из https://github.com/microsoft/playwright.git
1
0
Форкнуть 0
Код Задачи Пакеты Проекты Релизы Вики Активность

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

This commit is contained in:
Dmitry Gozman 2023-08-10 14:48:26 -07:00 коммит произвёл GitHub
Родитель 67962c58b4
Коммит c37dfb379b
Не найден ключ, соответствующий данной подписи
Идентификатор ключа GPG: 4AEE18F83AFDEB23
2 изменённых файлов: 93 добавлений и 66 удалений
Показать статистику Скачать Patch файл Скачать Diff файл Показать все файлы Свернуть все файлы

152
packages/playwright-test/types/test.d.ts поставляемый
Просмотреть файл

@ -3480,6 +3480,11 @@ export interface PlaywrightWorkerOptions {
browserName: 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**
*
* ```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;
/**
* 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**
*
* ```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;
/**
@ -3700,6 +3702,8 @@ export type VideoMode = 'off' | 'on' | 'retain-on-failure' | 'on-first-retry';
*/
export interface PlaywrightTestOptions {
/**
* Whether to automatically download all the attachments. Defaults to `true` where all the downloads are accepted.
*
* **Usage**
*
* ```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;
/**
* Toggles bypassing page's Content-Security-Policy. Defaults to `false`.
*
* **Usage**
*
* ```js
@ -3730,10 +3735,13 @@ export interface PlaywrightTestOptions {
* });
* ```
*
* Toggles bypassing page's Content-Security-Policy. Defaults to `false`.
*/
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**
*
* ```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;
/**
* 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**
*
* ```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;
/**
* An object containing additional HTTP headers to be sent with every request. Defaults to none.
*
* **Usage**
*
* ```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;
/**
@ -3808,6 +3815,9 @@ export interface PlaywrightTestOptions {
*/
geolocation: Geolocation | undefined;
/**
* Specifies if viewport supports touch events. Defaults to false. Learn more about
* [mobile emulation](https://playwright.dev/docs/emulation#devices).
*
* **Usage**
*
* ```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;
/**
* 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**
*
* ```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;
/**
* Whether to ignore HTTPS errors when sending network requests. Defaults to `false`.
*
* **Usage**
*
* ```js
@ -3860,10 +3871,13 @@ export interface PlaywrightTestOptions {
* });
* ```
*
* Whether to ignore HTTPS errors when sending network requests. Defaults to `false`.
*/
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**
*
* ```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;
/**
* 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**
*
* ```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;
/**
* 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**
*
* ```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;
/**
* Whether to emulate network being offline. Defaults to `false`. Learn more about
* [network emulation](https://playwright.dev/docs/emulation#offline).
*
* **Usage**
*
* ```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;
/**
* 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**
*
* ```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;
/**
* Network proxy settings.
*
* **Usage**
*
* ```js
@ -3973,10 +3990,15 @@ export interface PlaywrightTestOptions {
* });
* ```
*
* Network proxy settings.
*/
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**
*
* ```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;
/**
* 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**
*
* ```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;
/**
* Specific user agent to use in this context.
*
* **Usage**
*
* ```js
@ -4030,10 +4050,15 @@ export interface PlaywrightTestOptions {
* });
* ```
*
* Specific user agent to use in this context.
*/
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**
*
* ```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;
/**
* **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),
* [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),
@ -4082,6 +4089,20 @@ export interface PlaywrightTestOptions {
* `http://localhost:3000/foo/bar.html`
* - baseURL: `http://localhost:3000/foo` (without trailing slash) and navigating to `./bar.html` results in
* `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;
/**
@ -4152,6 +4173,11 @@ export interface PlaywrightTestOptions {
*/
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**
*
* ```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;
/**

7
utils/doclint/api_parser.js
Просмотреть файл

@ -293,7 +293,12 @@ function applyTemplates(body, params) {
const template = paramsMap.get(key);
if (!template)
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-')) {
node.text.replace(/%%-template-[^%]+-%%/, templateName => {
const template = paramsMap.get(templateName);