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 puppeteer#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,19 +36,22 @@ 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;
     }
 
     /**
      * @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.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>