feat: add page.emulateCPUThrottling

docs/api.md

@@ -138,6 +138,7 @@
   * [page.coverage](#pagecoverage)
   * [page.deleteCookie(...cookies)](#pagedeletecookiecookies)
   * [page.emulate(options)](#pageemulateoptions)
+  * [page.emulateCPUThrottling(rate)](#pageemulatecputhrottlingrate)
   * [page.emulateIdleState(overrides)](#pageemulateidlestateoverrides)
   * [page.emulateMediaFeatures(features)](#pageemulatemediafeaturesfeatures)
   * [page.emulateMediaType(type)](#pageemulatemediatypetype)
@@ -1535,6 +1536,27 @@ const iPhone = puppeteer.devices['iPhone 6'];
 
 List of all available devices is available in the source code: [src/common/DeviceDescriptors.ts](https://github.com/puppeteer/puppeteer/blob/main/src/common/DeviceDescriptors.ts).
 
+#### page.emulateCPUThrottling(rate)
+
+- `rate` <?[number]> Rate at which the CPU will be throttled (2x, 3x, ...). Passing `null` disables cpu throttling.
+- returns: <[Promise]>
+
+> **NOTE** Real device CPU performance is impacted by many factors that are not trivial to emulate via the Chrome DevTools Protocol / Puppeteer. e.g core count, L1/L2 cache, thermal throttling impacting performance, architecture etc. Simulating CPU performance can be a good guideline, but ideally also verify any numbers you see on a real mobile device.
+
+```js
+const puppeteer = require('puppeteer');
+const slow3G = puppeteer.networkConditions['Slow 3G'];
+
+(async () => {
+  const browser = await puppeteer.launch();
+  const page = await browser.newPage();
+  await page.emulateCPUThrottling(2);
+  await page.goto('https://www.google.com');
+  // other actions...
+  await browser.close();
+})();
+```
+
 #### page.emulateIdleState(overrides)
 
 - `overrides` <?[Object]> If not set, clears emulation

src/common/Page.ts

@@ -1587,6 +1587,16 @@ export class Page extends EventEmitter {
     });
   }
 
+  async emulateCPUThrottling(rate: number | null): Promise<void> {
+    assert(
+      rate === null || rate >= 1,
+      'Throttling rate should be greater or equal to 1'
+    );
+    await this._client.send('Emulation.setCPUThrottlingRate', {
+      rate: rate !== null ? rate : 1,
+    });
+  }
+
   /**
    * @param features - `<?Array<Object>>` Given an array of media feature
    * objects, emulates CSS media features on the page. Each media feature object

test/emulation.spec.ts

@@ -408,4 +408,34 @@ describe('Emulation', () => {
       await page.emulateNetworkConditions(null);
     });
   });
+
+  describeFailsFirefox('Page.emulateCPUThrottling', function () {
+    it('should slow down execution', async () => {
+      const { page } = getTestState();
+
+      async function measure() {
+        const start = new Date();
+        await page.evaluate(() => {
+          let i = 0;
+          while (i < 1000) {
+            i++;
+          }
+        });
+
+        const end = new Date();
+        return +end - +start;
+      }
+
+      const baseline = await measure();
+      await page.emulateCPUThrottling(100);
+      const throttledTime = await measure();
+      await page.emulateCPUThrottling(null);
+      const timeWithoutThrottle = await measure();
+
+      // Throttling is not super precise. 20 has been chosen as very loose
+      // threshold just to make sure that throttling has at least _some_ effect.
+      expect(throttledTime / baseline).toBeGreaterThan(20);
+      expect(timeWithoutThrottle / baseline).toBeLessThan(20);
+    });
+  });
 });