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.closeMigrationWizard(wizardWindowOrTab, forceLegacy)¶

Closes the migration wizard.

Arguments

wizardWindowOrTab (Element) – The XUL dialog window for the migration wizard in the legacy case, and the about:preferences tab otherwise. In general, it’s probably best to just pass whatever BrowserTestUtils.waitForMigrationWizard resolved to into this in order to handle both the old and new migration wizard.
forceLegacy (boolean) – True if, despite the browser.migrate.content-modal.enabled pref value, the legacy XUL migration wizard is expected.

Returns

Promise.<undefined> –

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” 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.is_hidden(element)¶

Checks if a DOM element is hidden.

Arguments

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

Returns

boolean –

static BrowserTestUtils.is_visible(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.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.

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

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

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

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, forceLegacy)¶

A helper function for this test that returns a Promise that resolves once either the legacy or new 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.
forceLegacy (boolean) – True if, despite the browser.migrate.content-modal.enabled pref value, the legacy XUL migration wizard is expected.

Returns

Promise.<Element> – Resolves to the dialog window in the legacy case, and the about:preferences tab otherwise.

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)¶

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 –

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

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.