From 8e5854033a4356355b5e545e0949681907838707 Mon Sep 17 00:00:00 2001 From: Dmitry Gozman Date: Mon, 25 Apr 2022 13:56:37 +0100 Subject: [PATCH] fix: types generation for attach and GlobalInfo (#13727) --- docs/src/test-api/class-globalinfo.md | 16 +- docs/src/test-api/class-testinfo.md | 16 +- packages/playwright-test/types/test.d.ts | 207 ++++++++++++++--------- tests/config/experimental.d.ts | 207 ++++++++++++++--------- utils/generate_types/overrides-test.d.ts | 5 - 5 files changed, 280 insertions(+), 171 deletions(-) diff --git a/docs/src/test-api/class-globalinfo.md b/docs/src/test-api/class-globalinfo.md index cff96d200e..e220e74703 100644 --- a/docs/src/test-api/class-globalinfo.md +++ b/docs/src/test-api/class-globalinfo.md @@ -111,13 +111,21 @@ after awaiting the attach call. ::: ### param: GlobalInfo.attach.name -- `name` <[string]> Attachment name. +- `name` <[string]> + +Attachment name. ### option: GlobalInfo.attach.body -- `body` ?<[string]|[Buffer]> Attachment body. Mutually exclusive with [`option: path`]. +- `body` ?<[string]|[Buffer]> + +Attachment body. Mutually exclusive with [`option: path`]. ### option: GlobalInfo.attach.contentType -- `contentType` ?<[string]> Optional content type of this attachment to properly present in the report, for example `'application/json'` or `'image/png'`. If omitted, content type is inferred based on the [`option: path`], or defaults to `text/plain` for [string] attachments and `application/octet-stream` for [Buffer] attachments. +- `contentType` ?<[string]> + +Optional content type of this attachment to properly present in the report, for example `'application/json'` or `'image/png'`. If omitted, content type is inferred based on the [`option: path`], or defaults to `text/plain` for [string] attachments and `application/octet-stream` for [Buffer] attachments. ### option: GlobalInfo.attach.path -- `path` ?<[string]> Path on the filesystem to the attached file. Mutually exclusive with [`option: body`]. +- `path` ?<[string]> + +Path on the filesystem to the attached file. Mutually exclusive with [`option: body`]. diff --git a/docs/src/test-api/class-testinfo.md b/docs/src/test-api/class-testinfo.md index 6c8ef6602d..107edfdbf7 100644 --- a/docs/src/test-api/class-testinfo.md +++ b/docs/src/test-api/class-testinfo.md @@ -97,16 +97,24 @@ after awaiting the attach call. ::: ### param: TestInfo.attach.name -- `name` <[string]> Attachment name. +- `name` <[string]> + +Attachment name. ### option: TestInfo.attach.body -- `body` <[string]|[Buffer]> Attachment body. Mutually exclusive with [`option: path`]. +- `body` <[string]|[Buffer]> + +Attachment body. Mutually exclusive with [`option: path`]. ### option: TestInfo.attach.contentType -- `contentType` <[string]> Content type of this attachment to properly present in the report, for example `'application/json'` or `'image/png'`. If omitted, content type is inferred based on the [`option: path`], or defaults to `text/plain` for [string] attachments and `application/octet-stream` for [Buffer] attachments. +- `contentType` <[string]> + +Content type of this attachment to properly present in the report, for example `'application/json'` or `'image/png'`. If omitted, content type is inferred based on the [`option: path`], or defaults to `text/plain` for [string] attachments and `application/octet-stream` for [Buffer] attachments. ### option: TestInfo.attach.path -- `path` <[string]> Path on the filesystem to the attached file. Mutually exclusive with [`option: body`]. +- `path` <[string]> + +Path on the filesystem to the attached file. Mutually exclusive with [`option: body`]. ## property: TestInfo.column diff --git a/packages/playwright-test/types/test.d.ts b/packages/playwright-test/types/test.d.ts index 27d7a2baf8..8c2f482f7f 100644 --- a/packages/playwright-test/types/test.d.ts +++ b/packages/playwright-test/types/test.d.ts @@ -1465,14 +1465,25 @@ export interface TestInfo { * > NOTE: [testInfo.attach(name[, options])](https://playwright.dev/docs/api/class-testinfo#test-info-attach) * automatically takes care of copying attached files to a location that is accessible to reporters. You can safely remove * the attachment after awaiting the attach call. - * @param name + * @param name Attachment name. * @param options */ attach(name: string, options?: { + /** + * Attachment body. Mutually exclusive with `path`. + */ body?: string|Buffer; + /** + * Content type of this attachment to properly present in the report, for example `'application/json'` or `'image/png'`. If + * omitted, content type is inferred based on the `path`, or defaults to `text/plain` for [string] attachments and + * `application/octet-stream` for [Buffer] attachments. + */ contentType?: string; + /** + * Path on the filesystem to the attached file. Mutually exclusive with `body`. + */ path?: string; }): Promise; @@ -1734,84 +1745,6 @@ export interface TestInfo { */ workerIndex: number;} -/** - * `GlobalInfo` contains information on the overall test run. The information spans projects and tests. Some reporters show - * global info. - * - * You can write to GlobalInfo via your Global Setup hook, and read from it in a [Custom Reporter](https://playwright.dev/docs/test-reporters): - * - * ```ts - * // global-setup.ts - * import { chromium, FullConfig, GlobalInfo } from '@playwright/test'; - * - * async function globalSetup(config: FullConfig, info: GlobalInfo) { - * await info.attach('agent.config.txt', { path: './agent.config.txt' }); - * } - * - * export default globalSetup; - * ``` - * - * Access the attachments from the Root Suite in the Reporter: - * - * ```ts - * // my-awesome-reporter.ts - * import { Reporter } from '@playwright/test/reporter'; - * - * class MyReporter implements Reporter { - * private _suite; - * - * onBegin(config, suite) { - * this._suite = suite; - * } - * - * onEnd(result) { - * console.log(`Finished the run with ${this._suite.attachments.length} global attachments!`); - * } - * } - * export default MyReporter; - * ``` - * - * Finally, specify `globalSetup` in the configuration file and `reporter`: - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig } from '@playwright/test'; - * - * const config: PlaywrightTestConfig = { - * globalSetup: require.resolve('./global-setup'), - * reporter: require.resolve('./my-awesome-reporter'), - * }; - * export default config; - * ``` - * - * See [`TestInfo`](https://playwright.dev/docs/api/class-testinfo) for related attachment functionality scoped to the test-level. - */ -export interface GlobalInfo { - /** - * The list of files or buffers attached to the overall test run. Some reporters show global attachments. - * - * To add an attachment, use - * [globalInfo.attach(name[, options])](https://playwright.dev/docs/api/class-globalinfo#global-info-attach). See - * [testInfo.attachments](https://playwright.dev/docs/api/class-testinfo#test-info-attachments) if you are looking for - * test-scoped attachments. - */ - attachments(): { name: string, path?: string, body?: Buffer, contentType: string }[]; - /** - * Attach a value or a file from disk to the overall test run. Some reporters show global attachments. Either `path` or - * `body` must be specified, but not both. - * - * See [testInfo.attach(name[, options])](https://playwright.dev/docs/api/class-testinfo#test-info-attach) if you are - * looking for test-scoped attachments. - * - * > NOTE: [globalInfo.attach(name[, options])](https://playwright.dev/docs/api/class-globalinfo#global-info-attach) - * automatically takes care of copying attached files to a location that is accessible to reporters. You can safely remove - * the attachment after awaiting the attach call. - * @param name - * @param options - */ - attach(name: string, options?: { contentType?: string, path?: string, body?: string | Buffer }): Promise; -} - interface SuiteFunction { (title: string, callback: () => void): void; } @@ -3654,6 +3587,122 @@ interface ScreenshotAssertions { }): void; } +/** + * `GlobalInfo` contains information on the overall test run. The information spans projects and tests. Some reporters show + * global info. + * + * You can write to GlobalInfo via your Global Setup hook, and read from it in a [Custom Reporter](https://playwright.dev/docs/test-reporters): + * + * ```ts + * // global-setup.ts + * import { chromium, FullConfig, GlobalInfo } from '@playwright/test'; + * + * async function globalSetup(config: FullConfig, info: GlobalInfo) { + * await info.attach('agent.config.txt', { path: './agent.config.txt' }); + * } + * + * export default globalSetup; + * ``` + * + * Access the attachments from the Root Suite in the Reporter: + * + * ```ts + * // my-awesome-reporter.ts + * import { Reporter } from '@playwright/test/reporter'; + * + * class MyReporter implements Reporter { + * private _suite; + * + * onBegin(config, suite) { + * this._suite = suite; + * } + * + * onEnd(result) { + * console.log(`Finished the run with ${this._suite.attachments.length} global attachments!`); + * } + * } + * export default MyReporter; + * ``` + * + * Finally, specify `globalSetup` in the configuration file and `reporter`: + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * globalSetup: require.resolve('./global-setup'), + * reporter: require.resolve('./my-awesome-reporter'), + * }; + * export default config; + * ``` + * + * See [`TestInfo`](https://playwright.dev/docs/api/class-testinfo) for related attachment functionality scoped to the test-level. + */ +export interface GlobalInfo { + /** + * The list of files or buffers attached to the overall test run. Some reporters show global attachments. + * + * To add an attachment, use + * [globalInfo.attach(name[, options])](https://playwright.dev/docs/api/class-globalinfo#global-info-attach). See + * [testInfo.attachments](https://playwright.dev/docs/api/class-testinfo#test-info-attachments) if you are looking for + * test-scoped attachments. + */ + 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 overall test run. Some reporters show global attachments. Either `path` or + * `body` must be specified, but not both. + * + * See [testInfo.attach(name[, options])](https://playwright.dev/docs/api/class-testinfo#test-info-attach) if you are + * looking for test-scoped attachments. + * + * > NOTE: [globalInfo.attach(name[, options])](https://playwright.dev/docs/api/class-globalinfo#global-info-attach) + * automatically takes care of copying attached files to a location that is accessible to reporters. You can safely remove + * the attachment after awaiting the attach call. + * @param name Attachment name. + * @param options + */ + attach(name: string, options?: { + /** + * Attachment body. Mutually exclusive with `path`. + */ + body?: string|Buffer; + + /** + * Optional content type of this attachment to properly present in the report, for example `'application/json'` or + * `'image/png'`. If omitted, content type is inferred based on the `path`, or defaults to `text/plain` for [string] + * attachments and `application/octet-stream` for [Buffer] attachments. + */ + contentType?: string; + + /** + * Path on the filesystem to the attached file. Mutually exclusive with `body`. + */ + path?: string; + }): Promise; +} + /** * Information about an error thrown during test execution. */ diff --git a/tests/config/experimental.d.ts b/tests/config/experimental.d.ts index c7f33b6741..d9766b419f 100644 --- a/tests/config/experimental.d.ts +++ b/tests/config/experimental.d.ts @@ -17711,14 +17711,25 @@ export interface TestInfo { * > NOTE: [testInfo.attach(name[, options])](https://playwright.dev/docs/api/class-testinfo#test-info-attach) * automatically takes care of copying attached files to a location that is accessible to reporters. You can safely remove * the attachment after awaiting the attach call. - * @param name + * @param name Attachment name. * @param options */ attach(name: string, options?: { + /** + * Attachment body. Mutually exclusive with `path`. + */ body?: string|Buffer; + /** + * Content type of this attachment to properly present in the report, for example `'application/json'` or `'image/png'`. If + * omitted, content type is inferred based on the `path`, or defaults to `text/plain` for [string] attachments and + * `application/octet-stream` for [Buffer] attachments. + */ contentType?: string; + /** + * Path on the filesystem to the attached file. Mutually exclusive with `body`. + */ path?: string; }): Promise; @@ -17980,84 +17991,6 @@ export interface TestInfo { */ workerIndex: number;} -/** - * `GlobalInfo` contains information on the overall test run. The information spans projects and tests. Some reporters show - * global info. - * - * You can write to GlobalInfo via your Global Setup hook, and read from it in a [Custom Reporter](https://playwright.dev/docs/test-reporters): - * - * ```ts - * // global-setup.ts - * import { chromium, FullConfig, GlobalInfo } from '@playwright/test'; - * - * async function globalSetup(config: FullConfig, info: GlobalInfo) { - * await info.attach('agent.config.txt', { path: './agent.config.txt' }); - * } - * - * export default globalSetup; - * ``` - * - * Access the attachments from the Root Suite in the Reporter: - * - * ```ts - * // my-awesome-reporter.ts - * import { Reporter } from '@playwright/test/reporter'; - * - * class MyReporter implements Reporter { - * private _suite; - * - * onBegin(config, suite) { - * this._suite = suite; - * } - * - * onEnd(result) { - * console.log(`Finished the run with ${this._suite.attachments.length} global attachments!`); - * } - * } - * export default MyReporter; - * ``` - * - * Finally, specify `globalSetup` in the configuration file and `reporter`: - * - * ```ts - * // playwright.config.ts - * import { PlaywrightTestConfig } from '@playwright/test'; - * - * const config: PlaywrightTestConfig = { - * globalSetup: require.resolve('./global-setup'), - * reporter: require.resolve('./my-awesome-reporter'), - * }; - * export default config; - * ``` - * - * See [`TestInfo`](https://playwright.dev/docs/api/class-testinfo) for related attachment functionality scoped to the test-level. - */ -export interface GlobalInfo { - /** - * The list of files or buffers attached to the overall test run. Some reporters show global attachments. - * - * To add an attachment, use - * [globalInfo.attach(name[, options])](https://playwright.dev/docs/api/class-globalinfo#global-info-attach). See - * [testInfo.attachments](https://playwright.dev/docs/api/class-testinfo#test-info-attachments) if you are looking for - * test-scoped attachments. - */ - attachments(): { name: string, path?: string, body?: Buffer, contentType: string }[]; - /** - * Attach a value or a file from disk to the overall test run. Some reporters show global attachments. Either `path` or - * `body` must be specified, but not both. - * - * See [testInfo.attach(name[, options])](https://playwright.dev/docs/api/class-testinfo#test-info-attach) if you are - * looking for test-scoped attachments. - * - * > NOTE: [globalInfo.attach(name[, options])](https://playwright.dev/docs/api/class-globalinfo#global-info-attach) - * automatically takes care of copying attached files to a location that is accessible to reporters. You can safely remove - * the attachment after awaiting the attach call. - * @param name - * @param options - */ - attach(name: string, options?: { contentType?: string, path?: string, body?: string | Buffer }): Promise; -} - interface SuiteFunction { (title: string, callback: () => void): void; } @@ -20086,6 +20019,122 @@ interface ScreenshotAssertions { }): void; } +/** + * `GlobalInfo` contains information on the overall test run. The information spans projects and tests. Some reporters show + * global info. + * + * You can write to GlobalInfo via your Global Setup hook, and read from it in a [Custom Reporter](https://playwright.dev/docs/test-reporters): + * + * ```ts + * // global-setup.ts + * import { chromium, FullConfig, GlobalInfo } from '@playwright/test'; + * + * async function globalSetup(config: FullConfig, info: GlobalInfo) { + * await info.attach('agent.config.txt', { path: './agent.config.txt' }); + * } + * + * export default globalSetup; + * ``` + * + * Access the attachments from the Root Suite in the Reporter: + * + * ```ts + * // my-awesome-reporter.ts + * import { Reporter } from '@playwright/test/reporter'; + * + * class MyReporter implements Reporter { + * private _suite; + * + * onBegin(config, suite) { + * this._suite = suite; + * } + * + * onEnd(result) { + * console.log(`Finished the run with ${this._suite.attachments.length} global attachments!`); + * } + * } + * export default MyReporter; + * ``` + * + * Finally, specify `globalSetup` in the configuration file and `reporter`: + * + * ```ts + * // playwright.config.ts + * import { PlaywrightTestConfig } from '@playwright/test'; + * + * const config: PlaywrightTestConfig = { + * globalSetup: require.resolve('./global-setup'), + * reporter: require.resolve('./my-awesome-reporter'), + * }; + * export default config; + * ``` + * + * See [`TestInfo`](https://playwright.dev/docs/api/class-testinfo) for related attachment functionality scoped to the test-level. + */ +export interface GlobalInfo { + /** + * The list of files or buffers attached to the overall test run. Some reporters show global attachments. + * + * To add an attachment, use + * [globalInfo.attach(name[, options])](https://playwright.dev/docs/api/class-globalinfo#global-info-attach). See + * [testInfo.attachments](https://playwright.dev/docs/api/class-testinfo#test-info-attachments) if you are looking for + * test-scoped attachments. + */ + 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 overall test run. Some reporters show global attachments. Either `path` or + * `body` must be specified, but not both. + * + * See [testInfo.attach(name[, options])](https://playwright.dev/docs/api/class-testinfo#test-info-attach) if you are + * looking for test-scoped attachments. + * + * > NOTE: [globalInfo.attach(name[, options])](https://playwright.dev/docs/api/class-globalinfo#global-info-attach) + * automatically takes care of copying attached files to a location that is accessible to reporters. You can safely remove + * the attachment after awaiting the attach call. + * @param name Attachment name. + * @param options + */ + attach(name: string, options?: { + /** + * Attachment body. Mutually exclusive with `path`. + */ + body?: string|Buffer; + + /** + * Optional content type of this attachment to properly present in the report, for example `'application/json'` or + * `'image/png'`. If omitted, content type is inferred based on the `path`, or defaults to `text/plain` for [string] + * attachments and `application/octet-stream` for [Buffer] attachments. + */ + contentType?: string; + + /** + * Path on the filesystem to the attached file. Mutually exclusive with `body`. + */ + path?: string; + }): Promise; +} + /** * Information about an error thrown during test execution. */ diff --git a/utils/generate_types/overrides-test.d.ts b/utils/generate_types/overrides-test.d.ts index e192e8c66f..3baa087748 100644 --- a/utils/generate_types/overrides-test.d.ts +++ b/utils/generate_types/overrides-test.d.ts @@ -150,11 +150,6 @@ export interface TestInfo { status?: TestStatus; } -export interface GlobalInfo { - attachments(): { name: string, path?: string, body?: Buffer, contentType: string }[]; - attach(name: string, options?: { contentType?: string, path?: string, body?: string | Buffer }): Promise; -} - interface SuiteFunction { (title: string, callback: () => void): void; }