From 175963182e77423fd9311d4bd5dc9c288f35ad56 Mon Sep 17 00:00:00 2001 From: Andrey Lushnikov Date: Sat, 17 Jun 2017 14:27:51 -0700 Subject: [PATCH] Implement FrameManager This patch implements FrameManager which is responsible for maintaining the frame tree. FrameManager is quite basic: it sends FrameAttached, FrameDetached and FrameNavigated events, and can report mainFrame and all frames. The next step would be moving certain Page API's to the Frame. For example, such method as Page.evaluate, Page.navigate and others should be available on Frame object as well. References #4 --- lib/FrameManager.js | 245 ++++++++++++++++++++++++++ lib/Page.js | 29 ++- package-lock.json | 6 + package.json | 3 +- test/assets/frames/frame.html | 3 + test/assets/frames/nested-frames.html | 22 +++ test/assets/frames/script.js | 1 + test/assets/frames/style.css | 3 + test/assets/frames/two-frames.html | 13 ++ test/diffstyle.css | 13 ++ test/frame-utils.js | 62 +++++++ test/golden/nested-frames.txt | 5 + test/test.js | 214 ++++++++++++++++------ 13 files changed, 563 insertions(+), 56 deletions(-) create mode 100644 lib/FrameManager.js create mode 100644 test/assets/frames/frame.html create mode 100644 test/assets/frames/nested-frames.html create mode 100644 test/assets/frames/script.js create mode 100644 test/assets/frames/style.css create mode 100644 test/assets/frames/two-frames.html create mode 100644 test/diffstyle.css create mode 100644 test/frame-utils.js create mode 100644 test/golden/nested-frames.txt diff --git a/lib/FrameManager.js b/lib/FrameManager.js new file mode 100644 index 00000000000..6e0e82755c0 --- /dev/null +++ b/lib/FrameManager.js @@ -0,0 +1,245 @@ +/** + * 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. + */ + +var EventEmitter = require('events'); + +class FrameManager extends EventEmitter { + /** + * @param {!Connection} client + * @return {!FrameManager} + */ + static async create(client) { + var mainFramePayload = await client.send('Page.getResourceTree'); + return new FrameManager(client, mainFramePayload.frameTree); + } + + /** + * @param {!Connection} client + * @param {!Object} frameTree + */ + constructor(client, frameTree) { + super(); + this._client = client; + /** @type {!Map} */ + this._frames = new Map(); + this._mainFrame = this._addFramesRecursively(null, frameTree); + + this._client.on('Page.frameAttached', event => this._frameAttached(event.frameId, event.parentFrameId)); + this._client.on('Page.frameNavigated', event => this._frameNavigated(event.frame)); + this._client.on('Page.frameDetached', event => this._frameDetached(event.frameId)); + } + + /** + * @return {!Frame} + */ + mainFrame() { + return this._mainFrame; + } + + /** + * @return {!Array} + */ + frames() { + return Array.from(this._frames.values()); + } + + /** + * @param {string} frameId + * @param {?string} parentFrameId + * @return {?Frame} + */ + _frameAttached(frameId, parentFrameId) { + if (this._frames.has(frameId)) + return; + + if (!parentFrameId) { + // Navigation to the new backend process. + this._navigateFrame(this._mainFrame, frameId, null); + return; + } + var parentFrame = this._frames.get(parentFrameId); + var frame = new Frame(parentFrame, frameId, null); + this._frames.set(frame._id, frame); + this.emit(FrameManager.Events.FrameAttached, frame); + } + + /** + * @param {!Object} framePayload + */ + _frameNavigated(framePayload) { + var frame = this._frames.get(framePayload.id); + if (!frame) { + // Simulate missed "frameAttached" for a main frame navigation to the new backend process. + console.assert(!framePayload.parentId, 'Main frame shouldn\'t have parent frame id.'); + frame = this._mainFrame; + } + this._navigateFrame(frame, framePayload.id, framePayload); + } + + /** + * @param {string} frameId + */ + _frameDetached(frameId) { + var frame = this._frames.get(frameId); + if (frame) + this._removeFramesRecursively(frame); + } + + /** + * @param {!Frame} frame + * @param {string} newFrameId + * @param {?Object} newFramePayload + */ + _navigateFrame(frame, newFrameId, newFramePayload) { + // Detach all child frames first. + for (var child of frame.childFrames()) + this._removeFramesRecursively(child); + this._frames.delete(frame._id, frame); + frame._id = newFrameId; + frame._adoptPayload(newFramePayload); + this._frames.set(newFrameId, frame); + this.emit(FrameManager.Events.FrameNavigated, frame); + } + + /** + * @param {?Frame} parentFrame + * @param {!Object} frameTreePayload + * @return {!Frame} + */ + _addFramesRecursively(parentFrame, frameTreePayload) { + var framePayload = frameTreePayload.frame; + var frame = new Frame(parentFrame, framePayload.id, framePayload); + this._frames.set(frame._id, frame); + + for (var i = 0; frameTreePayload.childFrames && i < frameTreePayload.childFrames.length; ++i) + this._addFramesRecursively(frame, frameTreePayload.childFrames[i]); + return frame; + } + + /** + * @param {!Frame} frame + */ + _removeFramesRecursively(frame) { + for (var child of frame.childFrames()) + this._removeFramesRecursively(child); + frame._detach(); + this._frames.delete(frame._id); + this.emit(FrameManager.Events.FrameDetached, frame); + } +} + +/** @enum {string} */ +FrameManager.Events = { + FrameAttached: 'frameattached', + FrameNavigated: 'framenavigated', + FrameDetached: 'framedetached' +}; + +/** + * @unrestricted + */ +class Frame { + /** + * @param {?Frame} parentFrame + * @param {string} frameId + * @param {?Object} payload + */ + constructor(parentFrame, frameId, payload) { + this._parentFrame = parentFrame; + this._url = ''; + this._id = frameId; + this._adoptPayload(payload); + + /** @type {!Set} */ + this._childFrames = new Set(); + if (this._parentFrame) + this._parentFrame._childFrames.add(this); + } + + /** + * @return {string} + */ + name() { + return this._name || ''; + } + + /** + * @return {string} + */ + url() { + return this._url; + } + + /** + * @return {string} + */ + securityOrigin() { + return this._securityOrigin; + } + + /** + * @return {?Frame} + */ + parentFrame() { + return this._parentFrame; + } + + /** + * @return {!Array.} + */ + childFrames() { + return Array.from(this._childFrames); + } + + /** + * @return {boolean} + */ + isMainFrame() { + return !this._detached && !this._parentFrame; + } + + /** + * @return {boolean} + */ + isDetached() { + return this._detached; + } + + /** + * @param {?Object} framePayload + */ + _adoptPayload(framePayload) { + framePayload = framePayload || { + name: '', + url: '', + securityOrigin: '', + mimeType: '' + }; + this._name = framePayload.name; + this._url = framePayload.url; + this._securityOrigin = framePayload.securityOrigin; + this._mimeType = framePayload.mimeType; + } + + _detach() { + this._detached = true; + if (this._parentFrame) + this._parentFrame._childFrames.delete(this); + this._parentFrame = null; + } +} + +module.exports = FrameManager; diff --git a/lib/Page.js b/lib/Page.js index daecd4f8026..c3763aee907 100644 --- a/lib/Page.js +++ b/lib/Page.js @@ -20,6 +20,7 @@ var helpers = require('./helpers'); var mime = require('mime'); var Request = require('./Request'); var Dialog = require('./Dialog'); +var FrameManager = require('./FrameManager'); class Page extends EventEmitter { /** @@ -35,7 +36,8 @@ class Page extends EventEmitter { ]); var expression = helpers.evaluationString(() => window.devicePixelRatio, []); var {result:{value: screenDPI}} = await client.send('Runtime.evaluate', { expression, returnByValue: true }); - var page = new Page(client, screenDPI); + var frameManager = await FrameManager.create(client); + var page = new Page(client, frameManager, screenDPI); // Initialize default page size. await page.setViewportSize({width: 400, height: 300}); return page; @@ -43,11 +45,13 @@ class Page extends EventEmitter { /** * @param {!Connection} client + * @param {!FrameManager} frameManager * @param {number} screenDPI */ - constructor(client, screenDPI) { + constructor(client, frameManager, screenDPI) { super(); this._client = client; + this._frameManager = frameManager; this._screenDPI = screenDPI; this._extraHeaders = {}; /** @type {!Map} */ @@ -57,6 +61,10 @@ class Page extends EventEmitter { this._screenshotTaskChain = Promise.resolve(); + this._frameManager.on(FrameManager.Events.FrameAttached, event => this.emit(Page.Events.FrameAttached, event)); + this._frameManager.on(FrameManager.Events.FrameDetached, event => this.emit(Page.Events.FrameDetached, event)); + this._frameManager.on(FrameManager.Events.FrameNavigated, event => this.emit(Page.Events.FrameNavigated, event)); + client.on('Network.responseReceived', event => this.emit(Page.Events.ResponseReceived, event.response)); client.on('Network.loadingFailed', event => this.emit(Page.Events.ResourceLoadingFailed, event)); client.on('Network.requestIntercepted', event => this._onRequestIntercepted(event)); @@ -65,6 +73,20 @@ class Page extends EventEmitter { client.on('Runtime.exceptionThrown', exception => this._handleException(exception.exceptionDetails)); } + /** + * @return {!Frame} + */ + mainFrame() { + return this._frameManager.mainFrame(); + } + + /** + * @return {!Array} + */ + frames() { + return this._frameManager.frames(); + } + /** * @param {?function(!Request)} interceptor */ @@ -583,6 +605,9 @@ Page.Events = { Error: 'error', ResourceLoadingFailed: 'resourceloadingfailed', ResponseReceived: 'responsereceived', + FrameAttached: 'frameattached', + FrameDetached: 'framedetached', + FrameNavigated: 'framenavigated', }; module.exports = Page; diff --git a/package-lock.json b/package-lock.json index 0f7e40fcce6..ebdaf885b93 100644 --- a/package-lock.json +++ b/package-lock.json @@ -165,6 +165,12 @@ "version": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.0.2.tgz", "integrity": "sha1-sp4fThEl+pehA4K4pTNze3SR4Xk=" }, + "text-diff": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/text-diff/-/text-diff-1.0.1.tgz", + "integrity": "sha1-bBBZBUNeM3hXN1ydL2ymPkU/9WU=", + "dev": true + }, "typedarray": { "version": "https://registry.npmjs.org/typedarray/-/typedarray-0.0.6.tgz", "integrity": "sha1-hnrHTjhkGHsdPUfZlqeOxciDB3c=" diff --git a/package.json b/package.json index 50977c27827..2a704d8d47e 100644 --- a/package.json +++ b/package.json @@ -32,6 +32,7 @@ "minimist": "^1.2.0", "ncp": "^2.0.0", "pixelmatch": "^4.0.2", - "pngjs": "^3.2.0" + "pngjs": "^3.2.0", + "text-diff": "^1.0.1" } } diff --git a/test/assets/frames/frame.html b/test/assets/frames/frame.html new file mode 100644 index 00000000000..e6d4a2377a8 --- /dev/null +++ b/test/assets/frames/frame.html @@ -0,0 +1,3 @@ + + +
Hi, I'm frame
diff --git a/test/assets/frames/nested-frames.html b/test/assets/frames/nested-frames.html new file mode 100644 index 00000000000..e5fdb751feb --- /dev/null +++ b/test/assets/frames/nested-frames.html @@ -0,0 +1,22 @@ + + + + diff --git a/test/assets/frames/script.js b/test/assets/frames/script.js new file mode 100644 index 00000000000..be22256d16b --- /dev/null +++ b/test/assets/frames/script.js @@ -0,0 +1 @@ +console.log('Cheers!'); diff --git a/test/assets/frames/style.css b/test/assets/frames/style.css new file mode 100644 index 00000000000..5b5436e8740 --- /dev/null +++ b/test/assets/frames/style.css @@ -0,0 +1,3 @@ +div { + color: blue; +} diff --git a/test/assets/frames/two-frames.html b/test/assets/frames/two-frames.html new file mode 100644 index 00000000000..46a50f3f643 --- /dev/null +++ b/test/assets/frames/two-frames.html @@ -0,0 +1,13 @@ + + + diff --git a/test/diffstyle.css b/test/diffstyle.css new file mode 100644 index 00000000000..c58f0e90a6a --- /dev/null +++ b/test/diffstyle.css @@ -0,0 +1,13 @@ +body { + font-family: monospace; + white-space: pre; +} + +ins { + background-color: #9cffa0; + text-decoration: none; +} + +del { + background-color: #ff9e9e; +} diff --git a/test/frame-utils.js b/test/frame-utils.js new file mode 100644 index 00000000000..148f7748573 --- /dev/null +++ b/test/frame-utils.js @@ -0,0 +1,62 @@ +var utils = module.exports = { + /** + * @param {!Page} page + * @param {string} frameId + * @param {string} url + * @return {!Promise} + */ + attachFrame: async function(page, frameId, url) { + await page.evaluate(attachFrame, frameId, url); + + function attachFrame(frameId, url) { + var frame = document.createElement('iframe'); + frame.src = url; + frame.id = frameId; + document.body.appendChild(frame); + return new Promise(x => frame.onload = x); + } + }, + + /** + * @param {!Page} page + * @param {string} frameId + * @return {!Promise} + */ + detachFrame: async function(page, frameId) { + await page.evaluate(detachFrame, frameId); + + function detachFrame(frameId) { + var frame = document.getElementById(frameId); + frame.remove(); + } + }, + + /** + * @param {!Page} page + * @param {string} frameId + * @param {string} url + * @return {!Promise} + */ + navigateFrame: async function(page, frameId, url) { + await page.evaluate(navigateFrame, frameId, url); + + function navigateFrame(frameId, url) { + var frame = document.getElementById(frameId); + frame.src = url; + return new Promise(x => frame.onload = x); + } + }, + + /** + * @param {!Frame} frame + * @param {string=} indentation + * @return {string} + */ + dumpFrames: function(frame, indentation) { + indentation = indentation || ''; + var result = indentation + frame.url(); + for (var child of frame.childFrames()) + result += '\n' + utils.dumpFrames(child, ' ' + indentation); + return result; + }, +}; diff --git a/test/golden/nested-frames.txt b/test/golden/nested-frames.txt new file mode 100644 index 00000000000..008d26ba1fa --- /dev/null +++ b/test/golden/nested-frames.txt @@ -0,0 +1,5 @@ +http://localhost:8907/frames/nested-frames.html + http://localhost:8907/frames/two-frames.html + http://localhost:8907/frames/frame.html + http://localhost:8907/frames/frame.html + http://localhost:8907/frames/frame.html \ No newline at end of file diff --git a/test/test.js b/test/test.js index 9e39a037ef5..0e4ec67fece 100644 --- a/test/test.js +++ b/test/test.js @@ -20,7 +20,9 @@ var rm = require('rimraf').sync; var Browser = require('../lib/Browser'); var StaticServer = require('./StaticServer'); var PNG = require('pngjs').PNG; +var mime = require('mime'); var pixelmatch = require('pixelmatch'); +var Diff = require('text-diff'); var PORT = 8907; var STATIC_PREFIX = 'http://localhost:' + PORT; @@ -268,85 +270,191 @@ describe('Puppeteer', function() { expect(screenshot).toBeGolden('screenshot-grid-fullpage.png'); })); }); + + describe('Frame Management', function() { + var FrameUtils = require('./frame-utils'); + it('should handle nested frames', SX(async function() { + await page.navigate(STATIC_PREFIX + '/frames/nested-frames.html'); + expect(FrameUtils.dumpFrames(page.mainFrame())).toBeGolden('nested-frames.txt'); + })); + it('should send events when frames are manipulated dynamically', SX(async function() { + await page.navigate(EMPTY_PAGE); + // validate frameattached events + var attachedFrames = []; + page.on('frameattached', frame => attachedFrames.push(frame)); + await FrameUtils.attachFrame(page, 'frame1', './assets/frame.html'); + expect(attachedFrames.length).toBe(1); + expect(attachedFrames[0].url()).toContain('/assets/frame.html'); + + // validate framenavigated events + var navigatedFrames = []; + page.on('framenavigated', frame => navigatedFrames.push(frame)); + await FrameUtils.navigateFrame(page, 'frame1', './empty.html'); + expect(navigatedFrames.length).toBe(1); + expect(navigatedFrames[0].url()).toContain('/empty.html'); + + // validate framedetached events + var detachedFrames = []; + page.on('framedetached', frame => detachedFrames.push(frame)); + await FrameUtils.detachFrame(page, 'frame1'); + expect(detachedFrames.length).toBe(1); + expect(detachedFrames[0].isDetached()).toBe(true); + })); + it('should persist mainFrame on cross-process navigation', SX(async function() { + await page.navigate(EMPTY_PAGE); + var mainFrame = page.mainFrame(); + await page.navigate('http://127.0.0.1:' + PORT + '/empty.html'); + expect(page.mainFrame() === mainFrame).toBeTruthy(); + })); + it('should not send attach/detach events for main frame', SX(async function() { + var hasEvents = false; + page.on('frameattached', frame => hasEvents = true); + page.on('framedetached', frame => hasEvents = true); + await page.navigate(EMPTY_PAGE); + expect(hasEvents).toBe(false); + })); + it('should detach child frames on navigation', SX(async function() { + var attachedFrames = []; + var detachedFrames = []; + var navigatedFrames = []; + page.on('frameattached', frame => attachedFrames.push(frame)); + page.on('framedetached', frame => detachedFrames.push(frame)); + page.on('framenavigated', frame => navigatedFrames.push(frame)); + await page.navigate(STATIC_PREFIX + '/frames/nested-frames.html'); + expect(attachedFrames.length).toBe(4); + expect(detachedFrames.length).toBe(0); + expect(navigatedFrames.length).toBe(5); + + var attachedFrames = []; + var detachedFrames = []; + var navigatedFrames = []; + await page.navigate(EMPTY_PAGE); + expect(attachedFrames.length).toBe(0); + expect(detachedFrames.length).toBe(4); + expect(navigatedFrames.length).toBe(1); + })); + }); }); -var customMatchers = { - toBeGolden: function(util, customEqualityTesters) { - return { - compare: function(actual, expected) { - return compareImageToGolden(actual, expected); - } - }; - } +var GoldenComparators = { + 'image/png': compareImages, + 'text/plain': compareText }; /** - * @param {?Buffer} imageBuffer - * @param {string} goldenName - * @return {!{pass: boolean, message: (undefined|string)}} + * @param {?Object} actualBuffer + * @param {!Buffer} expectedBuffer + * @return {?{diff: (!Object:undefined), errorMessage: (string|undefined)}} */ -function compareImageToGolden(imageBuffer, goldenName) { - if (!imageBuffer || !(imageBuffer instanceof Buffer)) { - return { - pass: false, - message: 'Test did not return Buffer with image.' - }; - } - var expectedPath = path.join(GOLDEN_DIR, goldenName); - var actualPath = path.join(OUTPUT_DIR, goldenName); - var diffPath = addSuffix(path.join(OUTPUT_DIR, goldenName), '-diff'); - var helpMessage = 'Output is saved in ' + path.relative(PROJECT_DIR, OUTPUT_DIR); +function compareImages(actualBuffer, expectedBuffer) { + if (!actualBuffer || !(actualBuffer instanceof Buffer)) + return { errorMessage: 'Actual result should be Buffer.' }; - if (!fs.existsSync(expectedPath)) { - ensureOutputDir(); - fs.writeFileSync(actualPath, imageBuffer); - return { - pass: false, - message: goldenName + ' is missing in golden results. ' + helpMessage - }; - } - var actual = PNG.sync.read(imageBuffer); - var expected = PNG.sync.read(fs.readFileSync(expectedPath)); + var actual = PNG.sync.read(actualBuffer); + var expected = PNG.sync.read(expectedBuffer); if (expected.width !== actual.width || expected.height !== actual.height) { - ensureOutputDir(); - fs.writeFileSync(actualPath, imageBuffer); - var message = `Sizes differ: expected image ${expected.width}px X ${expected.height}px, but got ${actual.width}px X ${actual.height}px. `; return { - pass: false, - message: message + helpMessage + errorMessage: `Sizes differ: expected image ${expected.width}px X ${expected.height}px, but got ${actual.width}px X ${actual.height}px. ` }; } var diff = new PNG({width: expected.width, height: expected.height}); var count = pixelmatch(expected.data, actual.data, diff.data, expected.width, expected.height, {threshold: 0.1}); - if (count > 0) { - ensureOutputDir(); - fs.writeFileSync(actualPath, imageBuffer); - fs.writeFileSync(diffPath, PNG.sync.write(diff)); - return { - pass: false, - message: goldenName + ' mismatch! ' + helpMessage - }; - } + return count > 0 ? { diff: PNG.sync.write(diff) } : null; +} + +/** + * @param {?Object} actual + * @param {!Buffer} expectedBuffer + * @return {?{diff: (!Object:undefined), errorMessage: (string|undefined)}} + */ +function compareText(actual, expectedBuffer) { + if (typeof actual !== 'string') + return { errorMessage: 'Actual result should be string' }; + var expected = expectedBuffer.toString('utf-8'); + if (expected === actual) + return null; + var diff = new Diff(); + var result = diff.main(expected, actual); + diff.cleanupSemantic(result); + var html = diff.prettyHtml(result); + var diffStylePath = path.join(__dirname, 'diffstyle.css'); + html = `` + html; return { - pass: true + diff: html, + diffExtension: '.html' }; } -function ensureOutputDir() { - if (!fs.existsSync(OUTPUT_DIR)) - fs.mkdirSync(OUTPUT_DIR); -} +var customMatchers = { + toBeGolden: function(util, customEqualityTesters) { + return { + /** + * @param {?Object} actual + * @param {string} goldenName + * @return {!{pass: boolean, message: (undefined|string)}} + */ + compare: function(actual, goldenName) { + var expectedPath = path.join(GOLDEN_DIR, goldenName); + var actualPath = path.join(OUTPUT_DIR, goldenName); + + var messageSuffix = 'Output is saved in ' + path.relative(PROJECT_DIR, OUTPUT_DIR); + + if (!fs.existsSync(expectedPath)) { + ensureOutputDir(); + fs.writeFileSync(actualPath, actual); + return { + pass: false, + message: goldenName + ' is missing in golden results. ' + messageSuffix + }; + } + var expected = fs.readFileSync(expectedPath); + var comparator = GoldenComparators[mime.lookup(goldenName)]; + if (!comparator) { + return { + pass: false, + message: 'Failed to find comparator with type ' + mime.lookup(goldenName) + ': ' + goldenName + }; + } + var result = comparator(actual, expected); + if (!result) + return { pass: true }; + ensureOutputDir(); + fs.writeFileSync(actualPath, actual); + // Copy expected to the output/ folder for convenience. + fs.writeFileSync(addSuffix(actualPath, '-expected'), expected); + if (result.diff) { + var diffPath = addSuffix(actualPath, '-diff', result.diffExtension); + fs.writeFileSync(diffPath, result.diff); + } + + var message = goldenName + ' mismatch!'; + if (result.errorMessage) + message += ' ' + result.errorMessage; + return { + pass: false, + message: message + ' ' + messageSuffix + }; + + function ensureOutputDir() { + if (!fs.existsSync(OUTPUT_DIR)) + fs.mkdirSync(OUTPUT_DIR); + } + } + }; + }, +}; /** * @param {string} filePath * @param {string} suffix + * @param {string=} customExtension * @return {string} */ -function addSuffix(filePath, suffix) { +function addSuffix(filePath, suffix, customExtension) { var dirname = path.dirname(filePath); var ext = path.extname(filePath); var name = path.basename(filePath, ext); - return path.join(dirname, name + suffix + ext); + return path.join(dirname, name + suffix + (customExtension || ext)); }