feat(api): add page.emulateTimezone(timezoneId) (#4949)

This enables dynamically changing the timezone of the page.

docs/api.md

@@ -111,6 +111,7 @@
   * [page.emulateMedia(type)](#pageemulatemediatype)
   * [page.emulateMediaFeatures(features)](#pageemulatemediafeaturesfeatures)
   * [page.emulateMediaType(type)](#pageemulatemediatypetype)
+  * [page.emulateTimezone(timezoneId)](#pageemulatetimezonetimezoneid)
   * [page.evaluate(pageFunction[, ...args])](#pageevaluatepagefunction-args)
   * [page.evaluateHandle(pageFunction[, ...args])](#pageevaluatehandlepagefunction-args)
   * [page.evaluateOnNewDocument(pageFunction[, ...args])](#pageevaluateonnewdocumentpagefunction-args)
@@ -1350,6 +1351,10 @@ await page.evaluate(() => matchMedia('print').matches));
 // → true
 ```
 
+#### page.emulateTimezone(timezoneId)
+- `timezoneId` <?[string]> Changes the timezone of the page. See [ICU’s `metaZones.txt`](https://cs.chromium.org/chromium/src/third_party/icu/source/data/misc/metaZones.txt?rcl=faee8bc70570192d82d2978a71e2a615788597d1) for a list of supported timezone IDs. Passing `null` disables timezone emulation.
+- returns: <[Promise]>
+
 #### page.evaluate(pageFunction[, ...args])
 - `pageFunction` <[function]|[string]> Function to be evaluated in the page context
 - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`

lib/Page.js

@@ -824,6 +824,19 @@ class Page extends EventEmitter {
     }
   }
 
+  /**
+   * @param {?string} timezoneId
+   */
+  async emulateTimezone(timezoneId) {
+    try {
+      await this._client.send('Emulation.setTimezoneOverride', {timezoneId: timezoneId || ''});
+    } catch (exception) {
+      if (exception.message.includes('Invalid timezone'))
+        throw new Error(`Invalid timezone ID: ${timezoneId}`);
+      throw exception;
+    }
+  }
+
   /**
    * @param {!Puppeteer.Viewport} viewport
    */

test/emulation.spec.js

@@ -157,4 +157,31 @@ module.exports.addTests = function({testRunner, expect, puppeteer}) {
     });
   });
 
+  describe_fails_ffox('Page.emulateTimezone', function() {
+    it('should work', async({page, server}) => {
+      page.evaluate(() => {
+        globalThis.date = new Date(1479579154987);
+      });
+      await page.emulateTimezone('America/Jamaica');
+      expect(await page.evaluate(() => date.toString())).toBe('Sat Nov 19 2016 13:12:34 GMT-0500 (Eastern Standard Time)');
+
+      await page.emulateTimezone('Pacific/Honolulu');
+      expect(await page.evaluate(() => date.toString())).toBe('Sat Nov 19 2016 08:12:34 GMT-1000 (Hawaii-Aleutian Standard Time)');
+
+      await page.emulateTimezone('America/Buenos_Aires');
+      expect(await page.evaluate(() => date.toString())).toBe('Sat Nov 19 2016 15:12:34 GMT-0300 (Argentina Standard Time)');
+
+      await page.emulateTimezone('Europe/Berlin');
+      expect(await page.evaluate(() => date.toString())).toBe('Sat Nov 19 2016 19:12:34 GMT+0100 (Central European Standard Time)');
+    });
+
+    it('should throw for invalid timezone IDs', async({page, server}) => {
+      let error = null;
+      await page.emulateTimezone('Foo/Bar').catch(e => error = e);
+      expect(error.message).toBe('Invalid timezone ID: Foo/Bar');
+      await page.emulateTimezone('Baz/Qux').catch(e => error = e);
+      expect(error.message).toBe('Invalid timezone ID: Baz/Qux');
+    });
+  });
+
 };