Bug 1328676 - Document some particulars of browser.Context; r=automatedtester
authorAndreas Tolfsen <ato@mozilla.com>
Wed, 04 Jan 2017 19:37:13 +0000
changeset 456691 7410544dfba432e87b973e6e68f0bf18efd665ed
parent 456690 8867228e079635242ecde2b45075fb937b210971
child 456692 8c25f4454f5bf48257416a1443cd715d44bdd492
push id40575
push userjwwang@mozilla.com
push dateFri, 06 Jan 2017 02:27:46 +0000
reviewersautomatedtester
bugs1328676
milestone53.0a1
Bug 1328676 - Document some particulars of browser.Context; r=automatedtester browser.Context has an awful API and this is a small step in the direction of mitigating some common misconceptions about its internal state. MozReview-Commit-ID: Bl5197GiSEL
testing/marionette/browser.js
--- a/testing/marionette/browser.js
+++ b/testing/marionette/browser.js
@@ -1,25 +1,21 @@
 /* This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
  * You can obtain one at http://mozilla.org/MPL/2.0/. */
 
 "use strict";
 
-const {classes: Cc, interfaces: Ci, utils: Cu, results: Cr} = Components;
-
-Cu.import("resource://gre/modules/Log.jsm");
+const {utils: Cu} = Components;
 
 Cu.import("chrome://marionette/content/element.js");
 Cu.import("chrome://marionette/content/frame.js");
 
 this.EXPORTED_SYMBOLS = ["browser"];
 
-const logger = Log.repository.getLogger("Marionette");
-
 this.browser = {};
 
 const XUL_NS = "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul";
 
 /**
  * Creates a browsing context wrapper.
  *
  * Browsing contexts handle interactions with the browser, according to
@@ -27,52 +23,72 @@ const XUL_NS = "http://www.mozilla.org/k
  *
  * @param {nsIDOMWindow} win
  *     The window whose browser needs to be accessed.
  * @param {GeckoDriver} driver
  *     Reference to the driver the browser is attached to.
  */
 browser.Context = class {
 
+  /**
+   * @param {<xul:browser>} win
+   *     Frame that is expected to contain the view of the web document.
+   * @param {GeckoDriver} driver
+   *     Reference to driver instance.
+   */
   constructor(win, driver) {
-    this.browser = undefined;
     this.window = win;
     this.driver = driver;
+
+    // In Firefox this is <xul:tabbrowser> (not <xul:browser>!)
+    // and BrowserApp in Fennec
+    this.browser = undefined;
+    this.setBrowser(win);
+
     this.knownFrames = [];
-    this.startPage = "about:blank";
-    // used in B2G to identify the homescreen content page
+
+    // Used in B2G to identify the homescreen content page
     this.mainContentId = null;
-    // used to set curFrameId upon new session
+
+    // Used to set curFrameId upon new session
     this.newSession = true;
+
     this.seenEls = new element.Store();
-    this.setBrowser(win);
 
     // A reference to the tab corresponding to the current window handle, if any.
     // Specifically, this.tab refers to the last tab that Marionette switched
     // to in this browser window. Note that this may not equal the currently
     // selected tab. For example, if Marionette switches to tab A, and then
     // clicks on a button that opens a new tab B in the same browser window,
     // this.tab will still point to tab A, despite tab B being the currently
     // selected tab.
     this.tab = null;
     this.pendingCommands = [];
 
-    // we should have one FM per BO so that we can handle modals in each Browser
+    // We should have one frame.Manager per browser.Context so that we
+    // can handle modals in each <xul:browser>.
     this.frameManager = new frame.Manager(driver);
     this.frameRegsPending = 0;
 
     // register all message listeners
     this.frameManager.addMessageManagerListeners(driver.mm);
     this.getIdForBrowser = driver.getIdForBrowser.bind(driver);
     this.updateIdForBrowser = driver.updateIdForBrowser.bind(driver);
     this._curFrameId = null;
     this._browserWasRemote = null;
     this._hasRemotenessChange = false;
   }
 
+  /**
+   * Get the <xul:browser> for the current tab in this tab browser.
+   *
+   * @return {<xul:browser>}
+   *     Browser linked to |this.tab| or the tab browser's
+   *     |selectedBrowser|.
+   */
   get browserForTab() {
     if (this.browser.getBrowserForTab) {
       return this.browser.getBrowserForTab(this.tab);
     } else {
       return this.browser.selectedBrowser;
     }
   }