Introduce page.emulate convenience wrapper (#231)

This patch:
- introduces Page.emulate convenience wrapper
- adds a screenshot-fullPage.js example

docs/api.md

@@ -28,6 +28,7 @@
     + [page.addScriptTag(url)](#pageaddscripttagurl)
     + [page.click(selector[, options])](#pageclickselector-options)
     + [page.close()](#pageclose)
+    + [page.emulate(options)](#pageemulateoptions)
     + [page.evaluate(pageFunction, ...args)](#pageevaluatepagefunction-args)
     + [page.evaluateOnNewDocument(pageFunction, ...args)](#pageevaluateonnewdocumentpagefunction-args)
     + [page.focus(selector)](#pagefocusselector)
@@ -334,6 +335,14 @@ Shortcut for [page.mainFrame().click(selector[, options])](#frameclickselector-o
 #### page.close()
 - returns: <[Promise]> Returns promise which resolves when page gets closed.
 
+#### page.emulate(options)
+- `options` <[Object]>
+  - `viewport` <[Object]> viewport as described in [`page.setViewport`](#pagesetviewportpath) method.
+  - `userAgent` <[string]> user agent string
+- returns: <[Promise]> Promise which resolves when emulation is performed.
+
+Emulates given device metrics and user agent.
+
 #### page.evaluate(pageFunction, ...args)
 - `pageFunction` <[function]|[string]> Function to be evaluated in browser context
 - `...args` <...[string]> Arguments to pass to  `pageFunction`

examples/pdf.js

@@ -25,7 +25,7 @@ await page.goto('https://news.ycombinator.com', {waitUntil: 'networkidle'});
 // @see https://bugs.chromium.org/p/chromium/issues/detail?id=753118
 await page.pdf({
   path: 'hn.pdf',
-  format: 'A4'
+  format: 'letter'
 });
 
 browser.close();

examples/screenshot-fullpage.js

@@ -0,0 +1,26 @@
+/**
+ * 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 {Browser} = require('puppeteer');
+const devices = require('puppeteer/DeviceDescriptors');
+const browser = new Browser();
+
+browser.newPage().then(async page => {
+  await page.emulate(devices['iPhone 6']);
+  await page.navigate('https://www.nytimes.com/');
+  await page.screenshot({path: 'fp_page.png', fullPage: true});
+  browser.close();
+});

lib/Page.js

@@ -343,6 +343,17 @@ class Page extends EventEmitter {
     return result;
   }
 
+  /**
+   * @param {!Object} options
+   * @return {!Promise}
+   */
+  async emulate(options) {
+    return Promise.all([
+      this.setViewport(options.viewport),
+      this.setUserAgent(options.userAgent)
+    ]);
+  }
+
   /**
    * @param {!Page.Viewport} viewport
    * @return {!Promise}
@@ -434,6 +445,7 @@ class Page extends EventEmitter {
       const metrics = await this._client.send('Page.getLayoutMetrics');
       const width = Math.ceil(metrics.contentSize.width);
       const height = Math.ceil(metrics.contentSize.height);
+
       // Overwrite clip for full page at all times.
       clip = { x: 0, y: 0, width, height, scale: 1 };
       const mobile = this._viewport.isMobile || false;

test/test.js

@@ -1435,6 +1435,12 @@ describe('Page', function() {
       await page.setViewport({width: 100, height: 100});
       expect(await page.evaluate(() => screen.orientation.type)).toBe('portrait-primary');
     }));
+    it('should support emulate shorthand', SX(async function() {
+      await page.goto(PREFIX + '/mobile.html');
+      await page.emulate(iPhone);
+      expect(await page.evaluate(() => window.innerWidth)).toBe(375);
+      expect(await page.evaluate(() => navigator.userAgent)).toContain('Safari');
+    }));
   });
 
   describe('Page.evaluateOnNewDocument', function() {