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;