From 778dd204035db6318a658de7041b0c81d76975dd Mon Sep 17 00:00:00 2001 From: Dmitry Gozman Date: Thu, 9 Feb 2023 20:46:33 -0800 Subject: [PATCH] chore(docs): beautify generated types, put options always last (#20805) --- packages/playwright-core/types/types.d.ts | 215 ++++++++++-------- packages/playwright-test/types/test.d.ts | 10 +- .../playwright-test/types/testReporter.d.ts | 12 +- utils/doclint/documentation.js | 10 + utils/generate_types/index.js | 7 +- utils/generate_types/overrides-test.d.ts | 2 +- 6 files changed, 143 insertions(+), 113 deletions(-) diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts index 21550c26c0..216d82687f 100644 --- a/packages/playwright-core/types/types.d.ts +++ b/packages/playwright-core/types/types.d.ts @@ -4620,7 +4620,8 @@ export interface Page { */ request: APIRequestContext; - touchscreen: Touchscreen;} + touchscreen: Touchscreen; +} /** * At every point of time, page exposes its current frame tree via the @@ -7235,7 +7236,8 @@ export interface Frame { * loading. */ waitUntil?: "load"|"domcontentloaded"|"networkidle"|"commit"; - }): Promise;} + }): Promise; +} /** * - extends: [EventEmitter] @@ -8323,7 +8325,8 @@ export interface BrowserContext { */ request: APIRequestContext; - tracing: Tracing;} + tracing: Tracing; +} /** * The Worker class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). @@ -8453,7 +8456,8 @@ export interface Worker { */ prependListener(event: 'close', listener: (worker: Worker) => void): this; - url(): string;} + url(): string; +} /** * JSHandle represents an in-page JavaScript object. JSHandles can be created with the @@ -8585,7 +8589,8 @@ export interface JSHandle { * Fetches a single property from the referenced object. * @param propertyName property to get */ - getProperty(propertyName: string): Promise;} + getProperty(propertyName: string): Promise; +} /** * - extends: [JSHandle] @@ -9978,7 +9983,8 @@ export interface ElementHandle extends JSHandle { * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods. */ timeout?: number; - }): Promise;} + }): Promise; +} /** * Locators are the central piece of Playwright's auto-waiting and retry-ability. In a nutshell, locators represent a @@ -11997,7 +12003,8 @@ export interface Locator { * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods. */ timeout?: number; - }): Promise;} + }): Promise; +} /** * BrowserType provides methods to launch a specific browser instance or connect to an existing one. The following is @@ -12696,7 +12703,8 @@ export interface BrowserType { /** * Returns browser name. For example: `'chromium'`, `'webkit'` or `'firefox'`. */ - name(): string;} + name(): string; +} /** * - extends: [EventEmitter] @@ -12741,7 +12749,8 @@ export interface CDPSession { * Detaches the CDPSession from the target. Once detached, the CDPSession object won't emit any events and can't be * used to send messages. */ - detach(): Promise;} + detach(): Promise; +} type DeviceDescriptor = { viewport: ViewportSize; @@ -12781,7 +12790,8 @@ export namespace errors { * ``` * */ -class TimeoutError extends Error {} +class TimeoutError extends Error { +} } @@ -12843,6 +12853,7 @@ export interface Accessibility { * @param options */ snapshot(options?: AccessibilitySnapshotOptions): Promise; + } type AccessibilityNode = { @@ -13110,7 +13121,8 @@ export interface ElectronApplication { /** * Convenience method that returns all the opened windows. */ - windows(): Array;} + windows(): Array; +} export type AndroidElementInfo = { clazz: string; @@ -17323,6 +17335,7 @@ export const selectors: Selectors; * This object can be used to launch or connect to WebKit, returning instances of [Browser]. */ export const webkit: BrowserType; + /** * Whenever the page sends a request for a network resource the following sequence of events are emitted by [Page]: * - [page.on('request')](https://playwright.dev/docs/api/class-page#page-event-request) emitted when the request is @@ -18298,21 +18311,21 @@ export interface WebSocket { * Fired when the websocket receives a frame. */ on(event: 'framereceived', listener: (data: { - /** - * frame payload - */ - payload: string|Buffer; -}) => void): this; + /** + * frame payload + */ + payload: string|Buffer; + }) => void): this; /** * Fired when the websocket sends a frame. */ on(event: 'framesent', listener: (data: { - /** - * frame payload - */ - payload: string|Buffer; -}) => void): this; + /** + * frame payload + */ + payload: string|Buffer; + }) => void): this; /** * Fired when the websocket has an error. @@ -18328,21 +18341,21 @@ export interface WebSocket { * Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event. */ once(event: 'framereceived', listener: (data: { - /** - * frame payload - */ - payload: string|Buffer; -}) => void): this; + /** + * frame payload + */ + payload: string|Buffer; + }) => void): this; /** * Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event. */ once(event: 'framesent', listener: (data: { - /** - * frame payload - */ - payload: string|Buffer; -}) => void): this; + /** + * frame payload + */ + payload: string|Buffer; + }) => void): this; /** * Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event. @@ -18358,21 +18371,21 @@ export interface WebSocket { * Fired when the websocket receives a frame. */ addListener(event: 'framereceived', listener: (data: { - /** - * frame payload - */ - payload: string|Buffer; -}) => void): this; + /** + * frame payload + */ + payload: string|Buffer; + }) => void): this; /** * Fired when the websocket sends a frame. */ addListener(event: 'framesent', listener: (data: { - /** - * frame payload - */ - payload: string|Buffer; -}) => void): this; + /** + * frame payload + */ + payload: string|Buffer; + }) => void): this; /** * Fired when the websocket has an error. @@ -18388,21 +18401,21 @@ export interface WebSocket { * Removes an event listener added by `on` or `addListener`. */ removeListener(event: 'framereceived', listener: (data: { - /** - * frame payload - */ - payload: string|Buffer; -}) => void): this; + /** + * frame payload + */ + payload: string|Buffer; + }) => void): this; /** * Removes an event listener added by `on` or `addListener`. */ removeListener(event: 'framesent', listener: (data: { - /** - * frame payload - */ - payload: string|Buffer; -}) => void): this; + /** + * frame payload + */ + payload: string|Buffer; + }) => void): this; /** * Removes an event listener added by `on` or `addListener`. @@ -18418,21 +18431,21 @@ export interface WebSocket { * Removes an event listener added by `on` or `addListener`. */ off(event: 'framereceived', listener: (data: { - /** - * frame payload - */ - payload: string|Buffer; -}) => void): this; + /** + * frame payload + */ + payload: string|Buffer; + }) => void): this; /** * Removes an event listener added by `on` or `addListener`. */ off(event: 'framesent', listener: (data: { - /** - * frame payload - */ - payload: string|Buffer; -}) => void): this; + /** + * frame payload + */ + payload: string|Buffer; + }) => void): this; /** * Removes an event listener added by `on` or `addListener`. @@ -18448,21 +18461,21 @@ export interface WebSocket { * Fired when the websocket receives a frame. */ prependListener(event: 'framereceived', listener: (data: { - /** - * frame payload - */ - payload: string|Buffer; -}) => void): this; + /** + * frame payload + */ + payload: string|Buffer; + }) => void): this; /** * Fired when the websocket sends a frame. */ prependListener(event: 'framesent', listener: (data: { - /** - * frame payload - */ - payload: string|Buffer; -}) => void): this; + /** + * frame payload + */ + payload: string|Buffer; + }) => void): this; /** * Fired when the websocket has an error. @@ -18488,41 +18501,41 @@ export interface WebSocket { * Fired when the websocket receives a frame. */ waitForEvent(event: 'framereceived', optionsOrPredicate?: { predicate?: (data: { - /** - * frame payload - */ - payload: string|Buffer; -}) => boolean | Promise, timeout?: number } | ((data: { - /** - * frame payload - */ - payload: string|Buffer; -}) => boolean | Promise)): Promise<{ - /** - * frame payload - */ - payload: string|Buffer; -}>; + /** + * frame payload + */ + payload: string|Buffer; + }) => boolean | Promise, timeout?: number } | ((data: { + /** + * frame payload + */ + payload: string|Buffer; + }) => boolean | Promise)): Promise<{ + /** + * frame payload + */ + payload: string|Buffer; + }>; /** * Fired when the websocket sends a frame. */ waitForEvent(event: 'framesent', optionsOrPredicate?: { predicate?: (data: { - /** - * frame payload - */ - payload: string|Buffer; -}) => boolean | Promise, timeout?: number } | ((data: { - /** - * frame payload - */ - payload: string|Buffer; -}) => boolean | Promise)): Promise<{ - /** - * frame payload - */ - payload: string|Buffer; -}>; + /** + * frame payload + */ + payload: string|Buffer; + }) => boolean | Promise, timeout?: number } | ((data: { + /** + * frame payload + */ + payload: string|Buffer; + }) => boolean | Promise)): Promise<{ + /** + * frame payload + */ + payload: string|Buffer; + }>; /** * Fired when the websocket has an error. diff --git a/packages/playwright-test/types/test.d.ts b/packages/playwright-test/types/test.d.ts index c621a8ccaf..56d50fe627 100644 --- a/packages/playwright-test/types/test.d.ts +++ b/packages/playwright-test/types/test.d.ts @@ -1285,7 +1285,8 @@ interface TestConfig { * ``` * */ - workers?: number|string;} + workers?: number|string; +} /** * Playwright Test provides many options to configure how your tests are collected and executed, for example `timeout` @@ -1833,7 +1834,8 @@ export interface WorkerInfo { * Also available as `process.env.TEST_WORKER_INDEX`. Learn more about [parallelism and sharding](https://playwright.dev/docs/test-parallel) * with Playwright Test. */ - workerIndex: number;} + workerIndex: number; +} /** * `TestInfo` contains information about currently running test. It is available to any test function, @@ -2271,7 +2273,8 @@ export interface TestInfo { * Also available as `process.env.TEST_WORKER_INDEX`. Learn more about [parallelism and sharding](https://playwright.dev/docs/test-parallel) * with Playwright Test. */ - workerIndex: number;} + workerIndex: number; +} interface SuiteFunction { /** @@ -4193,6 +4196,7 @@ interface GenericAssertions { * @param expected Expected error message or error object. */ toThrowError(error?: unknown): R; + } type BaseMatchers = GenericAssertions & PlaywrightTest.Matchers; diff --git a/packages/playwright-test/types/testReporter.d.ts b/packages/playwright-test/types/testReporter.d.ts index bb39ee50e0..753c49395d 100644 --- a/packages/playwright-test/types/testReporter.d.ts +++ b/packages/playwright-test/types/testReporter.d.ts @@ -84,7 +84,8 @@ export interface Suite { * - Title passed to [test.describe(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-1) * for a group suite. */ - title: string;} + title: string; +} /** * `TestCase` corresponds to every @@ -195,7 +196,8 @@ export interface TestCase { * Test title as passed to the * [test.(call)(title, testFunction)](https://playwright.dev/docs/api/class-test#test-call) call. */ - title: string;} + title: string; +} /** * A result of a single [TestCase] run. @@ -288,7 +290,8 @@ export interface TestResult { * * Learn more about [parallelism and sharding](https://playwright.dev/docs/test-parallel) with Playwright Test. */ - workerIndex: number;} + workerIndex: number; +} /** * Result of the full test run. @@ -453,7 +456,8 @@ export interface Reporter { * Whether this reporter uses stdio for reporting. When it does not, Playwright Test could add some output to enhance * user experience. If your reporter does not print to the terminal, it is strongly recommended to return `false`. */ - printsToStdio?(): boolean;} + printsToStdio?(): boolean; +} export interface JSONReport { config: Omit & { diff --git a/utils/doclint/documentation.js b/utils/doclint/documentation.js index 6f5cd707c2..dd348cabc8 100644 --- a/utils/doclint/documentation.js +++ b/utils/doclint/documentation.js @@ -328,6 +328,16 @@ class Documentation { this.membersArray.sort((m1, m2) => { return sortKey(m1).localeCompare(sortKey(m2), 'en', { sensitivity: 'base' }); }); + + // Options should be the last argument. + this.membersArray.forEach(member => { + const optionsIndex = member.argsArray.findIndex(a => a.name === 'options'); + if (optionsIndex !== -1) { + const options = member.argsArray[optionsIndex]; + member.argsArray.splice(optionsIndex, 1); + member.argsArray.push(options); + } + }); } /** diff --git a/utils/generate_types/index.js b/utils/generate_types/index.js index f326d0f898..1ecf6982bf 100644 --- a/utils/generate_types/index.js +++ b/utils/generate_types/index.js @@ -216,8 +216,7 @@ class TypesGenerator { const shouldExport = !this.doNotExportClassNames.has(classDesc.name); parts.push(`${shouldExport ? 'export ' : ''}interface ${classDesc.name} ${classDesc.extends ? `extends ${classDesc.extends} ` : ''}{`); parts.push(this.classBody(classDesc)); - parts.push('}\n'); - return parts.join('\n'); + return parts.join('\n') + '}\n'; } /** @@ -252,7 +251,7 @@ class TypesGenerator { const descriptions = []; for (let [eventName, value] of classDesc.events) { eventName = eventName.toLowerCase(); - const type = this.stringifyComplexType(value && value.type, '', classDesc.name, eventName, 'payload'); + const type = this.stringifyComplexType(value && value.type, ' ', classDesc.name, eventName, 'payload'); const argName = this.argNameForType(type); const params = argName ? `${argName}: ${type}` : ''; descriptions.push({ @@ -318,7 +317,7 @@ class TypesGenerator { } return `${jsdoc}${member.alias}${member.required ? '' : '?'}${args}: ${type};` }).filter(x => x).join('\n\n')); - return parts.join('\n'); + return parts.join('\n') + '\n'; } /** diff --git a/utils/generate_types/overrides-test.d.ts b/utils/generate_types/overrides-test.d.ts index 2fb1e121d0..52a517b96c 100644 --- a/utils/generate_types/overrides-test.d.ts +++ b/utils/generate_types/overrides-test.d.ts @@ -52,8 +52,8 @@ export interface FullProject { testMatch: string | RegExp | (string | RegExp)[]; timeout: number; use: UseOptions; - // [internal] !!! DO NOT ADD TO THIS !!! See prior note. } +// [internal] !!! DO NOT ADD TO THIS !!! See prior note. type LiteralUnion = T | (U & { zz_IGNORE_ME?: never });