Add emulation for named devices. (#72)

This patch introduces page emulation, making it possible to emulate different devices.

README.md

@@ -95,7 +95,7 @@ However, if you're using Node 8 or higher, `async/await` make life easier:
 
 ```javascript
 browser.newPage().then(async page => {
-  await page.setViewportSize({width: 1000, height: 1000});
+  await page.setViewport({width: 1000, height: 1000});
   await page.pdf({path: 'blank.pdf'});
   browser.close();
 });

docs/api.md

@@ -27,6 +27,8 @@
   * [page.addScriptTag(url)](#pageaddscripttagurl)
   * [page.click(selector)](#pageclickselector)
   * [page.close()](#pageclose)
+  * [page.emulate(name, options)](#pageemulatename-options)
+  * [page.emulatedDevices()](#pageemulateddevices)
   * [page.evaluate(pageFunction, ...args)](#pageevaluatepagefunction-args)
   * [page.evaluateOnInitialized(pageFunction, ...args)](#pageevaluateoninitializedpagefunction-args)
   * [page.focus(selector)](#pagefocusselector)
@@ -37,19 +39,20 @@
   * [page.navigate(url, options)](#pagenavigateurl-options)
   * [page.pdf(options)](#pagepdfoptions)
   * [page.plainText()](#pageplaintext)
+  * [page.reload()](#pagereload)
   * [page.screenshot([options])](#pagescreenshotoptions)
   * [page.setContent(html)](#pagesetcontenthtml)
   * [page.setHTTPHeaders(headers)](#pagesethttpheadersheaders)
   * [page.setInPageCallback(name, callback)](#pagesetinpagecallbackname-callback)
   * [page.setRequestInterceptor(interceptor)](#pagesetrequestinterceptorinterceptor)
   * [page.setUserAgent(userAgent)](#pagesetuseragentuseragent)
-  * [page.setViewportSize(size)](#pagesetviewportsizesize)
+  * [page.setViewport(viewport)](#pagesetviewportviewport)
   * [page.title()](#pagetitle)
   * [page.type(text)](#pagetypetext)
   * [page.uploadFile(selector, ...filePaths)](#pageuploadfileselector-filepaths)
   * [page.url()](#pageurl)
   * [page.userAgent()](#pageuseragent)
-  * [page.viewportSize()](#pageviewportsize)
+  * [page.viewport()](#pageviewport)
   * [page.waitFor(selector)](#pagewaitforselector)
 - [class: Dialog](#class-dialog)
   * [dialog.accept([promptText])](#dialogacceptprompttext)
@@ -257,6 +260,15 @@ Adds a `<script></script>` tag to the page with the desired url. Alternatively,
 #### page.close()
 - returns: <[Promise]> Returns promise which resolves when page gets closed.
 
+#### page.emulate(name, options)
+- `name` <[string]> A name of the device to be emulated. Get the full list of emulated devices via `page.emulatedDevices()`.
+- `options` <[Object]> Emulation parameters which might have the following properties:
+  - `landscape` <[boolean]> Emulates device in the landscape mode, defaults to `false`.
+- returns: <[Promise]> Returns promise which resolves when device is emulated. Can reload the page if switching between mobile and desktop devices.
+
+#### page.emulatedDevices()
+- returns: <[Array]<[String]>> Returns array of device names that can be used with `page.emulate()`.
+
 #### page.evaluate(pageFunction, ...args)
 - `pageFunction` <[function]> Function to be evaluated in browser context
 - `...args` <...[string]> Arguments to pass to  `pageFunction`
@@ -354,6 +366,9 @@ The `format` options are:
 #### page.plainText()
 - returns:  <[Promise]<[string]>> Returns page's inner text.
 
+#### page.reload()
+- returns: <[Promise]<[Response]>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect.
+
 #### page.screenshot([options])
 - `options` <[Object]> Options object which might have the following properties:
     - `path` <[string]> The file path to save the image to. The screenshot type will be inferred from file extension.
@@ -423,8 +438,8 @@ browser.newPage().then(async page =>
 - `userAgent` <[string]> Specific user agent to use in this page
 - returns: <[Promise]> Promise which resolves when the user agent is set.
 
-#### page.setViewportSize(size)
+#### page.setViewport(viewport)
-- `size` <[Object]>  An object with two fields:
+- `viewport` <[Object]>  An object with two fields:
 	- `width` <[number]> Specify page's width in pixels.
 	- `height` <[number]> Specify page's height in pixels.
 - returns: <[Promise]> Promise which resolves when the dimensions are updated.
@@ -454,7 +469,7 @@ This is a shortcut for [page.mainFrame().url()](#frameurl)
 #### page.userAgent()
 - returns: <[string]> Returns user agent.
 
-#### page.viewportSize()
+#### page.viewport()
 - returns: <[Object]>  An object with two fields:
 	- `width` <[number]> Page's width in pixels.
 	- `height` <[number]> Page's height in pixels.

examples/colorwheel.js

@@ -18,7 +18,7 @@ var Browser = require('../lib/Browser');
 var browser = new Browser();
 
 browser.newPage().then(async page => {
-    await page.setViewportSize({width: 400, height: 400});
+    await page.setViewport({width: 400, height: 400});
     await page.setContent('<html><body><canvas id="surface"></canvas></body></html>');
     await page.evaluate(drawColorWheel);
     await page.screenshot({path: 'colorwheel.png'});

lib/EmulationManager.js

@@ -0,0 +1,198 @@
+/**
+ * Copyright 2017 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.
+ */
+
+const DeviceDescriptors = require('./DeviceDescriptors');
+
+class EmulationManager {
+  /**
+   * @return {!Promise<!Array<string>>}
+   */
+  static deviceNames() {
+    return Promise.resolve(DeviceDescriptors.map(entry => entry['device'].title));
+  }
+
+  /**
+   * @param {string} name
+   * @param {!Object=} options
+   * @return {!Page.Viewport}
+   */
+  static deviceViewport(name, options) {
+    options = options || {};
+    const descriptor = DeviceDescriptors.find(entry => entry['device'].title === name)['device'];
+    if (!descriptor)
+      throw new Error(`Unable to emulate ${name}, no such device metrics in the library.`);
+    const device = EmulationManager.loadFromJSONV1(descriptor);
+    const viewport = options.landscape ? device.horizontal : device.vertical;
+    return {
+      width: viewport.width,
+      height: viewport.height,
+      deviceScaleFactor: device.deviceScaleFactor,
+      isMobile: device.capabilities.includes('mobile'),
+      hasMobile: device.capabilities.includes('touch'),
+      isLandscape: options.landscape || false
+    };
+  }
+
+  /**
+   * @param {string} name
+   */
+  static deviceUserAgent(name, options) {
+    const descriptor = DeviceDescriptors.find(entry => entry['device'].title === name)['device'];
+    if (!descriptor)
+      throw new Error(`Unable to emulate ${name}, no such device metrics in the library.`);
+    const device = EmulationManager.loadFromJSONV1(descriptor);
+    return device.userAgent;
+  }
+
+  /**
+   * @param {!Connection} client
+   * @param {!Page.Viewport} viewport
+   * @return {Promise<boolean>}
+   */
+  static async emulateViewport(client, viewport) {
+    const mobile = viewport.isMobile || false;
+    const landscape = viewport.isLandscape || false;
+    const width = viewport.width;
+    const height = viewport.height;
+    const deviceScaleFactor = viewport.deviceScaleFactor || 1;
+    const screenOrientation = landscape ? { angle: 90, type: 'landscapePrimary' } : { angle: 0, type: 'portraitPrimary' };
+
+    await Promise.all([
+      client.send('Emulation.setDeviceMetricsOverride', { mobile, width, height, deviceScaleFactor, screenOrientation }),
+      client.send('Emulation.setTouchEmulationEnabled', {
+        enabled: viewport.hasTouch || false,
+        configuration: viewport.isMobile ? 'mobile' : 'desktop'
+      })
+    ]);
+
+    let reloadNeeded = false;
+    if (viewport.hasTouch && !client[EmulationManager._touchScriptId]) {
+      const source = `(${injectedTouchEventsFunction})()`;
+      client[EmulationManager._touchScriptId] = await client.send('Runtime.addScriptToEvaluateOnNewDocument', { source });
+      reloadNeeded = true;
+    }
+
+    if (!viewport.hasTouch && client[EmulationManager._touchScriptId]) {
+      client[EmulationManager._touchScriptId] = null;
+      await client.send('Runtime.removeScriptToEvaluateOnNewDocument', EmulationManager._emulatingTouch);
+      reloadNeeded = true;
+    }
+
+    if (client[EmulationManager._emulatingMobile] !== mobile)
+      reloadNeeded = true;
+    client[EmulationManager._emulatingMobile] = mobile;
+
+    function injectedTouchEventsFunction() {
+      const touchEvents = ['ontouchstart', 'ontouchend', 'ontouchmove', 'ontouchcancel'];
+      const recepients = [window.__proto__, document.__proto__];
+      for (let i = 0; i < touchEvents.length; ++i) {
+        for (let j = 0; j < recepients.length; ++j) {
+          if (!(touchEvents[i] in recepients[j])) {
+            Object.defineProperty(recepients[j], touchEvents[i], {
+              value: null, writable: true, configurable: true, enumerable: true
+            });
+          }
+        }
+      }
+    }
+    return reloadNeeded;
+  }
+
+  /**
+   * @param {*} json
+   * @return {?Object}
+   */
+  static loadFromJSONV1(json) {
+    /**
+     * @param {*} object
+     * @param {string} key
+     * @param {string} type
+     * @param {*=} defaultValue
+     * @return {*}
+     */
+    function parseValue(object, key, type, defaultValue) {
+      if (typeof object !== 'object' || object === null || !object.hasOwnProperty(key)) {
+        if (typeof defaultValue !== 'undefined')
+          return defaultValue;
+        throw new Error('Emulated device is missing required property \'' + key + '\'');
+      }
+      const value = object[key];
+      if (typeof value !== type || value === null)
+        throw new Error('Emulated device property \'' + key + '\' has wrong type \'' + typeof value + '\'');
+      return value;
+    }
+
+    /**
+     * @param {*} object
+     * @param {string} key
+     * @return {number}
+     */
+    function parseIntValue(object, key) {
+      const value = /** @type {number} */ (parseValue(object, key, 'number'));
+      if (value !== Math.abs(value))
+        throw new Error('Emulated device value \'' + key + '\' must be integer');
+      return value;
+    }
+
+    /**
+     * @param {*} json
+     * @return {!{width: number, height: number}}
+     */
+    function parseOrientation(json) {
+      const result = {};
+      const minDeviceSize = 50;
+      const maxDeviceSize = 9999;
+      result.width = parseIntValue(json, 'width');
+      if (result.width < 0 || result.width > maxDeviceSize ||
+          result.width < minDeviceSize)
+        throw new Error('Emulated device has wrong width: ' + result.width);
+
+      result.height = parseIntValue(json, 'height');
+      if (result.height < 0 || result.height > maxDeviceSize ||
+          result.height < minDeviceSize)
+        throw new Error('Emulated device has wrong height: ' + result.height);
+
+      return /** @type {!{width: number, height: number}} */ (result);
+    }
+
+    const result = {};
+    result.type = /** @type {string} */ (parseValue(json, 'type', 'string'));
+    result.userAgent = /** @type {string} */ (parseValue(json, 'user-agent', 'string'));
+
+    const capabilities = parseValue(json, 'capabilities', 'object', []);
+    if (!Array.isArray(capabilities))
+      throw new Error('Emulated device capabilities must be an array');
+    result.capabilities = [];
+    for (let i = 0; i < capabilities.length; ++i) {
+      if (typeof capabilities[i] !== 'string')
+        throw new Error('Emulated device capability must be a string');
+      result.capabilities.push(capabilities[i]);
+    }
+
+    result.deviceScaleFactor = /** @type {number} */ (parseValue(json['screen'], 'device-pixel-ratio', 'number'));
+    if (result.deviceScaleFactor < 0 || result.deviceScaleFactor > 100)
+      throw new Error('Emulated device has wrong deviceScaleFactor: ' + result.deviceScaleFactor);
+
+    result.vertical = parseOrientation(parseValue(json['screen'], 'vertical', 'object'));
+    result.horizontal = parseOrientation(parseValue(json['screen'], 'horizontal', 'object'));
+    return result;
+  }
+}
+
+EmulationManager._touchScriptId = Symbol('emulatingTouchScriptId');
+EmulationManager._emulatingMobile = Symbol('emulatingMobile');
+
+module.exports = EmulationManager;

lib/Page.js

@@ -20,6 +20,7 @@ let mime = require('mime');
 let NetworkManager = require('./NetworkManager');
 let Navigator = require('./Navigator');
 let Dialog = require('./Dialog');
+let EmulationManager = require('./EmulationManager');
 let FrameManager = require('./FrameManager');
 let helper = require('./helper');
 
@@ -41,7 +42,7 @@ class Page extends EventEmitter {
     let networkManager = new NetworkManager(client, userAgent);
     let page = new Page(client, frameManager, networkManager);
     // Initialize default page size.
-    await page.setViewportSize({width: 400, height: 300});
+    await page.setViewport({width: 400, height: 300});
     return page;
   }
 
@@ -257,45 +258,67 @@ class Page extends EventEmitter {
    */
   async navigate(url, options) {
     const referrer = this._networkManager.httpHeaders()['referer'];
+    this._navigator = new Navigator(this._client, url, referrer, options);
+    return this.reload();
+  }
+
+  /**
+   * @return {!Promise<!Response>}
+   */
+  async reload() {
+    if (!this._navigator)
+      return;
     /** @type {!Map<string, !Response>} */
     const responses = new Map();
     const onResponse = response => responses.set(response.url, response);
-    const navigator = new Navigator(this._client, url, referrer, options);
     this._networkManager.on(NetworkManager.Events.Response, onResponse);
     try {
-      await navigator.navigate();
+      await this._navigator.navigate();
     } finally {
       this._networkManager.removeListener(NetworkManager.Events.Response, onResponse);
     }
     const response = responses.get(this.mainFrame().url());
     console.assert(response);
+
+    // Await for a single raf rountrip to ensure basic rasterization is complete.
+    await this.evaluate(() => new Promise(fulfill => requestAnimationFrame(fulfill)));
     return response;
   }
 
   /**
-   * @param {!{width: number, height: number}} size
+   * @param {!Page.Viewport} viewport
    * @return {!Promise}
    */
-  setViewportSize(size) {
+  async setViewport(viewport) {
-    this._viewportSize = size;
+    const needsReload = await EmulationManager.emulateViewport(this._client, viewport);
-    return this._resetDeviceEmulation();
+    this._viewport = viewport;
+    if (needsReload)
+      await this.reload();
   }
 
   /**
-   * @return {!{width: number, height: number}}
+   * @return {!Page.Viewport}
    */
-  viewportSize() {
+  viewport() {
-    return this._viewportSize;
+    return this._viewport;
   }
 
-  _resetDeviceEmulation() {
+  /**
-    const width = this._viewportSize.width;
+   * @return {!Promise<!Array<string>>}
-    const height = this._viewportSize.height;
+   */
-    const deviceScaleFactor = 1;
+  static emulatedDevices() {
-    const mobile = false;
+    return EmulationManager.deviceNames(name);
-    const screenOrientation = { angle: 0, type: 'portraitPrimary' };
+  }
+
+  /**
+   * @param {string} name
+   * @param {!Object=} options
+   * @return {!Promise}
+   */
+  emulate(name, options) {
     return Promise.all([
-      this._client.send('Emulation.setDeviceMetricsOverride', { mobile, width, height, deviceScaleFactor, screenOrientation }),
+      this.setUserAgent(EmulationManager.deviceUserAgent(name)),
+      this.setViewport(EmulationManager.deviceViewport(name, options))
     ]);
   }
 
@@ -365,13 +388,13 @@ class Page extends EventEmitter {
    */
   async _screenshotTask(format, options) {
     if (options.fullPage) {
-      let metrics = await this._client.send('Page.getLayoutMetrics');
+      const metrics = await this._client.send('Page.getLayoutMetrics');
       const width = Math.ceil(metrics.contentSize.width);
       const height = Math.ceil(metrics.contentSize.height);
       await this._client.send('Emulation.resetPageScaleFactor');
-      const mobile = false;
+      const mobile = this._viewport.isMobile || false;
-      const deviceScaleFactor = 1;
+      const deviceScaleFactor = this._viewport.deviceScaleFactor || 1;
-      const landscape = false;
+      const landscape = this._viewport.isLandscape || false;
       const screenOrientation = landscape ? { angle: 90, type: 'landscapePrimary' } : { angle: 0, type: 'portraitPrimary' };
       await this._client.send('Emulation.setDeviceMetricsOverride', { mobile, width, height, deviceScaleFactor, screenOrientation });
     }
@@ -382,7 +405,7 @@ class Page extends EventEmitter {
     let result = await this._client.send('Page.captureScreenshot', { format, quality: options.quality, clip });
 
     if (options.fullPage)
-      await this.setViewportSize(this.viewportSize());
+      await this.setViewport(this._viewport);
 
     let buffer = new Buffer(result.data, 'base64');
     if (options.path)
@@ -646,4 +669,7 @@ Page.Events = {
   Load: 'load',
 };
 
+/** @typedef {{width: number, height: number, deviceScaleFactor: number|undefined, isMobile: boolean|undefined, isLandscape: boolean, hasTouch: boolean|undefined}} */
+Page.Viewport;
+
 module.exports = Page;

phantom_shim/WebPage.js

@@ -37,7 +37,7 @@ class WebPage {
     if (options.settings.userAgent)
       this.settings.userAgent = options.settings.userAgent;
     if (options.viewportSize)
-      await(this._page.setViewportSize(options.viewportSize));
+      await(this._page.setViewport(options.viewportSize));
 
     this.loading = false;
     this.loadingProgress = 0;
@@ -214,7 +214,7 @@ class WebPage {
      * @return {!{width: number, height: number}}
      */
   get viewportSize() {
-    return this._page.viewportSize();
+    return this._page.viewport();
   }
 
   /**
@@ -380,7 +380,7 @@ class WebPage {
      * @param {!{width: number, height: number}} options
      */
   set viewportSize(options) {
-    await(this._page.setViewportSize(options));
+    await(this._page.setViewport(options));
   }
 
   /**

test/test.js

@@ -507,13 +507,13 @@ describe('Puppeteer', function() {
 
   describe('Page.screenshot', function() {
     it('should work', SX(async function() {
-      await page.setViewportSize({width: 500, height: 500});
+      await page.setViewport({width: 500, height: 500});
       await page.navigate(PREFIX + '/grid.html');
       let screenshot = await page.screenshot();
       expect(screenshot).toBeGolden('screenshot-sanity.png');
     }));
     it('should clip rect', SX(async function() {
-      await page.setViewportSize({width: 500, height: 500});
+      await page.setViewport({width: 500, height: 500});
       await page.navigate(PREFIX + '/grid.html');
       let screenshot = await page.screenshot({
         clip: {
@@ -526,7 +526,7 @@ describe('Puppeteer', function() {
       expect(screenshot).toBeGolden('screenshot-clip-rect.png');
     }));
     it('should work for offscreen clip', SX(async function() {
-      await page.setViewportSize({width: 500, height: 500});
+      await page.setViewport({width: 500, height: 500});
       await page.navigate(PREFIX + '/grid.html');
       let screenshot = await page.screenshot({
         clip: {
@@ -539,7 +539,7 @@ describe('Puppeteer', function() {
       expect(screenshot).toBeGolden('screenshot-offscreen-clip.png');
     }));
     it('should run in parallel', SX(async function() {
-      await page.setViewportSize({width: 500, height: 500});
+      await page.setViewport({width: 500, height: 500});
       await page.navigate(PREFIX + '/grid.html');
       let promises = [];
       for (let i = 0; i < 3; ++i) {
@@ -556,7 +556,7 @@ describe('Puppeteer', function() {
       expect(screenshot).toBeGolden('screenshot-parallel-calls.png');
     }));
     it('should take fullPage screenshots', SX(async function() {
-      await page.setViewportSize({width: 500, height: 500});
+      await page.setViewport({width: 500, height: 500});
       await page.navigate(PREFIX + '/grid.html');
       let screenshot = await page.screenshot({
         fullPage: true
@@ -811,11 +811,11 @@ describe('Puppeteer', function() {
     }));
   });
 
-  describe('Page.viewportSize', function() {
+  describe('Page.viewport', function() {
     it('should get the proper viewport size', SX(async function() {
-      expect(page.viewportSize()).toEqual({width: 400, height: 300});
+      expect(page.viewport()).toEqual({width: 400, height: 300});
-      await page.setViewportSize({width: 123, height: 456});
+      await page.setViewport({width: 123, height: 456});
-      expect(page.viewportSize()).toEqual({width: 123, height: 456});
+      expect(page.viewport()).toEqual({width: 123, height: 456});
     }));
   });
 

utils/doclint/lint.js

@@ -8,6 +8,7 @@ const PROJECT_DIR = path.join(__dirname, '..', '..');
 
 let EXCLUDE_CLASSES = new Set([
   'Connection',
+  'EmulationManager',
   'FrameManager',
   'Helper',
   'Navigator',