diff --git a/docs/api.md b/docs/api.md index ff971c33733..92cba659dc0 100644 --- a/docs/api.md +++ b/docs/api.md @@ -31,6 +31,7 @@ + [page.click(selector[, options])](#pageclickselector-options) + [page.close()](#pageclose) + [page.emulate(options)](#pageemulateoptions) + + [page.emulateMedia(mediaType)](#pageemulatemediamediatype) + [page.evaluate(pageFunction, ...args)](#pageevaluatepagefunction-args) + [page.evaluateOnNewDocument(pageFunction, ...args)](#pageevaluateonnewdocumentpagefunction-args) + [page.exposeFunction(name, puppeteerFunction)](#pageexposefunctionname-puppeteerfunction) @@ -160,7 +161,7 @@ This methods attaches Puppeteer to an existing Chromium instance. The method launches a browser instance with given arguments. The browser will be closed when the parent node.js process is closed. -> **Note** Puppeteer works best with the version of Chromium it is bundled with. There is no guarantee it will work with any other version. Use `executablePath` option with extreme caution. If Google Chrome (rather than Chromium) is preferred, a [Chrome Canary](https://www.google.com/chrome/browser/canary.html) or [Dev Channel](https://www.chromium.org/getting-involved/dev-channel) build is suggested. +> **NOTE** Puppeteer works best with the version of Chromium it is bundled with. There is no guarantee it will work with any other version. Use `executablePath` option with extreme caution. If Google Chrome (rather than Chromium) is preferred, a [Chrome Canary](https://www.google.com/chrome/browser/canary.html) or [Dev Channel](https://www.chromium.org/getting-involved/dev-channel) build is suggested. ### class: Browser @@ -237,7 +238,7 @@ Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` o Emitted when the page crashes. -> **Note** `error` event has a special meaning in Node, see [error events](https://nodejs.org/api/events.html#events_error_events) for details. +> **NOTE** `error` event has a special meaning in Node, see [error events](https://nodejs.org/api/events.html#events_error_events) for details. #### event: 'frameattached' - <[Frame]> @@ -348,6 +349,10 @@ puppeteer.launch().then(async browser => { List of all available devices is available in the source code: [DeviceDescriptors.js](https://github.com/GoogleChrome/puppeteer/blob/master/DeviceDescriptors.js). +#### page.emulateMedia(mediaType) + - `mediaType` <[string]> Changes the CSS media type of the page. The only allowed values are `'screen'`, `'media'` and `null`. Passing `null` disables media emulation. + - returns: <[Promise]> + #### page.evaluate(pageFunction, ...args) - `pageFunction` <[function]|[string]> Function to be evaluated in the page context - `...args` <...[Serializable]> Arguments to pass to `pageFunction` @@ -546,6 +551,14 @@ Page is guaranteed to have a main frame which persists during navigations. - `left` <[string]> Left margin, accepts values labeled with units. - returns: <[Promise]<[Buffer]>> Promise which resolves with PDF buffer. +`page.pdf()` generates a pdf of the page with `print` css media. To generate a pdf with `screen` media, call [page.emulateMedia('screen')](#pageemulatemediamediatype) before calling `page.pdf()`: + +```js +// Generates a PDF with 'screen' media type. +await page.emulateMedia('screen'); +await page.pdf({path: 'page.pdf'}); +``` + The `width`, `height`, and `margin` options accept values labeled with units. Unlabeled values are treated as pixels. A few examples: diff --git a/lib/Page.js b/lib/Page.js index e05d52c500b..d9f54bf1953 100644 --- a/lib/Page.js +++ b/lib/Page.js @@ -363,6 +363,15 @@ class Page extends EventEmitter { ]); } + /** + * @param {?string} mediaType + * @return {!Promise} + */ + async emulateMedia(mediaType) { + console.assert(mediaType === 'screen' || mediaType === 'print' || mediaType === null, 'Unsupported media type: ' + mediaType); + await this._client.send('Emulation.setEmulatedMedia', {media: mediaType || ''}); + } + /** * @param {!Page.Viewport} viewport * @return {!Promise} diff --git a/test/test.js b/test/test.js index 577aa70de9d..d04680b4689 100644 --- a/test/test.js +++ b/test/test.js @@ -1629,7 +1629,10 @@ 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() { + }); + + describe('Page.emulate', function() { + it('should work', SX(async function() { await page.goto(PREFIX + '/mobile.html'); await page.emulate(iPhone); expect(await page.evaluate(() => window.innerWidth)).toBe(375); @@ -1637,6 +1640,24 @@ describe('Page', function() { })); }); + describe('Page.emulateMedia', function() { + it('should work', SX(async function() { + expect(await page.evaluate(() => window.matchMedia('screen').matches)).toBe(true); + expect(await page.evaluate(() => window.matchMedia('print').matches)).toBe(false); + await page.emulateMedia('print'); + expect(await page.evaluate(() => window.matchMedia('screen').matches)).toBe(false); + expect(await page.evaluate(() => window.matchMedia('print').matches)).toBe(true); + await page.emulateMedia(null); + expect(await page.evaluate(() => window.matchMedia('screen').matches)).toBe(true); + expect(await page.evaluate(() => window.matchMedia('print').matches)).toBe(false); + })); + it('should throw in case of bad argument', SX(async function() { + let error = null; + await page.emulateMedia('bad').catch(e => error = e); + expect(error.message).toBe('Unsupported media type: bad'); + })); + }); + describe('Page.evaluateOnNewDocument', function() { it('should evaluate before anything else on the page', SX(async function() { await page.evaluateOnNewDocument(function(){