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

@@ -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<string, !Frame>} */
+        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<!Frame>}
+     */
+    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<!Frame>} */
+        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.<!Frame>}
+    */
+    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;

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<string, function>} */
@@ -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<!Frame>}
+     */
+    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;

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="

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"
   }
 }

test/assets/frames/frame.html

@@ -0,0 +1,3 @@
+<link rel='stylesheet' href='./style.css'>
+<script src='./script.js' type='text/javascript'></script>
+<div>Hi, I'm frame</div>

test/assets/frames/nested-frames.html

@@ -0,0 +1,22 @@
+<style>
+body {
+    display: flex;
+}
+
+body iframe {
+    flex-grow: 1;
+    flex-shrink: 1;
+}
+</style>
+<script>
+async function attachFrame(frameId, url) {
+    var frame = document.createElement('iframe');
+    frame.src = url;
+    frame.id = frameId;
+    document.body.appendChild(frame);
+    await new Promise(x => frame.onload = x);
+    return 'kazakh';
+}
+</script>
+<iframe src='./two-frames.html'></iframe>
+<iframe src='./frame.html'></iframe>

test/assets/frames/script.js

@@ -0,0 +1 @@
+console.log('Cheers!');

test/assets/frames/style.css

@@ -0,0 +1,3 @@
+div {
+    color: blue;
+}

test/assets/frames/two-frames.html

@@ -0,0 +1,13 @@
+<style>
+body {
+    display: flex;
+    flex-direction: column;
+}
+
+body iframe {
+    flex-grow: 1;
+    flex-shrink: 1;
+}
+</style>
+<iframe src='./frame.html'></iframe>
+<iframe src='./frame.html'></iframe>

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;
+}

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;
+    },
+};

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

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 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 = `<link rel="stylesheet" href="file://${diffStylePath}">` + html;
     return {
-            pass: false,
-            message: goldenName + ' mismatch! ' + helpMessage
-        };
-    }
-    return {
-        pass: true
+        diff: html,
+        diffExtension: '.html'
     };
 }
 
-function ensureOutputDir() {
+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));
 }