feat: add an ability to trim cache for Puppeteer (#10199)

docs/api/index.md

@@ -135,6 +135,7 @@ sidebar_label: API
 | [networkConditions](./puppeteer.networkconditions.md)                                         |                                                                                                                               |
 | [PredefinedNetworkConditions](./puppeteer.predefinednetworkconditions.md)                     | A list of network conditions to be used with [Page.emulateNetworkConditions()](./puppeteer.page.emulatenetworkconditions.md). |
 | [puppeteer](./puppeteer.puppeteer.md)                                                         |                                                                                                                               |
+| [trimCache](./puppeteer.trimcache.md)                                                         |                                                                                                                               |
 
 ## Type Aliases
 

docs/api/puppeteer.puppeteernode.md

@@ -52,9 +52,10 @@ Once you have created a `page` you have access to a large API to interact with t
 
 ## Methods
 
-| Method                                                                 | Modifiers | Description                                                                                                                                                                                                                                                        |
-| ---------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| [connect(options)](./puppeteer.puppeteernode.connect.md)               |           | This method attaches Puppeteer to an existing browser instance.                                                                                                                                                                                                    |
-| [defaultArgs(options)](./puppeteer.puppeteernode.defaultargs.md)       |           |                                                                                                                                                                                                                                                                    |
-| [executablePath(channel)](./puppeteer.puppeteernode.executablepath.md) |           | The default executable path.                                                                                                                                                                                                                                       |
-| [launch(options)](./puppeteer.puppeteernode.launch.md)                 |           | <p>Launches a browser instance with given arguments and options when specified.</p><p>When using with <code>puppeteer-core</code>, [options.executablePath](./puppeteer.launchoptions.md) or [options.channel](./puppeteer.launchoptions.md) must be provided.</p> |
+| Method                                                                 | Modifiers | Description                                                                                                                                                                                                                                                                             |
+| ---------------------------------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [connect(options)](./puppeteer.puppeteernode.connect.md)               |           | This method attaches Puppeteer to an existing browser instance.                                                                                                                                                                                                                         |
+| [defaultArgs(options)](./puppeteer.puppeteernode.defaultargs.md)       |           |                                                                                                                                                                                                                                                                                         |
+| [executablePath(channel)](./puppeteer.puppeteernode.executablepath.md) |           | The default executable path.                                                                                                                                                                                                                                                            |
+| [launch(options)](./puppeteer.puppeteernode.launch.md)                 |           | <p>Launches a browser instance with given arguments and options when specified.</p><p>When using with <code>puppeteer-core</code>, [options.executablePath](./puppeteer.launchoptions.md) or [options.channel](./puppeteer.launchoptions.md) must be provided.</p>                      |
+| [trimCache()](./puppeteer.puppeteernode.trimcache.md)                  |           | Removes all non-current Firefox and Chrome binaries in the cache directory identified by the provided Puppeteer configuration. The current browser version is determined by resolving PUPPETEER_REVISIONS from Puppeteer unless <code>configuration.browserRevision</code> is provided. |

docs/api/puppeteer.puppeteernode.trimcache.md

@@ -0,0 +1,23 @@
+---
+sidebar_label: PuppeteerNode.trimCache
+---
+
+# PuppeteerNode.trimCache() method
+
+Removes all non-current Firefox and Chrome binaries in the cache directory identified by the provided Puppeteer configuration. The current browser version is determined by resolving PUPPETEER_REVISIONS from Puppeteer unless `configuration.browserRevision` is provided.
+
+#### Signature:
+
+```typescript
+class PuppeteerNode {
+  trimCache(): Promise<void>;
+}
+```
+
+**Returns:**
+
+Promise&lt;void&gt;
+
+## Remarks
+
+Note that the method does not check if any other Puppeteer versions installed on the host that use the same cache directory require the non-current binaries.

docs/api/puppeteer.trimcache.md

@@ -0,0 +1,11 @@
+---
+sidebar_label: trimCache
+---
+
+# trimCache variable
+
+#### Signature:
+
+```typescript
+trimCache: () => Promise<void>;
+```

packages/puppeteer-core/src/node/PuppeteerNode.ts

@@ -14,6 +14,14 @@
  * limitations under the License.
  */
 
+import {
+  Browser as SupportedBrowser,
+  resolveBuildId,
+  detectBrowserPlatform,
+  getInstalledBrowsers,
+  uninstall,
+} from '@puppeteer/browsers';
+
 import {Browser} from '../api/Browser.js';
 import {BrowserConnectOptions} from '../common/BrowserConnector.js';
 import {Configuration} from '../common/Configuration.js';
@@ -264,4 +272,73 @@ export class PuppeteerNode extends Puppeteer {
   defaultArgs(options: BrowserLaunchArgumentOptions = {}): string[] {
     return this.#launcher.defaultArgs(options);
   }
+
+  /**
+   * Removes all non-current Firefox and Chrome binaries in the cache directory
+   * identified by the provided Puppeteer configuration. The current browser
+   * version is determined by resolving PUPPETEER_REVISIONS from Puppeteer
+   * unless `configuration.browserRevision` is provided.
+   *
+   * @remarks
+   *
+   * Note that the method does not check if any other Puppeteer versions
+   * installed on the host that use the same cache directory require the
+   * non-current binaries.
+   *
+   * @public
+   */
+  async trimCache(): Promise<void> {
+    const platform = detectBrowserPlatform();
+    if (!platform) {
+      throw new Error('The current platform is not supported.');
+    }
+
+    const cacheDir =
+      this.configuration.downloadPath ?? this.configuration.cacheDirectory!;
+    const installedBrowsers = await getInstalledBrowsers({
+      cacheDir,
+    });
+
+    const product = this.configuration.defaultProduct!;
+
+    const chromeBuildId = await resolveBuildId(
+      SupportedBrowser.CHROME,
+      platform,
+      (product === 'chrome' ? this.configuration.browserRevision : null) ||
+        PUPPETEER_REVISIONS['chrome']
+    );
+
+    const firefoxBuildId = await resolveBuildId(
+      SupportedBrowser.FIREFOX,
+      platform,
+      (product === 'firefox' ? this.configuration.browserRevision : null) ||
+        PUPPETEER_REVISIONS['firefox']
+    );
+
+    for (const browser of installedBrowsers) {
+      if (
+        browser.browser === SupportedBrowser.CHROME &&
+        browser.buildId !== chromeBuildId
+      ) {
+        await uninstall({
+          browser: SupportedBrowser.CHROME,
+          platform,
+          cacheDir,
+          buildId: chromeBuildId,
+        });
+      }
+
+      if (
+        browser.browser === SupportedBrowser.FIREFOX &&
+        browser.buildId !== firefoxBuildId
+      ) {
+        await uninstall({
+          browser: SupportedBrowser.FIREFOX,
+          platform,
+          cacheDir,
+          buildId: firefoxBuildId,
+        });
+      }
+    }
+  }
 }

packages/puppeteer/src/getConfiguration.ts

@@ -1,3 +1,19 @@
+/**
+ * Copyright 2023 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 at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless 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.
+ */
+
 import {homedir} from 'os';
 import {join} from 'path';
 

packages/puppeteer/src/puppeteer.ts

@@ -49,6 +49,10 @@ export const {
    * @public
    */
   launch,
+  /**
+   * @public
+   */
+  trimCache,
 } = puppeteer;
 
 export default puppeteer;

test/installation/assets/puppeteer/installCanary.js

@@ -0,0 +1,34 @@
+/**
+ * Copyright 2023 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 at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless 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.
+ */
+
+import {
+  Browser,
+  detectBrowserPlatform,
+  install,
+  resolveBuildId,
+} from '@puppeteer/browsers';
+
+(async () => {
+  await install({
+    cacheDir: process.env['PUPPETEER_CACHE_DIR'],
+    browser: Browser.CHROME,
+    buildId: await resolveBuildId(
+      Browser.CHROME,
+      detectBrowserPlatform(),
+      'canary'
+    ),
+  });
+})();

test/installation/assets/puppeteer/trimCache.js

@@ -0,0 +1,21 @@
+/**
+ * Copyright 2023 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 at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless 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.
+ */
+
+import puppeteer from 'puppeteer';
+
+(async () => {
+  await puppeteer.trimCache();
+})();

test/installation/src/puppeteer.spec.ts

@@ -15,6 +15,7 @@
  */
 
 import assert from 'assert';
+import {readdirSync} from 'fs';
 import {readdir} from 'fs/promises';
 import {join} from 'path';
 
@@ -64,3 +65,38 @@ describe('`puppeteer` with PUPPETEER_DOWNLOAD_PATH', () => {
     await this.runScript(script, 'mjs');
   });
 });
+
+describe('`puppeteer` clears cache', () => {
+  configureSandbox({
+    dependencies: ['@puppeteer/browsers', 'puppeteer-core', 'puppeteer'],
+    env: cwd => {
+      return {
+        PUPPETEER_CACHE_DIR: join(cwd, '.cache', 'puppeteer'),
+      };
+    },
+  });
+
+  it('evaluates', async function () {
+    assert.equal(
+      readdirSync(join(this.sandbox, '.cache', 'puppeteer', 'chrome')).length,
+      1
+    );
+
+    await this.runScript(
+      await readAsset('puppeteer', 'installCanary.js'),
+      'mjs'
+    );
+
+    assert.equal(
+      readdirSync(join(this.sandbox, '.cache', 'puppeteer', 'chrome')).length,
+      2
+    );
+
+    await this.runScript(await readAsset('puppeteer', 'trimCache.js'), 'mjs');
+
+    assert.equal(
+      readdirSync(join(this.sandbox, '.cache', 'puppeteer', 'chrome')).length,
+      1
+    );
+  });
+});