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.

static 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.

static 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.

static 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 –

static 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 –

static 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 –

static 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.

static BrowserTestUtils.contentTopicObserved(aBrowsingContext, aTopic, aCount, aFilterFn)

There are two ways to listen for observers in a content process:

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.
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.

static 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” | “CRASH_SYSCALL” The type of crash. If unspecified, default to “CRASH_INVALID_POINTER_DEREF” asyncCrash: bool If specified and true, cause the crash asynchronously.

Returns:

(Promise)

static 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.

static 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.

static 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.

static 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 –

static BrowserTestUtils.getBrowsingContextFrom(): If the argument is a browsingContext, return it. If the argument is a browser/frame, returns the browsing context for it.

static BrowserTestUtils.isHidden(element)

Checks if a DOM element is hidden.

Arguments:

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

Returns:

boolean –

static BrowserTestUtils.isVisible(element)

Checks if a DOM element is visible.

Arguments:

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

Returns:

boolean –

static 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.

static 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.

static 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.

static BrowserTestUtils.overflowTabs(registerCleanupFunction, win, params)

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

Arguments:

registerCleanupFunction (function|null) – 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. This can be null if you are using a temporary window for the test.
win (Window) – The window where the tabs need to be overflowed.
params (object) – [optional] Parameters object for BrowserTestUtils.overflowTabs. overflowAtStart: bool Determines whether the new tabs are added at the beginning of the URL bar or at the end of it. overflowTabFactor: 3 | 1.1 Factor that helps in determining the tab count for overflow.

static 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.

static 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.

static 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.

static 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 –

static 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.

static 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.

static 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 –

static 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.

static 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

static BrowserTestUtils.startLoadingURIString(browser, uri)

Starts the load of a new URI in the given browser, triggered by the system principal. Note this won’t want for the load to be complete. For that you may either use BrowserTestUtils.browserLoaded(), BrowserTestUtils.waitForErrorPage(), or make your own handler.

Arguments:

browser (xul:browser) – A xul:browser.
uri (string) – The URI to load.

static 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.<String>) – array of observer topics

Returns:

Promise – resolves when the listeners have been added.

static 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.<String>) – 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.

static 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.

static 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 –

static 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 –

static 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 –

static BrowserTestUtils.synthesizeMouse(target, offsetX, offsetY, event, browsingContext, handlingUserInput)

Versions of EventUtils.sys.mjs 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.sys.mjs 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 –

static BrowserTestUtils.synthesizeMouseAtCenter()

Version of synthesizeMouse that uses the center of the target as the mouse: location. Arguments and the return value are the same.

static 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.

static BrowserTestUtils.synthesizeTouch(target, offsetX, offsetY, event, browsingContext)

Versions of EventUtils.sys.mjs 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.sys.mjs version
browsingContext (BrowserContext|MozFrameLoaderOwner) – Browsing context or browser element, must not be null

Returns:

Promise –

static 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 –

static 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 –

static 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 –

static 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 –

static BrowserTestUtils.waitForDateTimePickerPanelShown(win)

Waits for the datetime picker popup to be shown.

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.

static 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

static 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 –

static BrowserTestUtils.waitForErrorPage(browser)

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

Arguments:

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

Returns:

Promise –

static 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 });

static 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.

static 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 –

static 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.

static BrowserTestUtils.waitForMigrationWizard(window)

A helper function for this test that returns a Promise that resolves once the migration wizard appears.

Arguments:

window (DOMWindow) – The top-level window that the about:preferences tab is likely to open in if the new migration wizard is enabled.

Returns:

Promise.<Element> – Resolves to the opened about:preferences tab with the migration wizard running and loaded in it.

static 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.

static BrowserTestUtils.waitForNewTab(tabbrowser, wantLoad="null", waitForLoad=false, waitForAnyTab=false, maybeErrorPage=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.
maybeErrorPage (boolean) – See browserLoaded function.

Returns:

Promise –

static BrowserTestUtils.waitForNewWindow(aParams)

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

Arguments:

aParams (Object)
aParams.url (string) – The url to await being loaded. If unset this may or may not wait for any page to be loaded, according to the waitForAnyURLLoaded param.
aParams.waitForAnyURLLoaded (bool) – When url is unset, this controls whether to wait for any initial URL to be loaded. Defaults to false, that means the initial browser may or may not have finished loading its first page when this resolves. When url is set, this is ignored, thus the load is always awaited for.
aParams.anyWindow (bool)
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.

static 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.

static 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 –

static 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.

static 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 –

static BrowserTestUtils.waitForTabClosing((tab))

Returns a Promise that resolves once the tab starts closing.

Arguments:

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

Returns:

(Promise)

static 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.

static 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.

static 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.