From c37dfb379b86a02d310668ef1936b8afc7b80fc0 Mon Sep 17 00:00:00 2001 From: Dmitry Gozman Date: Thu, 10 Aug 2023 14:48:26 -0700 Subject: [PATCH] docs: make sure usage comes after description when templating (#26420) --- packages/playwright-test/types/test.d.ts | 152 +++++++++++++---------- utils/doclint/api_parser.js | 7 +- 2 files changed, 93 insertions(+), 66 deletions(-) diff --git a/packages/playwright-test/types/test.d.ts b/packages/playwright-test/types/test.d.ts index 8f72539faa..843f337fd5 100644 --- a/packages/playwright-test/types/test.d.ts +++ b/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; /** diff --git a/utils/doclint/api_parser.js b/utils/doclint/api_parser.js index c21be41002..223d562542 100644 --- a/utils/doclint/api_parser.js +++ b/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);