From d68440dbe245e6e94fa503397a308bcb7ed0c58d Mon Sep 17 00:00:00 2001 From: martinsplitt Date: Tue, 23 Jun 2020 10:22:43 +0200 Subject: [PATCH 1/4] Adds tsdoc for BrowserFetcher --- new-docs/puppeteer.browser.md | 1 - new-docs/puppeteer.browsercontext.md | 1 - .../puppeteer.browserfetcher._constructor_.md | 21 ----- ...puppeteer.browserfetcher._getfolderpath.md | 24 ------ .../puppeteer.browserfetcher.candownload.md | 10 ++- new-docs/puppeteer.browserfetcher.download.md | 12 ++- new-docs/puppeteer.browserfetcher.host.md | 2 + ...puppeteer.browserfetcher.localrevisions.md | 6 ++ new-docs/puppeteer.browserfetcher.md | 27 ++++-- new-docs/puppeteer.browserfetcher.platform.md | 2 + new-docs/puppeteer.browserfetcher.product.md | 2 + new-docs/puppeteer.browserfetcher.remove.md | 8 +- .../puppeteer.browserfetcher.revisioninfo.md | 4 +- new-docs/puppeteer.cdpsession.md | 1 - new-docs/puppeteer.connection.md | 1 - new-docs/puppeteer.elementhandle.md | 1 - new-docs/puppeteer.eventemitter.md | 1 - new-docs/puppeteer.framemanager.md | 1 - new-docs/puppeteer.md | 2 +- new-docs/puppeteer.page.md | 1 - new-docs/puppeteer.timeouterror.md | 1 - new-docs/puppeteer.webworker.md | 1 - src/node/BrowserFetcher.ts | 83 ++++++++++++++++--- 23 files changed, 133 insertions(+), 80 deletions(-) delete mode 100644 new-docs/puppeteer.browserfetcher._constructor_.md delete mode 100644 new-docs/puppeteer.browserfetcher._getfolderpath.md diff --git a/new-docs/puppeteer.browser.md b/new-docs/puppeteer.browser.md index 4c669ee5802c7..d04f7335c0a06 100644 --- a/new-docs/puppeteer.browser.md +++ b/new-docs/puppeteer.browser.md @@ -9,7 +9,6 @@ ```typescript export declare class Browser extends EventEmitter ``` -Extends: [EventEmitter](./puppeteer.eventemitter.md) ## Constructors diff --git a/new-docs/puppeteer.browsercontext.md b/new-docs/puppeteer.browsercontext.md index 393509a20ef7a..68a9b8284476c 100644 --- a/new-docs/puppeteer.browsercontext.md +++ b/new-docs/puppeteer.browsercontext.md @@ -9,7 +9,6 @@ ```typescript export declare class BrowserContext extends EventEmitter ``` -Extends: [EventEmitter](./puppeteer.eventemitter.md) ## Constructors diff --git a/new-docs/puppeteer.browserfetcher._constructor_.md b/new-docs/puppeteer.browserfetcher._constructor_.md deleted file mode 100644 index 13d9d5549c017..0000000000000 --- a/new-docs/puppeteer.browserfetcher._constructor_.md +++ /dev/null @@ -1,21 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [BrowserFetcher](./puppeteer.browserfetcher.md) > [(constructor)](./puppeteer.browserfetcher._constructor_.md) - -## BrowserFetcher.(constructor) - -Constructs a new instance of the `BrowserFetcher` class - -Signature: - -```typescript -constructor(projectRoot: string, options?: BrowserFetcherOptions); -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| projectRoot | string | | -| options | [BrowserFetcherOptions](./puppeteer.browserfetcheroptions.md) | | - diff --git a/new-docs/puppeteer.browserfetcher._getfolderpath.md b/new-docs/puppeteer.browserfetcher._getfolderpath.md deleted file mode 100644 index 7c3e0203687d1..0000000000000 --- a/new-docs/puppeteer.browserfetcher._getfolderpath.md +++ /dev/null @@ -1,24 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [BrowserFetcher](./puppeteer.browserfetcher.md) > [\_getFolderPath](./puppeteer.browserfetcher._getfolderpath.md) - -## BrowserFetcher.\_getFolderPath() method - -Signature: - -```typescript -_getFolderPath(revision: string): string; -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| revision | string | | - -Returns: - -string - -{string} - diff --git a/new-docs/puppeteer.browserfetcher.candownload.md b/new-docs/puppeteer.browserfetcher.candownload.md index 323ba86e7ca14..f0a2d544450c8 100644 --- a/new-docs/puppeteer.browserfetcher.candownload.md +++ b/new-docs/puppeteer.browserfetcher.candownload.md @@ -4,6 +4,8 @@ ## BrowserFetcher.canDownload() method +Initiates a HEAD request to check if the revision is available. + Signature: ```typescript @@ -14,9 +16,15 @@ canDownload(revision: string): Promise; | Parameter | Type | Description | | --- | --- | --- | -| revision | string | | +| revision | string | The revision to check availability for. | Returns: Promise<boolean> +A promise that resolves to `true` if the revision could be downloaded from the host. + +## Remarks + +This method is affected by the current `product`. + diff --git a/new-docs/puppeteer.browserfetcher.download.md b/new-docs/puppeteer.browserfetcher.download.md index a04a3e33680b1..d8da3eb9b72e1 100644 --- a/new-docs/puppeteer.browserfetcher.download.md +++ b/new-docs/puppeteer.browserfetcher.download.md @@ -4,6 +4,8 @@ ## BrowserFetcher.download() method +Initiates a GET request to download the revision from the host. + Signature: ```typescript @@ -14,12 +16,16 @@ download(revision: string, progressCallback: (x: number, y: number) => void): Pr | Parameter | Type | Description | | --- | --- | --- | -| revision | string | | -| progressCallback | (x: number, y: number) => void | | +| revision | string | The revision to download. | +| progressCallback | (x: number, y: number) => void | A function that will be called with two arguments: How many bytes have been downloaded and the total number of bytes of the download. | Returns: Promise<BrowserFetcherRevisionInfo> -{!Promise<!BrowserFetcher.RevisionInfo>} +A promise with revision information when the revision is downloaded and extracted. + +## Remarks + +This method is affected by the current `product`. diff --git a/new-docs/puppeteer.browserfetcher.host.md b/new-docs/puppeteer.browserfetcher.host.md index 1a342db63199a..5667cb5156ce9 100644 --- a/new-docs/puppeteer.browserfetcher.host.md +++ b/new-docs/puppeteer.browserfetcher.host.md @@ -13,3 +13,5 @@ host(): string; string +The download host being used. + diff --git a/new-docs/puppeteer.browserfetcher.localrevisions.md b/new-docs/puppeteer.browserfetcher.localrevisions.md index 78db4f48f9ee3..8f7c65d10312e 100644 --- a/new-docs/puppeteer.browserfetcher.localrevisions.md +++ b/new-docs/puppeteer.browserfetcher.localrevisions.md @@ -13,3 +13,9 @@ localRevisions(): Promise; Promise<string\[\]> +A promise with a list of all revision strings (for the current `product`) available locally on disk. + +## Remarks + +This method is affected by the current `product`. + diff --git a/new-docs/puppeteer.browserfetcher.md b/new-docs/puppeteer.browserfetcher.md index 82777b0044575..7b6172bd9e4c0 100644 --- a/new-docs/puppeteer.browserfetcher.md +++ b/new-docs/puppeteer.browserfetcher.md @@ -4,25 +4,38 @@ ## BrowserFetcher class +BrowserFetcher can download and manage different versions of Chromium and Firefox. + Signature: ```typescript export declare class BrowserFetcher ``` -## Constructors +## Remarks -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(projectRoot, options)](./puppeteer.browserfetcher._constructor_.md) | | Constructs a new instance of the BrowserFetcher class | +BrowserFetcher operates on revision strings that specify a precise version of Chromium, e.g. `"533271"`. Revision strings can be obtained from \[omahaproxy.appspot.com\](http://omahaproxy.appspot.com/). In the Firefox case, BrowserFetcher downloads Firefox Nightly and operates on version numbers such as `"75"`. + +The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `BrowserFetcher` class. + +## Example + +An example of using BrowserFetcher to download a specific version of Chromium and running Puppeteer against it: + +```js +const browserFetcher = puppeteer.createBrowserFetcher(); +const revisionInfo = await browserFetcher.download('533271'); +const browser = await puppeteer.launch({executablePath: revisionInfo.executablePath}) + +``` +\*\*NOTE\*\* BrowserFetcher is not designed to work concurrently with other instances of BrowserFetcher that share the same downloads directory. ## Methods | Method | Modifiers | Description | | --- | --- | --- | -| [\_getFolderPath(revision)](./puppeteer.browserfetcher._getfolderpath.md) | | | -| [canDownload(revision)](./puppeteer.browserfetcher.candownload.md) | | | -| [download(revision, progressCallback)](./puppeteer.browserfetcher.download.md) | | | +| [canDownload(revision)](./puppeteer.browserfetcher.candownload.md) | | Initiates a HEAD request to check if the revision is available. | +| [download(revision, progressCallback)](./puppeteer.browserfetcher.download.md) | | Initiates a GET request to download the revision from the host. | | [host()](./puppeteer.browserfetcher.host.md) | | | | [localRevisions()](./puppeteer.browserfetcher.localrevisions.md) | | | | [platform()](./puppeteer.browserfetcher.platform.md) | | | diff --git a/new-docs/puppeteer.browserfetcher.platform.md b/new-docs/puppeteer.browserfetcher.platform.md index b48185e5ba408..8f55cd2ae1fc5 100644 --- a/new-docs/puppeteer.browserfetcher.platform.md +++ b/new-docs/puppeteer.browserfetcher.platform.md @@ -13,3 +13,5 @@ platform(): string; string +One of `mac`, `linux`, `win32` or `win64`. + diff --git a/new-docs/puppeteer.browserfetcher.product.md b/new-docs/puppeteer.browserfetcher.product.md index a8bf2223e150e..7b2201366edb0 100644 --- a/new-docs/puppeteer.browserfetcher.product.md +++ b/new-docs/puppeteer.browserfetcher.product.md @@ -13,3 +13,5 @@ product(): string; string +One of `chrome` or `firefox`. + diff --git a/new-docs/puppeteer.browserfetcher.remove.md b/new-docs/puppeteer.browserfetcher.remove.md index 1343c6f0c87ab..334abc5f6adc4 100644 --- a/new-docs/puppeteer.browserfetcher.remove.md +++ b/new-docs/puppeteer.browserfetcher.remove.md @@ -14,9 +14,15 @@ remove(revision: string): Promise; | Parameter | Type | Description | | --- | --- | --- | -| revision | string | | +| revision | string | A revision to remove for the current product. | Returns: Promise<void> +A promise that resolves when the revision has been removes or throws if the revision has not been downloaded. + +## Remarks + +This method is affected by the current `product`. + diff --git a/new-docs/puppeteer.browserfetcher.revisioninfo.md b/new-docs/puppeteer.browserfetcher.revisioninfo.md index 2586b24a6ad3f..c72e30ffa3e49 100644 --- a/new-docs/puppeteer.browserfetcher.revisioninfo.md +++ b/new-docs/puppeteer.browserfetcher.revisioninfo.md @@ -14,9 +14,11 @@ revisionInfo(revision: string): BrowserFetcherRevisionInfo; | Parameter | Type | Description | | --- | --- | --- | -| revision | string | | +| revision | string | The revision to get info for. | Returns: BrowserFetcherRevisionInfo +The revision info for the given revision. + diff --git a/new-docs/puppeteer.cdpsession.md b/new-docs/puppeteer.cdpsession.md index 1f3987c67c37b..cca7a99042691 100644 --- a/new-docs/puppeteer.cdpsession.md +++ b/new-docs/puppeteer.cdpsession.md @@ -9,7 +9,6 @@ ```typescript export declare class CDPSession extends EventEmitter ``` -Extends: [EventEmitter](./puppeteer.eventemitter.md) ## Constructors diff --git a/new-docs/puppeteer.connection.md b/new-docs/puppeteer.connection.md index 75fff814e8c64..3fb04345462b1 100644 --- a/new-docs/puppeteer.connection.md +++ b/new-docs/puppeteer.connection.md @@ -9,7 +9,6 @@ ```typescript export declare class Connection extends EventEmitter ``` -Extends: [EventEmitter](./puppeteer.eventemitter.md) ## Constructors diff --git a/new-docs/puppeteer.elementhandle.md b/new-docs/puppeteer.elementhandle.md index a5b14ac0d9197..6280f20a45367 100644 --- a/new-docs/puppeteer.elementhandle.md +++ b/new-docs/puppeteer.elementhandle.md @@ -9,7 +9,6 @@ ```typescript export declare class ElementHandle extends JSHandle ``` -Extends: [JSHandle](./puppeteer.jshandle.md) ## Constructors diff --git a/new-docs/puppeteer.eventemitter.md b/new-docs/puppeteer.eventemitter.md index 99d26ef45a8d5..9937c5b2acac9 100644 --- a/new-docs/puppeteer.eventemitter.md +++ b/new-docs/puppeteer.eventemitter.md @@ -11,7 +11,6 @@ The EventEmitter class that many Puppeteer classes extend. ```typescript export declare class EventEmitter implements CommonEventEmitter ``` -Implements: CommonEventEmitter ## Remarks diff --git a/new-docs/puppeteer.framemanager.md b/new-docs/puppeteer.framemanager.md index f1563870ebec9..d5322f6fe5670 100644 --- a/new-docs/puppeteer.framemanager.md +++ b/new-docs/puppeteer.framemanager.md @@ -9,7 +9,6 @@ ```typescript export declare class FrameManager extends EventEmitter ``` -Extends: [EventEmitter](./puppeteer.eventemitter.md) ## Constructors diff --git a/new-docs/puppeteer.md b/new-docs/puppeteer.md index d6ba6af699f70..8144ee04f7d3e 100644 --- a/new-docs/puppeteer.md +++ b/new-docs/puppeteer.md @@ -11,7 +11,7 @@ | [Accessibility](./puppeteer.accessibility.md) | The Accessibility class provides methods for inspecting Chromium's accessibility tree. The accessibility tree is used by assistive technology such as [screen readers](https://en.wikipedia.org/wiki/Screen_reader) or [switches](https://en.wikipedia.org/wiki/Switch_access). | | [Browser](./puppeteer.browser.md) | | | [BrowserContext](./puppeteer.browsercontext.md) | | -| [BrowserFetcher](./puppeteer.browserfetcher.md) | | +| [BrowserFetcher](./puppeteer.browserfetcher.md) | BrowserFetcher can download and manage different versions of Chromium and Firefox. | | [CDPSession](./puppeteer.cdpsession.md) | | | [Connection](./puppeteer.connection.md) | | | [ConsoleMessage](./puppeteer.consolemessage.md) | | diff --git a/new-docs/puppeteer.page.md b/new-docs/puppeteer.page.md index fc1c7965b277c..0277bffd2672a 100644 --- a/new-docs/puppeteer.page.md +++ b/new-docs/puppeteer.page.md @@ -11,7 +11,6 @@ Page provides methods to interact with a single tab or \[extension background pa ```typescript export declare class Page extends EventEmitter ``` -Extends: [EventEmitter](./puppeteer.eventemitter.md) ## Remarks diff --git a/new-docs/puppeteer.timeouterror.md b/new-docs/puppeteer.timeouterror.md index 10ceabbef546f..7fc63559dc1ef 100644 --- a/new-docs/puppeteer.timeouterror.md +++ b/new-docs/puppeteer.timeouterror.md @@ -11,7 +11,6 @@ TimeoutError is emitted whenever certain operations are terminated due to timeou ```typescript export declare class TimeoutError extends CustomError ``` -Extends: CustomError ## Remarks diff --git a/new-docs/puppeteer.webworker.md b/new-docs/puppeteer.webworker.md index 23f649c150155..771e1d3bea583 100644 --- a/new-docs/puppeteer.webworker.md +++ b/new-docs/puppeteer.webworker.md @@ -11,7 +11,6 @@ The WebWorker class represents a [WebWorker](https://developer.mozilla.org/en-US ```typescript export declare class WebWorker extends EventEmitter ``` -Extends: [EventEmitter](./puppeteer.eventemitter.md) ## Remarks diff --git a/src/node/BrowserFetcher.ts b/src/node/BrowserFetcher.ts index b4082a771f8fc..e8a0b9093657a 100644 --- a/src/node/BrowserFetcher.ts +++ b/src/node/BrowserFetcher.ts @@ -80,11 +80,7 @@ function archiveName( } /** - * @param {string} product - * @param {string} platform - * @param {string} host - * @param {string} revision - * @returns {string} + * @internal */ function downloadURL( product: Product, @@ -101,7 +97,10 @@ function downloadURL( return url; } -function handleArm64() { +/** + * @internal + */ +function handleArm64(): void { fs.stat('/usr/bin/chromium-browser', function (err, stats) { if (stats === undefined) { console.error(`The chromium binary is not available for arm64: `); @@ -138,6 +137,27 @@ interface BrowserFetcherRevisionInfo { product: string; } /** + * BrowserFetcher can download and manage different versions of Chromium and Firefox. + * + * @remarks + * BrowserFetcher operates on revision strings that specify a precise version of Chromium, e.g. `"533271"`. Revision strings can be obtained from [omahaproxy.appspot.com](http://omahaproxy.appspot.com/). + * In the Firefox case, BrowserFetcher downloads Firefox Nightly and + * operates on version numbers such as `"75"`. + * + * @example + * An example of using BrowserFetcher to download a specific version of Chromium + * and running Puppeteer against it: + * + * ```js + * const browserFetcher = puppeteer.createBrowserFetcher(); + * const revisionInfo = await browserFetcher.download('533271'); + * const browser = await puppeteer.launch({executablePath: revisionInfo.executablePath}) + * ``` + * + * **NOTE** BrowserFetcher is not designed to work concurrently with other + * instances of BrowserFetcher that share the same downloads directory. + * + * @public */ export class BrowserFetcher { @@ -146,6 +166,9 @@ export class BrowserFetcher { private _downloadHost: string; private _platform: Platform; + /** + * @internal + */ constructor(projectRoot: string, options: BrowserFetcherOptions = {}) { this._product = (options.product || 'chrome').toLowerCase() as Product; assert( @@ -178,18 +201,35 @@ export class BrowserFetcher { else assert(this._platform, 'Unsupported platform: ' + os.platform()); } + /** + * @returns One of `mac`, `linux`, `win32` or `win64`. + */ platform(): string { return this._platform; } + /** + * @returns One of `chrome` or `firefox`. + */ product(): string { return this._product; } + /** + * @returns The download host being used. + */ host(): string { return this._downloadHost; } + /** + * Initiates a HEAD request to check if the revision is available. + * @remarks + * This method is affected by the current `product`. + * @param revision The revision to check availability for. + * @returns A promise that resolves to `true` if the revision could be downloaded + * from the host. + */ canDownload(revision: string): Promise { const url = downloadURL( this._product, @@ -209,9 +249,14 @@ export class BrowserFetcher { } /** - * @param {string} revision - * @param {?function(number, number):void} progressCallback - * @returns {!Promise} + * Initiates a GET request to download the revision from the host. + * @remarks + * This method is affected by the current `product`. + * @param revision The revision to download. + * @param progressCallback A function that will be called with two arguments: + * How many bytes have been downloaded and the total number of bytes of the download. + * @returns A promise with revision information when the revision is downloaded + * and extracted. */ async download( revision: string, @@ -244,6 +289,12 @@ export class BrowserFetcher { return revisionInfo; } + /** + * @remarks + * This method is affected by the current `product`. + * @returns A promise with a list of all revision strings (for the current `product`) + * available locally on disk. + */ async localRevisions(): Promise { if (!(await existsAsync(this._downloadsFolder))) return []; const fileNames = await readdirAsync(this._downloadsFolder); @@ -253,6 +304,13 @@ export class BrowserFetcher { .map((entry) => entry.revision); } + /** + * @remarks + * This method is affected by the current `product`. + * @param revision A revision to remove for the current `product`. + * @returns A promise that resolves when the revision has been removes or + * throws if the revision has not been downloaded. + */ async remove(revision: string): Promise { const folderPath = this._getFolderPath(revision); assert( @@ -262,6 +320,10 @@ export class BrowserFetcher { await new Promise((fulfill) => removeRecursive(folderPath, fulfill)); } + /** + * @param revision The revision to get info for. + * @returns The revision info for the given revision. + */ revisionInfo(revision: string): BrowserFetcherRevisionInfo { const folderPath = this._getFolderPath(revision); let executablePath = ''; @@ -331,8 +393,7 @@ export class BrowserFetcher { } /** - * @param {string} revision - * @returns {string} + * @internal */ _getFolderPath(revision: string): string { return path.join(this._downloadsFolder, this._platform + '-' + revision); From d8d774625ea5b254fc0597a100614aaa4828a656 Mon Sep 17 00:00:00 2001 From: martinsplitt Date: Tue, 23 Jun 2020 19:03:52 +0200 Subject: [PATCH 2/4] Adds tsdoc to BrowserFetcher --- new-docs/puppeteer.browser.md | 1 + new-docs/puppeteer.browsercontext.md | 1 + new-docs/puppeteer.browserfetcher.md | 2 +- new-docs/puppeteer.browserfetcher.platform.md | 2 +- new-docs/puppeteer.browserfetcher.product.md | 2 +- new-docs/puppeteer.cdpsession.md | 1 + new-docs/puppeteer.connection.md | 1 + new-docs/puppeteer.elementhandle.md | 1 + new-docs/puppeteer.eventemitter.md | 1 + new-docs/puppeteer.framemanager.md | 1 + new-docs/puppeteer.page.md | 1 + new-docs/puppeteer.timeouterror.md | 1 + new-docs/puppeteer.webworker.md | 1 + src/node/BrowserFetcher.ts | 37 +++++++++---------- 14 files changed, 30 insertions(+), 23 deletions(-) diff --git a/new-docs/puppeteer.browser.md b/new-docs/puppeteer.browser.md index d04f7335c0a06..4c669ee5802c7 100644 --- a/new-docs/puppeteer.browser.md +++ b/new-docs/puppeteer.browser.md @@ -9,6 +9,7 @@ ```typescript export declare class Browser extends EventEmitter ``` +Extends: [EventEmitter](./puppeteer.eventemitter.md) ## Constructors diff --git a/new-docs/puppeteer.browsercontext.md b/new-docs/puppeteer.browsercontext.md index 68a9b8284476c..393509a20ef7a 100644 --- a/new-docs/puppeteer.browsercontext.md +++ b/new-docs/puppeteer.browsercontext.md @@ -9,6 +9,7 @@ ```typescript export declare class BrowserContext extends EventEmitter ``` +Extends: [EventEmitter](./puppeteer.eventemitter.md) ## Constructors diff --git a/new-docs/puppeteer.browserfetcher.md b/new-docs/puppeteer.browserfetcher.md index 7b6172bd9e4c0..e335b693b4f05 100644 --- a/new-docs/puppeteer.browserfetcher.md +++ b/new-docs/puppeteer.browserfetcher.md @@ -14,7 +14,7 @@ export declare class BrowserFetcher ## Remarks -BrowserFetcher operates on revision strings that specify a precise version of Chromium, e.g. `"533271"`. Revision strings can be obtained from \[omahaproxy.appspot.com\](http://omahaproxy.appspot.com/). In the Firefox case, BrowserFetcher downloads Firefox Nightly and operates on version numbers such as `"75"`. +BrowserFetcher operates on revision strings that specify a precise version of Chromium, e.g. `"533271"`. Revision strings can be obtained from [omahaproxy.appspot.com](http://omahaproxy.appspot.com/). In the Firefox case, BrowserFetcher downloads Firefox Nightly and operates on version numbers such as `"75"`. The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `BrowserFetcher` class. diff --git a/new-docs/puppeteer.browserfetcher.platform.md b/new-docs/puppeteer.browserfetcher.platform.md index 8f55cd2ae1fc5..1be81478eae46 100644 --- a/new-docs/puppeteer.browserfetcher.platform.md +++ b/new-docs/puppeteer.browserfetcher.platform.md @@ -13,5 +13,5 @@ platform(): string; string -One of `mac`, `linux`, `win32` or `win64`. +Returns the current `Platform`. diff --git a/new-docs/puppeteer.browserfetcher.product.md b/new-docs/puppeteer.browserfetcher.product.md index 7b2201366edb0..89d248e725a49 100644 --- a/new-docs/puppeteer.browserfetcher.product.md +++ b/new-docs/puppeteer.browserfetcher.product.md @@ -13,5 +13,5 @@ product(): string; string -One of `chrome` or `firefox`. +Returns the current `Product`. diff --git a/new-docs/puppeteer.cdpsession.md b/new-docs/puppeteer.cdpsession.md index cca7a99042691..1f3987c67c37b 100644 --- a/new-docs/puppeteer.cdpsession.md +++ b/new-docs/puppeteer.cdpsession.md @@ -9,6 +9,7 @@ ```typescript export declare class CDPSession extends EventEmitter ``` +Extends: [EventEmitter](./puppeteer.eventemitter.md) ## Constructors diff --git a/new-docs/puppeteer.connection.md b/new-docs/puppeteer.connection.md index 3fb04345462b1..75fff814e8c64 100644 --- a/new-docs/puppeteer.connection.md +++ b/new-docs/puppeteer.connection.md @@ -9,6 +9,7 @@ ```typescript export declare class Connection extends EventEmitter ``` +Extends: [EventEmitter](./puppeteer.eventemitter.md) ## Constructors diff --git a/new-docs/puppeteer.elementhandle.md b/new-docs/puppeteer.elementhandle.md index 6280f20a45367..a5b14ac0d9197 100644 --- a/new-docs/puppeteer.elementhandle.md +++ b/new-docs/puppeteer.elementhandle.md @@ -9,6 +9,7 @@ ```typescript export declare class ElementHandle extends JSHandle ``` +Extends: [JSHandle](./puppeteer.jshandle.md) ## Constructors diff --git a/new-docs/puppeteer.eventemitter.md b/new-docs/puppeteer.eventemitter.md index 9937c5b2acac9..99d26ef45a8d5 100644 --- a/new-docs/puppeteer.eventemitter.md +++ b/new-docs/puppeteer.eventemitter.md @@ -11,6 +11,7 @@ The EventEmitter class that many Puppeteer classes extend. ```typescript export declare class EventEmitter implements CommonEventEmitter ``` +Implements: CommonEventEmitter ## Remarks diff --git a/new-docs/puppeteer.framemanager.md b/new-docs/puppeteer.framemanager.md index d5322f6fe5670..f1563870ebec9 100644 --- a/new-docs/puppeteer.framemanager.md +++ b/new-docs/puppeteer.framemanager.md @@ -9,6 +9,7 @@ ```typescript export declare class FrameManager extends EventEmitter ``` +Extends: [EventEmitter](./puppeteer.eventemitter.md) ## Constructors diff --git a/new-docs/puppeteer.page.md b/new-docs/puppeteer.page.md index 0277bffd2672a..fc1c7965b277c 100644 --- a/new-docs/puppeteer.page.md +++ b/new-docs/puppeteer.page.md @@ -11,6 +11,7 @@ Page provides methods to interact with a single tab or \[extension background pa ```typescript export declare class Page extends EventEmitter ``` +Extends: [EventEmitter](./puppeteer.eventemitter.md) ## Remarks diff --git a/new-docs/puppeteer.timeouterror.md b/new-docs/puppeteer.timeouterror.md index 7fc63559dc1ef..10ceabbef546f 100644 --- a/new-docs/puppeteer.timeouterror.md +++ b/new-docs/puppeteer.timeouterror.md @@ -11,6 +11,7 @@ TimeoutError is emitted whenever certain operations are terminated due to timeou ```typescript export declare class TimeoutError extends CustomError ``` +Extends: CustomError ## Remarks diff --git a/new-docs/puppeteer.webworker.md b/new-docs/puppeteer.webworker.md index 771e1d3bea583..23f649c150155 100644 --- a/new-docs/puppeteer.webworker.md +++ b/new-docs/puppeteer.webworker.md @@ -11,6 +11,7 @@ The WebWorker class represents a [WebWorker](https://developer.mozilla.org/en-US ```typescript export declare class WebWorker extends EventEmitter ``` +Extends: [EventEmitter](./puppeteer.eventemitter.md) ## Remarks diff --git a/src/node/BrowserFetcher.ts b/src/node/BrowserFetcher.ts index e8a0b9093657a..96e6b580e3d6b 100644 --- a/src/node/BrowserFetcher.ts +++ b/src/node/BrowserFetcher.ts @@ -59,7 +59,13 @@ const browserConfig = { }, } as const; +/** + * Supported platforms. + */ type Platform = 'linux' | 'mac' | 'win32' | 'win64'; +/** + * Supported products. + */ type Product = 'chrome' | 'firefox'; function archiveName( @@ -140,7 +146,7 @@ interface BrowserFetcherRevisionInfo { * BrowserFetcher can download and manage different versions of Chromium and Firefox. * * @remarks - * BrowserFetcher operates on revision strings that specify a precise version of Chromium, e.g. `"533271"`. Revision strings can be obtained from [omahaproxy.appspot.com](http://omahaproxy.appspot.com/). + * BrowserFetcher operates on revision strings that specify a precise version of Chromium, e.g. `"533271"`. Revision strings can be obtained from {@link http://omahaproxy.appspot.com/ | omahaproxy.appspot.com}. * In the Firefox case, BrowserFetcher downloads Firefox Nightly and * operates on version numbers such as `"75"`. * @@ -202,14 +208,14 @@ export class BrowserFetcher { } /** - * @returns One of `mac`, `linux`, `win32` or `win64`. + * @returns Returns the current `Platform`. */ platform(): string { return this._platform; } /** - * @returns One of `chrome` or `firefox`. + * @returns Returns the current `Product`. */ product(): string { return this._product; @@ -226,7 +232,7 @@ export class BrowserFetcher { * Initiates a HEAD request to check if the revision is available. * @remarks * This method is affected by the current `product`. - * @param revision The revision to check availability for. + * @param revision - The revision to check availability for. * @returns A promise that resolves to `true` if the revision could be downloaded * from the host. */ @@ -252,8 +258,8 @@ export class BrowserFetcher { * Initiates a GET request to download the revision from the host. * @remarks * This method is affected by the current `product`. - * @param revision The revision to download. - * @param progressCallback A function that will be called with two arguments: + * @param revision - The revision to download. + * @param progressCallback - A function that will be called with two arguments: * How many bytes have been downloaded and the total number of bytes of the download. * @returns A promise with revision information when the revision is downloaded * and extracted. @@ -307,7 +313,7 @@ export class BrowserFetcher { /** * @remarks * This method is affected by the current `product`. - * @param revision A revision to remove for the current `product`. + * @param revision - A revision to remove for the current `product`. * @returns A promise that resolves when the revision has been removes or * throws if the revision has not been downloaded. */ @@ -321,7 +327,7 @@ export class BrowserFetcher { } /** - * @param revision The revision to get info for. + * @param revision - The revision to get info for. * @returns The revision info for the given revision. */ revisionInfo(revision: string): BrowserFetcherRevisionInfo { @@ -413,10 +419,7 @@ function parseFolderPath( } /** - * @param {string} url - * @param {string} destinationPath - * @param {?function(number, number):void} progressCallback - * @returns {!Promise} + * @internal */ function downloadFile( url: string, @@ -476,9 +479,7 @@ function install(archivePath: string, folderPath: string): Promise { } /** - * @param {string} tarPath - * @param {string} folderPath - * @returns {!Promise} + * @internal */ function extractTar(tarPath: string, folderPath: string): Promise { // eslint-disable-next-line @typescript-eslint/no-var-requires @@ -495,11 +496,7 @@ function extractTar(tarPath: string, folderPath: string): Promise { } /** - * Install *.app directory from dmg file - * - * @param {string} dmgPath - * @param {string} folderPath - * @returns {!Promise} + * @internal */ function installDMG(dmgPath: string, folderPath: string): Promise { let mountPath; From 64c1186b981bef2763a029d74930e595c188bba0 Mon Sep 17 00:00:00 2001 From: martinsplitt Date: Wed, 24 Jun 2020 08:42:54 +0200 Subject: [PATCH 3/4] Updates return types in BrowserFetcher --- new-docs/puppeteer.browserfetcher.platform.md | 4 ++-- new-docs/puppeteer.browserfetcher.product.md | 4 ++-- src/node/BrowserFetcher.ts | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/new-docs/puppeteer.browserfetcher.platform.md b/new-docs/puppeteer.browserfetcher.platform.md index 1be81478eae46..92303f46888af 100644 --- a/new-docs/puppeteer.browserfetcher.platform.md +++ b/new-docs/puppeteer.browserfetcher.platform.md @@ -7,11 +7,11 @@ Signature: ```typescript -platform(): string; +platform(): Platform; ``` Returns: -string +Platform Returns the current `Platform`. diff --git a/new-docs/puppeteer.browserfetcher.product.md b/new-docs/puppeteer.browserfetcher.product.md index 89d248e725a49..861c9b7864dcf 100644 --- a/new-docs/puppeteer.browserfetcher.product.md +++ b/new-docs/puppeteer.browserfetcher.product.md @@ -7,11 +7,11 @@ Signature: ```typescript -product(): string; +product(): Product; ``` Returns: -string +Product Returns the current `Product`. diff --git a/src/node/BrowserFetcher.ts b/src/node/BrowserFetcher.ts index 96e6b580e3d6b..d48e6a59ba00e 100644 --- a/src/node/BrowserFetcher.ts +++ b/src/node/BrowserFetcher.ts @@ -210,14 +210,14 @@ export class BrowserFetcher { /** * @returns Returns the current `Platform`. */ - platform(): string { + platform(): Platform { return this._platform; } /** * @returns Returns the current `Product`. */ - product(): string { + product(): Product { return this._product; } From 505466b05d22a2662def960bf9b5cbf5b5295a27 Mon Sep 17 00:00:00 2001 From: martinsplitt Date: Wed, 24 Jun 2020 09:45:02 +0200 Subject: [PATCH 4/4] Fixes puppeteer class docs --- new-docs/puppeteer.md | 156 +++++++++++++++++++++--------------------- 1 file changed, 78 insertions(+), 78 deletions(-) diff --git a/new-docs/puppeteer.md b/new-docs/puppeteer.md index 8f4c04245c622..e0219567f813b 100644 --- a/new-docs/puppeteer.md +++ b/new-docs/puppeteer.md @@ -1,78 +1,78 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) - -## puppeteer package - -## Classes - -| Class | Description | -| --- | --- | -| [Accessibility](./puppeteer.accessibility.md) | The Accessibility class provides methods for inspecting Chromium's accessibility tree. The accessibility tree is used by assistive technology such as [screen readers](https://en.wikipedia.org/wiki/Screen_reader) or [switches](https://en.wikipedia.org/wiki/Switch_access). | -| [Browser](./puppeteer.browser.md) | A Browser is created when Puppeteer connects to a Chromium instance, either through [Puppeteer.launch()](./puppeteer.puppeteer.launch.md) or [Puppeteer.connect()](./puppeteer.puppeteer.connect.md). | -| [BrowserContext](./puppeteer.browsercontext.md) | BrowserContexts provide a way to operate multiple independent browser sessions. When a browser is launched, it has a single BrowserContext used by default. The method [Browser.newPage](./puppeteer.browser.newpage.md) creates a page in the default browser context. | -| [BrowserFetcher](./puppeteer.browserfetcher.md) | BrowserFetcher can download and manage different versions of Chromium and Firefox. | -| [CDPSession](./puppeteer.cdpsession.md) | The CDPSession instances are used to talk raw Chrome Devtools Protocol. | -| [Connection](./puppeteer.connection.md) | | -| [ConsoleMessage](./puppeteer.consolemessage.md) | ConsoleMessage objects are dispatched by page via the 'console' event. | -| [Coverage](./puppeteer.coverage.md) | | -| [Dialog](./puppeteer.dialog.md) | Dialog instances are dispatched by the [Page](./puppeteer.page.md) via the dialog event. | -| [ElementHandle](./puppeteer.elementhandle.md) | ElementHandle represents an in-page DOM element. | -| [EventEmitter](./puppeteer.eventemitter.md) | The EventEmitter class that many Puppeteer classes extend. | -| [ExecutionContext](./puppeteer.executioncontext.md) | | -| [FileChooser](./puppeteer.filechooser.md) | | -| [Frame](./puppeteer.frame.md) | | -| [FrameManager](./puppeteer.framemanager.md) | | -| [HTTPRequest](./puppeteer.httprequest.md) | | -| [HTTPResponse](./puppeteer.httpresponse.md) | | -| [JSHandle](./puppeteer.jshandle.md) | | -| [Keyboard](./puppeteer.keyboard.md) | | -| [Mouse](./puppeteer.mouse.md) | | -| [Page](./puppeteer.page.md) | Page provides methods to interact with a single tab or \[extension background page\](https://developer.chrome.com/extensions/background\_pages) in Chromium. One \[Browser\] instance might have multiple \[Page\] instances. | -| [Puppeteer](./puppeteer.puppeteer.md) | The main Puppeteer class | -| [SecurityDetails](./puppeteer.securitydetails.md) | The SecurityDetails class represents the security details of a response that was received over a secure connection. | -| [Target](./puppeteer.target.md) | | -| [TimeoutError](./puppeteer.timeouterror.md) | TimeoutError is emitted whenever certain operations are terminated due to timeout. | -| [Touchscreen](./puppeteer.touchscreen.md) | | -| [Tracing](./puppeteer.tracing.md) | | -| [WebWorker](./puppeteer.webworker.md) | The WebWorker class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). | - -## Enumerations - -| Enumeration | Description | -| --- | --- | -| [PageEmittedEvents](./puppeteer.pageemittedevents.md) | All the events that a page instance may emit. | - -## Interfaces - -| Interface | Description | -| --- | --- | -| [BoundingBox](./puppeteer.boundingbox.md) | | -| [BoxModel](./puppeteer.boxmodel.md) | | -| [BrowserFetcherOptions](./puppeteer.browserfetcheroptions.md) | | -| [ClickOptions](./puppeteer.clickoptions.md) | | -| [ConsoleMessageLocation](./puppeteer.consolemessagelocation.md) | | -| [KeyDefinition](./puppeteer.keydefinition.md) | Copyright 2017 Google Inc. All rights reserved.Licensed under the Apache License, Version 2.0 (the 'License'); you may not use this file except in compliance with the License. You may obtain a copy of the License athttp://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an 'AS IS' BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. | -| [Metrics](./puppeteer.metrics.md) | | -| [PressOptions](./puppeteer.pressoptions.md) | | -| [SerializedAXNode](./puppeteer.serializedaxnode.md) | Represents a Node and the properties of it that are relevant to Accessibility. | -| [SnapshotOptions](./puppeteer.snapshotoptions.md) | | -| [WaitForTargetOptions](./puppeteer.waitfortargetoptions.md) | | - -## Variables - -| Variable | Description | -| --- | --- | -| [EVALUATION\_SCRIPT\_URL](./puppeteer.evaluation_script_url.md) | | -| [keyDefinitions](./puppeteer.keydefinitions.md) | | -| [puppeteerErrors](./puppeteer.puppeteererrors.md) | | - -## Type Aliases - -| Type Alias | Description | -| --- | --- | -| [ConsoleMessageType](./puppeteer.consolemessagetype.md) | The supported types for console messages. | -| [KeyInput](./puppeteer.keyinput.md) | | -| [MouseButtonInput](./puppeteer.mousebuttoninput.md) | | -| [PuppeteerErrors](./puppeteer.puppeteererrors.md) | | - + + +[Home](./index.md) > [puppeteer](./puppeteer.md) + +## puppeteer package + +## Classes + +| Class | Description | +| --- | --- | +| [Accessibility](./puppeteer.accessibility.md) | The Accessibility class provides methods for inspecting Chromium's accessibility tree. The accessibility tree is used by assistive technology such as [screen readers](https://en.wikipedia.org/wiki/Screen_reader) or [switches](https://en.wikipedia.org/wiki/Switch_access). | +| [Browser](./puppeteer.browser.md) | A Browser is created when Puppeteer connects to a Chromium instance, either through [Puppeteer.launch()](./puppeteer.puppeteer.launch.md) or [Puppeteer.connect()](./puppeteer.puppeteer.connect.md). | +| [BrowserContext](./puppeteer.browsercontext.md) | BrowserContexts provide a way to operate multiple independent browser sessions. When a browser is launched, it has a single BrowserContext used by default. The method [Browser.newPage](./puppeteer.browser.newpage.md) creates a page in the default browser context. | +| [BrowserFetcher](./puppeteer.browserfetcher.md) | BrowserFetcher can download and manage different versions of Chromium and Firefox. | +| [CDPSession](./puppeteer.cdpsession.md) | The CDPSession instances are used to talk raw Chrome Devtools Protocol. | +| [Connection](./puppeteer.connection.md) | | +| [ConsoleMessage](./puppeteer.consolemessage.md) | ConsoleMessage objects are dispatched by page via the 'console' event. | +| [Coverage](./puppeteer.coverage.md) | | +| [Dialog](./puppeteer.dialog.md) | Dialog instances are dispatched by the [Page](./puppeteer.page.md) via the dialog event. | +| [ElementHandle](./puppeteer.elementhandle.md) | ElementHandle represents an in-page DOM element. | +| [EventEmitter](./puppeteer.eventemitter.md) | The EventEmitter class that many Puppeteer classes extend. | +| [ExecutionContext](./puppeteer.executioncontext.md) | | +| [FileChooser](./puppeteer.filechooser.md) | | +| [Frame](./puppeteer.frame.md) | | +| [FrameManager](./puppeteer.framemanager.md) | | +| [HTTPRequest](./puppeteer.httprequest.md) | | +| [HTTPResponse](./puppeteer.httpresponse.md) | | +| [JSHandle](./puppeteer.jshandle.md) | | +| [Keyboard](./puppeteer.keyboard.md) | | +| [Mouse](./puppeteer.mouse.md) | | +| [Page](./puppeteer.page.md) | Page provides methods to interact with a single tab or \[extension background page\](https://developer.chrome.com/extensions/background\_pages) in Chromium. One \[Browser\] instance might have multiple \[Page\] instances. | +| [Puppeteer](./puppeteer.puppeteer.md) | The main Puppeteer class | +| [SecurityDetails](./puppeteer.securitydetails.md) | The SecurityDetails class represents the security details of a response that was received over a secure connection. | +| [Target](./puppeteer.target.md) | | +| [TimeoutError](./puppeteer.timeouterror.md) | TimeoutError is emitted whenever certain operations are terminated due to timeout. | +| [Touchscreen](./puppeteer.touchscreen.md) | | +| [Tracing](./puppeteer.tracing.md) | | +| [WebWorker](./puppeteer.webworker.md) | The WebWorker class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). | + +## Enumerations + +| Enumeration | Description | +| --- | --- | +| [PageEmittedEvents](./puppeteer.pageemittedevents.md) | All the events that a page instance may emit. | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [BoundingBox](./puppeteer.boundingbox.md) | | +| [BoxModel](./puppeteer.boxmodel.md) | | +| [BrowserFetcherOptions](./puppeteer.browserfetcheroptions.md) | | +| [ClickOptions](./puppeteer.clickoptions.md) | | +| [ConsoleMessageLocation](./puppeteer.consolemessagelocation.md) | | +| [KeyDefinition](./puppeteer.keydefinition.md) | Copyright 2017 Google Inc. All rights reserved.Licensed under the Apache License, Version 2.0 (the 'License'); you may not use this file except in compliance with the License. You may obtain a copy of the License athttp://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an 'AS IS' BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. | +| [Metrics](./puppeteer.metrics.md) | | +| [PressOptions](./puppeteer.pressoptions.md) | | +| [SerializedAXNode](./puppeteer.serializedaxnode.md) | Represents a Node and the properties of it that are relevant to Accessibility. | +| [SnapshotOptions](./puppeteer.snapshotoptions.md) | | +| [WaitForTargetOptions](./puppeteer.waitfortargetoptions.md) | | + +## Variables + +| Variable | Description | +| --- | --- | +| [EVALUATION\_SCRIPT\_URL](./puppeteer.evaluation_script_url.md) | | +| [keyDefinitions](./puppeteer.keydefinitions.md) | | +| [puppeteerErrors](./puppeteer.puppeteererrors.md) | | + +## Type Aliases + +| Type Alias | Description | +| --- | --- | +| [ConsoleMessageType](./puppeteer.consolemessagetype.md) | The supported types for console messages. | +| [KeyInput](./puppeteer.keyinput.md) | | +| [MouseButtonInput](./puppeteer.mousebuttoninput.md) | | +| [PuppeteerErrors](./puppeteer.puppeteererrors.md) | | +