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 1e44245da0928..15679730e6d64 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): P | 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..e335b693b4f05 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..92303f46888af 100644 --- a/new-docs/puppeteer.browserfetcher.platform.md +++ b/new-docs/puppeteer.browserfetcher.platform.md @@ -7,9 +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 a8bf2223e150e..861c9b7864dcf 100644 --- a/new-docs/puppeteer.browserfetcher.product.md +++ b/new-docs/puppeteer.browserfetcher.product.md @@ -7,9 +7,11 @@ Signature: ```typescript -product(): string; +product(): Product; ``` Returns: -string +Product + +Returns the current `Product`. 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.md b/new-docs/puppeteer.md index 83272458a6231..e0219567f813b 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) | 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](./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. | diff --git a/src/node/BrowserFetcher.ts b/src/node/BrowserFetcher.ts index 4f879da6b0eef..9f5df3cda6ce9 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( @@ -80,11 +86,7 @@ function archiveName( } /** - * @param {string} product - * @param {string} platform - * @param {string} host - * @param {string} revision - * @returns {string} + * @internal */ function downloadURL( product: Product, @@ -101,7 +103,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 +143,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 {@link http://omahaproxy.appspot.com/ | 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 +172,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 +207,35 @@ export class BrowserFetcher { else assert(this._platform, 'Unsupported platform: ' + os.platform()); } - platform(): string { + /** + * @returns Returns the current `Platform`. + */ + platform(): Platform { return this._platform; } - product(): string { + /** + * @returns Returns the current `Product`. + */ + product(): Product { 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 +255,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 +295,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 +310,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 +326,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 +399,7 @@ export class BrowserFetcher { } /** - * @param {string} revision - * @returns {string} + * @internal */ _getFolderPath(revision: string): string { return path.join(this._downloadsFolder, this._platform + '-' + revision); @@ -352,10 +419,7 @@ function parseFolderPath( } /** - * @param {string} url - * @param {string} destinationPath - * @param {?function(number, number):void} progressCallback - * @returns {!Promise} + * @internal */ function downloadFile( url: string, @@ -415,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 @@ -434,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;