BrowserTestUtils module

class BrowserTestUtils()

BrowserTestUtils provides useful test utilities for working with the browser in browser mochitests. Most common operations (opening, closing and switching between tabs and windows, loading URLs, waiting for events in the parent or content process, clicking things in the content process, registering about pages, etc.) have dedicated helpers on this object.

BrowserTestUtils.addContentEventListener(browser, eventName, listener, listenerOptions, checkFn)

Adds a content event listener on the given browser element. Similar to waitForContentEvent, but the listener will fire until it is removed. A callable object is returned that, when called, removes the event listener. Note that this function works even if the browser’s frameloader is swapped.

Arguments
  • browser (xul:browser()) – The browser element to listen for events in.

  • eventName (string()) – Name of the event to listen to.

  • listener (function()) – Function to call in parent process when event fires. Not passed any arguments.

  • listenerOptions (object()) – [optional] Options to pass to the event listener.

  • checkFn (function()) – [optional] Called with the Event object as argument, should return true if the event is the expected one, or false if it should be ignored and listening should continue. If not specified, the first event with the specified name resolves the returned promise. This is called within the content process and can have no closure environment.

Returns

function If called, the return value will remove the event listener.

BrowserTestUtils.addTab(tabbrowser, uri, params, beforeLoadFunc)

Opens a tab with a given uri and params object. If the params object is not set or the params parameter does not include a triggeringPrincipal then this function provides a params object using the systemPrincipal as the default triggeringPrincipal.

Arguments
  • tabbrowser (xul:tabbrowser()) – The gBrowser object to open the tab with.

  • uri (string()) – The URI to open in the new tab.

  • params (object()) – [optional] Parameters object for gBrowser.addTab.

  • beforeLoadFunc (function()) – [optional] A function to run after that xul:browser has been created but before the URL is loaded. Can spawn a content task in the tab, for example.

BrowserTestUtils.browserLoaded(browser, includeSubFrames=false, wantLoad="null", maybeErrorPage=false)

Waits for an ongoing page load in a browser window to complete.

This can be used in conjunction with any synchronous method for starting a load, like the “addTab” method on “tabbrowser”, and must be called before yielding control to the event loop. Note that calling this after multiple successive load operations can be racy, so wantLoad should be specified in these cases.

This function works by listening for custom load events on browser. These are sent by a BrowserTestUtils window actor in response to “load” and “DOMContentLoaded” content events.

Arguments
  • browser (xul:browser()) – A xul:browser.

  • includeSubFrames (Boolean()) – A boolean indicating if loads from subframes should be included.

  • wantLoad (string|function()) – If a function, takes a URL and returns true if that’s the load we’re interested in. If a string, gives the URL of the load we’re interested in. If not present, the first load resolves the promise.

  • maybeErrorPage (boolean()) – If true, this uses DOMContentLoaded event instead of load event. Also wantLoad will be called with visible URL, instead of ‘about:neterror?…’ for error page.

Returns

Promise

BrowserTestUtils.browserStarted(browser, expectedURI)

Waits for the web progress listener associated with this tab to fire a STATE_START for the toplevel document.

Arguments
  • browser (xul:browser()) – A xul:browser.

  • expectedURI (String()) – (optional) A specific URL to check the channel load against

Returns

Promise

BrowserTestUtils.browserStopped(browser, expectedURI, checkAborts)

Waits for the web progress listener associated with this tab to fire a STATE_STOP for the toplevel document.

Arguments
  • browser (xul:browser()) – A xul:browser.

  • expectedURI (String()) – (optional) A specific URL to check the channel load against

  • checkAborts (Boolean()) – (optional, defaults to false) Whether NS_BINDING_ABORTED stops ‘count’ as ‘real’ stops (e.g. caused by the stop button or equivalent APIs)

Returns

Promise

BrowserTestUtils.closeWindow(win)

Closes a window.

Arguments
  • win (Window()) – A window to close.

Returns

Promise – Resolves when the provided window has been closed. For browser windows, the Promise will also wait until all final SessionStore messages have been sent up from all browser tabs.

BrowserTestUtils.contentTopicObserved(aBrowsingContext, aTopic, aCount, aFilterFn)
There are two ways to listen for observers in a content process:
  1. Call contentTopicObserved which will watch for an observer notification in a content process to occur, and will return a promise which resolves when that notification occurs.

  2. Enclose calls to contentTopicObserved inside a pair of calls to startObservingTopics and stopObservingTopics. Usually this pair will be placed at the start and end of a test or set of tests. Any observer notification that happens between the start and stop that doesn’t match any explicitly expected by using contentTopicObserved will cause stopObservingTopics to reject with an error. For example:

    await BrowserTestUtils.startObservingTopics(bc, [“a”, “b”, “c”]); await BrowserTestUtils contentTopicObserved(bc, “a”, 2); await BrowserTestUtils.stopObservingTopics(bc, [“a”, “b”, “c”]);

    This will expect two “a” notifications to occur, but will fail if more than two occur, or if any “b” or “c” notifications occur.

Note that this function doesn’t handle adding a listener for the same topic more than once. To do that, use the aCount argument.

Arguments
  • aBrowsingContext – The browsing context associated with the content process to listen to.

  • aTopic (string()) – Observer topic to listen to. May be null to listen to any topic.

  • aCount (number()) – Number of such matching topics to listen to, defaults to 1. A match occurs when the topic and filter function match.

  • aFilterFn (function()) – Function to be evaluated in the content process which should return true if the notification matches. This function is passed the same arguments as nsIObserver.observe(). May be null to always match.

Returns

Promise – resolves when the notification occurs.

BrowserTestUtils.crashFrame((Browser), (bool), (BrowsingContext), (object?))

Crashes a remote frame tab and cleans up the generated minidumps. Resolves with the data from the .extra file (the crash annotations).

Arguments
  • (Browser) – browser A remote <xul:browser> element. Must not be null.

  • (bool) – shouldShowTabCrashPage True if it is expected that the tab crashed page will be shown for this browser. If so, the Promise will only resolve once the tab crash page has loaded.

  • (bool) – shouldClearMinidumps True if the minidumps left behind by the crash should be removed.

  • (BrowsingContext) – browsingContext The context where the frame leaves. Default to top level context if not supplied.

  • (object?) – options An object with any of the following fields: crashType: “CRASH_INVALID_POINTER_DEREF” | “CRASH_OOM” The type of crash. If unspecified, default to “CRASH_INVALID_POINTER_DEREF” asyncCrash: bool If specified and true, cause the crash asynchronously.

Returns

(Promise)

BrowserTestUtils.domWindowClosed(win)
Arguments
  • win – (optional) The window we should wait to have “domwindowclosed” sent through the observer service for. If this is not supplied, we’ll just resolve when the first “domwindowclosed” notification is seen.

Returns

Promise – A Promise which resolves when a “domwindowclosed” notification has been fired by the window watcher.

BrowserTestUtils.domWindowOpened(win, checkFn)
Arguments
  • win – (optional) The window we should wait to have “domwindowopened” sent through the observer service for. If this is not supplied, we’ll just resolve when the first “domwindowopened” notification is seen.

  • checkFn (function()) – [optional] Called with the nsIDOMWindow object as argument, should return true if the event is the expected one, or false if it should be ignored and observing should continue. If not specified, the first window resolves the returned promise.

Returns

Promise – A Promise which resolves when a “domwindowopened” notification has been fired by the window watcher.

BrowserTestUtils.domWindowOpenedAndLoaded(win, checkFn)
Arguments
  • win – (optional) The window we should wait to have “domwindowopened” sent through the observer service for. If this is not supplied, we’ll just resolve when the first “domwindowopened” notification is seen. The promise will be resolved once the new window’s document has been loaded.

  • checkFn (function()) – (optional) Called with the nsIDOMWindow object as argument, should return true if the event is the expected one, or false if it should be ignored and observing should continue. If not specified, the first window resolves the returned promise.

Returns

Promise – A Promise which resolves when a “domwindowopened” notification has been fired by the window watcher.

BrowserTestUtils.firstBrowserLoaded(window, aboutBlank, checkFn)

Waits for the selected browser to load in a new window. This is most useful when you’ve got a window that might not have loaded its DOM yet, and where you can’t easily use browserLoaded on gBrowser.selectedBrowser since gBrowser doesn’t yet exist.

Arguments
  • window (xul:window()) – A newly opened window for which we’re waiting for the first browser load.

  • aboutBlank (Boolean()) – [optional] If false, about:blank loads are ignored and we continue to wait.

  • checkFn (function|null()) – [optional] If checkFn(browser) returns false, the load is ignored and we continue to wait.

Returns

Promise

BrowserTestUtils.getBrowsingContextFrom()

If the argument is a browsingContext, return it. If the argument is a browser/frame, returns the browsing context for it.

BrowserTestUtils.is_hidden(element)

Checks if a DOM element is hidden.

Arguments
  • element (Element()) – The element which is to be checked.

Returns

boolean

BrowserTestUtils.is_visible(element)

Checks if a DOM element is visible.

Arguments
  • element (Element()) – The element which is to be checked.

Returns

boolean

BrowserTestUtils.loadURI(browser, uri)

Loads a new URI in the given browser, triggered by the system principal.

Arguments
  • browser (xul:browser()) – A xul:browser.

  • uri (string()) – The URI to load.

BrowserTestUtils.maybeCreatePreloadedBrowser(gBrowser)

Maybe create a preloaded browser and ensure it’s finished loading.

Arguments
  • gBrowser – (<xul:tabbrowser>) The tabbrowser in which to preload a browser.

BrowserTestUtils.openNewBrowserWindow(options)

Open a new browser window from an existing one. This relies on OpenBrowserWindow in browser.js, and waits for the window to be completely loaded before resolving.

Arguments
  • options (Object()) – Options to pass to OpenBrowserWindow. Additionally, supports:

  • options.waitForTabURL (bool()) – Forces the initial browserLoaded check to wait for the tab to load the given URL (instead of about:blank)

Returns

Promise – Resolves with the new window once it is loaded.

BrowserTestUtils.openNewForegroundTab(gBrowser, opening, waitForLoad, waitForStateStop, forceNewProcess)

Opens a new tab in the foreground.

This function takes an options object (which is preferred) or actual parameters. The names of the options must correspond to the names below. gBrowser is required and all other options are optional.

Arguments
  • gBrowser (tabbrowser()) – The tabbrowser to open the tab new in.

  • opening (string()) – (or url) May be either a string URL to load in the tab, or a function that will be called to open a foreground tab. Defaults to “about:blank”.

  • waitForLoad (boolean()) – True to wait for the page in the new tab to load. Defaults to true.

  • waitForStateStop (boolean()) – True to wait for the web progress listener to send STATE_STOP for the document in the tab. Defaults to false.

  • forceNewProcess (boolean()) – True to force the new tab to load in a new process. Defaults to false.

Returns

Promise – Resolves when the tab is ready and loaded as necessary.

BrowserTestUtils.openNewWindowWithFlushedCacheForMozSupports(options)

Clear the stylesheet cache and open a new window to ensure CSS @supports -moz-bool-pref(…) {} rules are correctly applied to the browser chrome.

Arguments
  • options (Object()) – See BrowserTestUtils.openNewBrowserWindow

Returns

Promise – Resolves with the new window once it is loaded.

BrowserTestUtils.overflowTabs(registerCleanupFunction, win, overflowAtStart)

Create enough tabs to cause a tab overflow in the given window.

Arguments
  • registerCleanupFunction (function()) – The test framework doesn’t keep its cleanup stuff anywhere accessible, so the first argument is a reference to your cleanup registration function, allowing us to clean up after you if necessary.

  • win (Window()) – The window where the tabs need to be overflowed.

  • overflowAtStart (boolean()) – Determines whether the new tabs are added at the beginning of the URL bar or at the end of it.

BrowserTestUtils.promiseAlertDialog(buttonNameOrElementID, uri)

Waits for the dialog to open, and clicks the specified button, and waits for the dialog to close.

Arguments
  • buttonNameOrElementID (string()) – The name of the button (“accept”, “cancel”, etc) or element ID to click.

  • uri (string()) – The URI of the dialog to wait for. Defaults to the common dialog.

Returns

Promise – A Promise which resolves when a “domwindowopened” notification for a dialog has been fired by the window watcher and the specified button is clicked, and the dialog has been fully closed.

BrowserTestUtils.promiseAlertDialogOpen(buttonNameOrElementID, uri)

Waits for the dialog to open, and clicks the specified button.

Arguments
  • buttonNameOrElementID (string()) – The name of the button (“accept”, “cancel”, etc) or element ID to click.

  • uri (string()) – The URI of the dialog to wait for. Defaults to the common dialog.

Returns

Promise – A Promise which resolves when a “domwindowopened” notification for a dialog has been fired by the window watcher and the specified button is clicked.

BrowserTestUtils.registerAboutPage(registerCleanupFunction, aboutModule, pageURI, flags)

Registers an about: page with particular flags in both the parent and any content processes. Returns a promise that resolves when registration is complete.

Arguments
  • registerCleanupFunction (function()) – The test framework doesn’t keep its cleanup stuff anywhere accessible, so the first argument is a reference to your cleanup registration function, allowing us to clean up after you if necessary.

  • aboutModule (String()) – The name of the about page.

  • pageURI (String()) – The URI the about: page should point to.

  • flags (Number()) – The nsIAboutModule flags to use for registration.

Returns

Promise – Promise that resolves when registration has finished.

BrowserTestUtils.reloadTab(tab, includeSubFrames=false)
Arguments
  • tab (tab()) – The tab that will be reloaded.

  • includeSubFrames (Boolean()) – A boolean indicating if loads from subframes should be included when waiting for the frame to reload.

Returns

Promise

BrowserTestUtils.removeTab((tab), (Object))

Removes the given tab from its parent tabbrowser. This method doesn’t SessionStore etc.

Arguments
  • (tab) – tab The tab to remove.

  • (Object) – options Extra options to pass to tabbrowser’s removeTab method.

BrowserTestUtils.sendAsyncMessage(aBrowsingContext, aMessageName, aMessageData)

Sends a message to a specific BrowserTestUtils window actor.

Arguments
  • aBrowsingContext (BrowsingContext()) – The browsing context where the actor lives.

  • aMessageName (string()) – Name of the message to be sent to the actor.

  • aMessageData (object()) – Extra information to pass to the actor.

BrowserTestUtils.sendChar(char, browsingContext)

Version of EventUtils’ sendChar function; it will synthesize a keypress event in a child process and returns a Promise that will resolve when the event was fired. Instead of a Window, a Browser or Browsing Context is required to be passed to this function.

Arguments
  • char (String()) – A character for the keypress event that is sent to the browser.

  • browsingContext (BrowserContext|MozFrameLoaderOwner()) – Browsing context or browser element, must not be null

Returns

Promise

BrowserTestUtils.sendQuery(aBrowsingContext, aMessageName, aMessageData)

Sends a query to a specific BrowserTestUtils window actor.

Arguments
  • aBrowsingContext (BrowsingContext()) – The browsing context where the actor lives.

  • aMessageName (string()) – Name of the message to be sent to the actor.

  • aMessageData (object()) – Extra information to pass to the actor.

BrowserTestUtils.simulateProcessLaunchFail(browser)

Attempts to simulate a launch fail by crashing a browser, but stripping the browser of its childID so that the TabCrashHandler thinks it was a launch fail.

Arguments
  • browser – (<xul:browser>) The browser to simulate a content process launch failure on.

Returns

Promise

BrowserTestUtils.startObservingTopics(aBrowsingContext, aTopics)

Starts observing a list of topics in a content process. Use contentTopicObserved to allow an observer notification. Any other observer notification that occurs that matches one of the specified topics will cause the promise to reject.

Calling this function more than once adds additional topics to be observed without replacing the existing ones.

Arguments
  • aBrowsingContext (BrowsingContext()) – The browsing context associated with the content process to listen to.

  • aTopics (Array.) – array of observer topics

Returns

Promise – resolves when the listeners have been added.

BrowserTestUtils.stopObservingTopics(aBrowsingContext, aTopics)

Stop listening to a set of observer topics.

Arguments
  • aBrowsingContext (BrowsingContext()) – The browsing context associated with the content process to listen to.

  • aTopics (Array.) – array of observer topics. If empty, then all current topics being listened to are removed.

Returns

Promise – promise that fails if an unexpected observer occurs.

BrowserTestUtils.switchTab(tabbrowser, tab)

Switches to a tab and resolves when it is ready.

Arguments
  • tabbrowser (tabbrowser()) – The tabbrowser.

  • tab (tab()) – Either a tab element to switch to or a function to perform the switch.

Returns

Promise – Resolves when the tab has been switched to.

BrowserTestUtils.synthesizeComposition(event, browsingContext)

Version of EventUtils’ synthesizeComposition function; it will synthesize a composition event in a child process and returns a Promise that will resolve when the event was fired. Instead of a Window, a Browser or Browsing Context is required to be passed to this function.

Arguments
  • event (Object()) – See the documentation available for EventUtils#synthesizeComposition.

  • browsingContext (BrowserContext|MozFrameLoaderOwner()) – Browsing context or browser element, must not be null

Returns

Promise

BrowserTestUtils.synthesizeCompositionChange(event, browsingContext)

Version of EventUtils’ synthesizeCompositionChange function; it will synthesize a compositionchange event in a child process and returns a Promise that will resolve when the event was fired. Instead of a Window, a Browser or Browsing Context object is required to be passed to this function.

Arguments
  • event (Object()) – See the documentation available for EventUtils#synthesizeCompositionChange.

  • browsingContext (BrowserContext|MozFrameLoaderOwner()) – Browsing context or browser element, must not be null

Returns

Promise

BrowserTestUtils.synthesizeKey(key, event, browsingContext)

Version of EventUtils’ synthesizeKey function; it will synthesize a key event in a child process and returns a Promise that will resolve when the event was fired. Instead of a Window, a Browser or Browsing Context is required to be passed to this function.

Arguments
  • key (String()) – See the documentation available for EventUtils#synthesizeKey.

  • event (Object()) – See the documentation available for EventUtils#synthesizeKey.

  • browsingContext (BrowserContext|MozFrameLoaderOwner()) – Browsing context or browser element, must not be null

Returns

Promise

BrowserTestUtils.synthesizeMouse(target, offsetX, offsetY, event, browsingContext, handlingUserInput)
Versions of EventUtils.jsm synthesizeMouse functions that synthesize a

mouse event in a child process and return promises that resolve when the event has fired and completed. Instead of a window, a browser or browsing context is required to be passed to this function.

Arguments
  • target – One of the following: - a selector string that identifies the element to target. The syntax is as for querySelector. - a function to be run in the content process that returns the element to target - null, in which case the offset is from the content document’s edge.

  • offsetX (integer()) – x offset from target’s left bounding edge

  • offsetY (integer()) – y offset from target’s top bounding edge

  • event (Object()) – object Additional arguments, similar to the EventUtils.jsm version

  • browsingContext (BrowserContext|MozFrameLoaderOwner()) – Browsing context or browser element, must not be null

  • handlingUserInput (boolean()) – Whether the synthesize should be perfomed while simulating user interaction (making windowUtils.isHandlingUserInput be true).

Returns

Promise

BrowserTestUtils.synthesizeMouseAtCenter()
Version of synthesizeMouse that uses the center of the target as the mouse

location. Arguments and the return value are the same.

BrowserTestUtils.synthesizeMouseAtPoint()
Version of synthesizeMouse that uses a client point within the child

window instead of a target as the offset. Otherwise, the arguments and return value are the same as synthesizeMouse.

BrowserTestUtils.synthesizeTouch(target, offsetX, offsetY, event, browsingContext)
Versions of EventUtils.jsm synthesizeTouch functions that synthesize a

touch event in a child process and return promises that resolve when the event has fired and completed. Instead of a window, a browser or browsing context is required to be passed to this function.

Arguments
  • target – One of the following: - a selector string that identifies the element to target. The syntax is as for querySelector. - a function to be run in the content process that returns the element to target - null, in which case the offset is from the content document’s edge.

  • offsetX (integer()) – x offset from target’s left bounding edge

  • offsetY (integer()) – y offset from target’s top bounding edge

  • event (Object()) – object Additional arguments, similar to the EventUtils.jsm version

  • browsingContext (BrowserContext|MozFrameLoaderOwner()) – Browsing context or browser element, must not be null

Returns

Promise

BrowserTestUtils.waitForAttribute(attr, element, value)

Returns a promise that is resolved when element gains attribute (or, optionally, when it is set to value).

Arguments
  • attr (String()) – The attribute to wait for

  • element (Element()) – The element which should gain the attribute

  • value (String()) – (optional) Optional, the value the attribute should have.

Returns

Promise

BrowserTestUtils.waitForAttributeRemoval(attr, element)

Returns a promise that is resolved when element loses an attribute.

Arguments
  • attr (String()) – The attribute to wait for

  • element (Element()) – The element which should lose the attribute

Returns

Promise

BrowserTestUtils.waitForBrowserStateChange(browser, expectedURI, checkFn)

Waits for the web progress listener associated with this tab to fire a state change that matches checkFn for the toplevel document.

Arguments
  • browser (xul:browser()) – A xul:browser.

  • expectedURI (String()) – (optional) A specific URL to check the channel load against

  • checkFn (function()) – If checkFn(aStateFlags, aStatus) returns false, the state change is ignored and we continue to wait.

Returns

Promise

BrowserTestUtils.waitForContentEvent(eventName, capture, checkFn, wantUntrusted)

Like waitForEvent, but adds the event listener to the message manager global for browser.

Arguments
  • eventName (string()) – Name of the event to listen to.

  • capture (bool()) – [optional] Whether to use a capturing listener.

  • checkFn (function()) – [optional] Called with the Event object as argument, should return true if the event is the expected one, or false if it should be ignored and listening should continue. If not specified, the first event with the specified name resolves the returned promise.

  • wantUntrusted (bool()) – [optional] Whether to accept untrusted events

Returns

Promise

BrowserTestUtils.waitForDialogClose(dialog)

Wait for the containing dialog with the id window-modal-dialog to become empty and close.

Arguments
  • dialog (HTMLDialogElement()) – The dialog to wait on.

Returns

Promise – Resolves once the the dialog has closed

BrowserTestUtils.waitForDocLoadAndStopIt(expectedURL, browser, checkFn)

Waits for the next top-level document load in the current browser. The URI of the document is compared against expectedURL. The load is then stopped before it actually starts.

Arguments
  • expectedURL (string()) – The URL of the document that is expected to load.

  • browser (object()) – The browser to wait for.

  • checkFn (function()) – (optional) Function to run on the channel before stopping it.

Returns

Promise

BrowserTestUtils.waitForErrorPage(browser)

Like browserLoaded, but waits for an error page to appear.

Arguments
  • browser (xul:browser()) – A xul:browser.

Returns

Promise

BrowserTestUtils.waitForEvent(subject, eventName, capture, checkFn, wantsUntrusted=false)

Waits for an event to be fired on a specified element.

Arguments
  • subject (Element()) – The element that should receive the event.

  • eventName (string()) – Name of the event to listen to.

  • capture (bool()) – True to use a capturing listener.

  • checkFn (function()) – Called with the Event object as argument, should return true if the event is the expected one, or false if it should be ignored and listening should continue. If not specified, the first event with the specified name resolves the returned promise.

  • wantsUntrusted (bool()) – True to receive synthetic events dispatched by web content.

Returns

Promise

Examples:

let promiseEvent = BrowserTestUtils.waitForEvent(element, "eventName");
   // Do some processing here that will cause the event to be fired
   // ...
   // Now wait until the Promise is fulfilled
   let receivedEvent = await promiseEvent;
// The promise resolution/rejection handler for the returned promise is
   // guaranteed not to be called until the next event tick after the event
   // listener gets called, so that all other event listeners for the element
   // are executed before the handler is executed.

   let promiseEvent = BrowserTestUtils.waitForEvent(element, "eventName");
   // Same event tick here.
   await promiseEvent;
   // Next event tick here.
// If some code, such like adding yet another event listener, needs to be
   // executed in the same event tick, use raw addEventListener instead and
   // place the code inside the event listener.

   element.addEventListener("load", () => {
     // Add yet another event listener in the same event tick as the load
     // event listener.
     p = BrowserTestUtils.waitForEvent(element, "ready");
   }, { once: true });
BrowserTestUtils.waitForGlobalNotificationBar(win, notificationValue)

Waits for a <xul:notification> with a particular value to appear in the global <xul:notificationbox> of the given browser window.

Arguments
  • win (Window()) – The browser window in whose global notificationbox the notification is expected to appear.

  • notificationValue (String()) – The “value” of the notification, which is often used as a unique identifier. Example: “captive-portal-detected”.

Returns

Promise – Resolves to the <xul:notification> that is being shown.

BrowserTestUtils.waitForLocationChange(tabbrowser, url)

Waits for onLocationChange.

Arguments
  • tabbrowser (tabbrowser()) – The tabbrowser to wait for the location change on.

  • url (string()) – The string URL to look for. The URL must match the URL in the location bar exactly.

Returns

Promise

BrowserTestUtils.waitForMessage(messageManager, message, checkFn)

Wait for a message to be fired from a particular message manager

Arguments
  • messageManager (nsIMessageManager()) – The message manager that should be used.

  • message (String()) – The message we’re waiting for.

  • checkFn (function()) – (optional) Optional function to invoke to check the message.

BrowserTestUtils.waitForMutationCondition(target, options, checkFn)

Wait until DOM mutations cause the condition expressed in checkFn to pass.

Intended as an easy-to-use alternative to waitForCondition.

Arguments
  • target (Element()) – The target in which to observe mutations.

  • options (Object()) – The options to pass to MutationObserver.observe();

  • checkFn (function()) – Function that returns true when it wants the promise to be resolved.

BrowserTestUtils.waitForNewTab(tabbrowser, wantLoad="null", waitForLoad=false, waitForAnyTab=false)

Waits for a tab to open and load a given URL.

By default, the method doesn’t wait for the tab contents to load.

Arguments
  • tabbrowser (tabbrowser()) – The tabbrowser to look for the next new tab in.

  • wantLoad (string|function()) – If a function, takes a URL and returns true if that’s the load we’re interested in. If a string, gives the URL of the load we’re interested in. If not present, the first non-about:blank load is used.

  • waitForLoad (boolean()) – True to wait for the page in the new tab to load. Defaults to false.

  • waitForAnyTab (boolean()) – True to wait for the url to be loaded in any new tab, not just the next one opened.

Returns

Promise

BrowserTestUtils.waitForNewWindow(aParams)

Waits for the next browser window to open and be fully loaded.

Arguments
  • aParams (Object()) –

  • aParams.url (string()) – If set, we will wait until the initial browser in the new window has loaded a particular page. If unset, the initial browser may or may not have finished loading its first page when the resulting Promise resolves.

  • aParams.anyWindow (bool()) – True to wait for the url to be loaded in any new window, not just the next one opened.

  • aParams.maybeErrorPage (bool()) – See browserLoaded function.

Returns

Promise – A Promise which resolves the next time that a DOM window opens and the delayed startup observer notification fires.

BrowserTestUtils.waitForNotificationBar(tabbrowser, browser, notificationValue)

Waits for a <xul:notification> with a particular value to appear for the <xul:notificationbox> of the passed in browser.

Arguments
  • tabbrowser (xul:tabbrowser()) – The gBrowser that hosts the browser that should show the notification. For most tests, this will probably be gBrowser.

  • browser (xul:browser()) – The browser that should be showing the notification.

  • notificationValue (String()) – The “value” of the notification, which is often used as a unique identifier. Example: “plugin-crashed”.

Returns

Promise – Resolves to the <xul:notification> that is being shown.

BrowserTestUtils.waitForPopupEvent(popup, eventSuffix)

Like waitForEvent, but acts on a popup. It ensures the popup is not already in the expected state.

Arguments
  • popup (Element()) – The popup element that should receive the event.

  • eventSuffix (string()) – The event suffix expected to be received, one of “shown” or “hidden”.

Returns

Promise

BrowserTestUtils.waitForSelectPopupShown(win)

Waits for the select popup to be shown. This is needed because the select dropdown is created lazily.

Arguments
  • win (Window()) – A window to expect the popup in.

Returns

Promise – Resolves when the popup has been fully opened. The resolution value is the select popup.

BrowserTestUtils.waitForSessionStoreUpdate(tab)

Returns a Promise that resolves once the SessionStore information for the given tab is updated and all listeners are called.

Arguments
  • tab (xul:tab()) – The tab that will be removed.

Returns

Promise

BrowserTestUtils.waitForTabClosing((tab))

Returns a Promise that resolves once the tab starts closing.

Arguments
  • (tab) – tab The tab that will be removed.

Returns

(Promise)

BrowserTestUtils.waitForTransition(element, timeout)

Waits for CSS transitions to complete for an element. Tracks any transitions that start after this function is called and resolves once all started transitions complete.

Arguments
  • element (Element()) – The element that will transition.

  • timeout (Number()) – The maximum time to wait in milliseconds. Defaults to 5 seconds.

Returns

Promise – Resolves when transitions complete or rejects if the timeout is hit.

BrowserTestUtils.windowClosed(win)

Returns a Promise that resolves when a window has finished closing.

Arguments
  • win (Window()) – The closing window.

Returns

Promise – Resolves when the provided window has been fully closed. For browser windows, the Promise will also wait until all final SessionStore messages have been sent up from all browser tabs.

BrowserTestUtils.withNewTab(options, taskFn)

Loads a page in a new tab, executes a Task and closes the tab.

Arguments
  • options (Object|String()) – If this is a string it is the url to open and will be opened in the currently active browser window.

  • options.gBrowser (tabbrowser()) – A reference to the tabbrowser element where the new tab should be opened,

  • options.url (string()) – The URL of the page to load.

  • taskFn (function()) – Async function representing that will be executed while the tab is loaded. The first argument passed to the function is a reference to the browser object for the new tab.

Returns

Any – Returns the value that is returned from taskFn.