BrowserTestUtils 模块¶

class BrowserTestUtils()¶

BrowserTestUtils 提供了在浏览器 mochitests 中处理浏览器的实用测试工具。此对象上提供了大多数常见操作（在选项卡和窗口之间打开、关闭和切换、加载 URL、等待父进程或内容进程中的事件、单击内容进程中的内容、注册 about 页面等）的专用帮助程序。

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

在给定的浏览器元素上添加内容事件监听器。类似于 waitForContentEvent，但监听器将一直触发，直到将其移除。返回一个可调用的对象，当调用它时，会移除事件监听器。请注意，即使浏览器的 frameloader 被交换，此函数也能正常工作。

参数：

browser (xul:browser) – 要在其中监听事件的浏览器元素。
eventName (string) – 要监听的事件的名称。
listener (function) – 事件触发时在父进程中调用的函数。不传递任何参数。
listenerOptions (object) – [可选] 传递给事件监听器的选项。
checkFn (function) – [可选] 使用 Event 对象作为参数调用，如果事件是预期的事件，则应返回 true，否则如果应忽略它并且监听应继续，则返回 false。如果未指定，则具有指定名称的第一个事件会解析返回的 Promise。这是在内容进程中调用的，并且不能有任何闭包环境。

返回值：

function 如果调用，返回值将移除事件监听器。

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

使用给定的 uri 和 params 对象打开一个选项卡。如果 params 对象未设置，或者 params 参数不包含触发主体，则此函数将使用 systemPrincipal 作为默认触发主体提供 params 对象。

参数：

tabbrowser (xul:tabbrowser) – 要使用其打开选项卡的 gBrowser 对象。
uri (string) – 在新选项卡中打开的 URI。
params (object) – [可选] gBrowser.addTab 的参数对象。
beforeLoadFunc (function) – [可选] 在创建 xul:browser 后但在加载 URL 之前运行的函数。例如，可以在选项卡中生成内容任务。

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

等待浏览器窗口中正在进行的页面加载完成。

这可以与任何用于启动加载的同步方法结合使用，例如“tabbrowser”上的“addTab”方法，并且必须在将控制权交给事件循环之前调用。请注意，在多个连续加载操作后调用此方法可能会出现竞争条件，因此在这些情况下应指定wantLoad。

此函数通过监听browser上的自定义加载事件来工作。这些事件由 BrowserTestUtils 窗口参与者在响应“load”和“DOMContentLoaded”内容事件时发送。

参数：

browser (xul:browser) – 一个 xul:browser。
includeSubFrames (Boolean) – 一个布尔值，指示是否应包含来自子框架的加载。
wantLoad (string|function) – 如果是函数，则获取 URL 并返回 true（如果那是我们感兴趣的加载）。如果是字符串，则给出我们感兴趣的加载的 URL。如果不存在，则第一个加载会解析 Promise。
maybeErrorPage (boolean) – 如果为 true，则使用 DOMContentLoaded 事件而不是 load 事件。此外，wantLoad 将使用可见 URL 调用，而不是错误页面的“about:neterror?…”。

返回值：

Promise –

static BrowserTestUtils.browserStarted(browser, expectedURI)¶

等待与此选项卡关联的 Web 进度监听器为顶级文档触发 STATE_START。

参数：

browser (xul:browser) – 一个 xul:browser。
expectedURI (String) – (可选) 要检查通道加载的特定 URL

返回值：

Promise –

static BrowserTestUtils.browserStopped(browser, expectedURI, checkAborts)¶

等待与此选项卡关联的 Web 进度监听器为顶级文档触发 STATE_STOP。

参数：

browser (xul:browser) – 一个 xul:browser。
expectedURI (String) – (可选) 要检查通道加载的特定 URL
checkAborts (Boolean) – (可选，默认为 false) 是否 NS_BINDING_ABORTED 将“count”计为“真实”停止（例如，由停止按钮或等效 API 导致）

返回值：

Promise –

static BrowserTestUtils.closeWindow(win)¶

关闭窗口。

参数：

win (Window) – 要关闭的窗口。

返回值：

Promise – 在提供的窗口关闭时解析。对于浏览器窗口，Promise 还将等待来自所有浏览器选项卡的所有最终 SessionStore 消息发送完毕。

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

有两种方法可以监听内容进程中的观察者

调用 contentTopicObserved，它将监视内容进程中观察者通知的发生，并返回一个 Promise，该 Promise 在该通知发生时解析。
将对 contentTopicObserved 的调用括在对 startObservingTopics 和 stopObservingTopics 的调用对中。通常，此对将放置在测试或一组测试的开头和结尾。在开始和停止之间发生的任何不与使用 contentTopicObserved 明确期望的任何内容匹配的观察者通知都将导致 stopObservingTopics 拒绝并显示错误。例如

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

这将期望发生两个“a”通知，但如果发生超过两个通知，或者如果发生任何“b”或“c”通知，则会失败。

请注意，此函数不会处理多次为同一主题添加监听器。为此，请使用 aCount 参数。

参数：

aBrowsingContext – 与要监听的内容进程关联的浏览上下文。
aTopic (string) – 要监听的观察者主题。可以为 null 以监听任何主题。
aCount (number) – 要监听此类匹配主题的数量，默认为 1。当主题和筛选器函数匹配时，就会发生匹配。
aFilterFn (function) – 在内容进程中计算的函数，如果通知匹配，则应返回 true。此函数传递与 nsIObserver.observe() 相同的参数。可以为 null 以始终匹配。

返回值：

Promise – 通知发生时解析。

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

使远程框架选项卡崩溃并清理生成的 minidump。解析 .extra 文件中的数据（崩溃注释）。

参数：

(Browser) – browser 一个远程 <xul:browser> 元素。不能为 null。
(bool) – shouldShowTabCrashPage 如果预期将显示此浏览器的选项卡崩溃页面，则为 true。如果是这样，Promise 将仅在选项卡崩溃页面加载后才解析。
(bool) – shouldClearMinidumps 如果应删除崩溃留下的 minidump，则为 true。
(BrowsingContext) – browsingContext 框架离开的上下文。如果未提供，则默认为顶级上下文。
(object?) – options 具有以下任何字段的对象：crashType: “CRASH_INVALID_POINTER_DEREF” | “CRASH_OOM” | “CRASH_SYSCALL” 崩溃类型。如果未指定，则默认为“CRASH_INVALID_POINTER_DEREF” asyncCrash: bool 如果指定且为true，则异步导致崩溃。

返回值：

(Promise)

static BrowserTestUtils.domWindowClosed(win)¶

参数：

win – (可选) 我们应该等待通过观察者服务发送“domwindowclosed”的窗口。如果未提供此参数，我们将在看到第一个“domwindowclosed”通知时解析。

返回值：

Promise – 当窗口观察器触发“domwindowclosed”通知时解析的 Promise。

static BrowserTestUtils.domWindowOpened(win, checkFn)¶

参数：

win – (可选) 我们应该等待通过观察者服务发送“domwindowopened”的窗口。如果未提供此参数，我们将在看到第一个“domwindowopened”通知时解析。
checkFn (function) – [可选] 使用 nsIDOMWindow 对象作为参数调用，如果事件是预期的事件，则应返回 true，否则如果应忽略它并且观察应继续，则返回 false。如果未指定，则第一个窗口会解析返回的 Promise。

返回值：

Promise – 当窗口观察器触发“domwindowopened”通知时解析的 Promise。

static BrowserTestUtils.domWindowOpenedAndLoaded(win, checkFn)¶

参数：

win – (可选) 我们应该等待其通过观察者服务发送“domwindowopened”的窗口。如果未提供，则仅在看到第一个“domwindowopened”通知时解析。一旦新窗口的文档加载完成，promise 将被解析。
checkFn (function) – (可选) 以 nsIDOMWindow 对象作为参数调用，如果事件是预期的事件，则应返回 true，否则如果应忽略它并且应继续观察，则返回 false。如果未指定，则第一个窗口将解析返回的 promise。

返回值：

Promise – 当窗口观察器触发“domwindowopened”通知时解析的 Promise。

static BrowserTestUtils.firstBrowserLoaded(window, aboutBlank, checkFn)¶

等待选定的浏览器在新窗口中加载。当您有一个可能尚未加载其 DOM 的窗口，并且您无法轻松地在 gBrowser.selectedBrowser 上使用 browserLoaded（因为 gBrowser 尚未存在）时，这非常有用。

参数：

window (xul:window) – 一个新打开的窗口，我们正在等待其第一个浏览器加载。
aboutBlank (Boolean) – [可选] 如果为 false，则忽略 about:blank 加载，并且我们将继续等待。
checkFn (function|null) – [可选] 如果 checkFn(browser) 返回 false，则忽略加载并继续等待。

返回值：

Promise –

static BrowserTestUtils.getBrowsingContextFrom()¶: 如果参数是 browsingContext，则返回它。如果参数是浏览器/框架，则返回其 browsing context。

static BrowserTestUtils.isHidden(element)¶

检查 DOM 元素是否隐藏。

参数：

element (Element) – 要检查的元素。

返回值：

boolean –

static BrowserTestUtils.isVisible(element)¶

检查 DOM 元素是否可见。

参数：

element (Element) – 要检查的元素。

返回值：

boolean –

static BrowserTestUtils.maybeCreatePreloadedBrowser(gBrowser)¶

可能创建一个预加载的浏览器并确保它已完成加载。

参数：

gBrowser – (<xul:tabbrowser>) 要在其中预加载浏览器的 tabbrowser。

static BrowserTestUtils.openNewBrowserWindow(options)¶

从现有窗口打开一个新的浏览器窗口。这依赖于 browser.js 中的 OpenBrowserWindow，并在窗口完全加载之前等待解析。

参数：

options (Object) – 传递给 OpenBrowserWindow 的选项。此外，还支持
options.waitForTabURL (bool) – 强制初始 browserLoaded 检查等待选项卡加载给定的 URL（而不是 about:blank）

返回值：

Promise – 加载完成后，使用新窗口解析。

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

在前台打开一个新标签页。

此函数采用选项对象（首选）或实际参数。选项的名称必须与下面的名称相对应。gBrowser 是必需的，所有其他选项都是可选的。

参数：

gBrowser (tabbrowser) – 要在新标签页中打开标签页的 tabbrowser。
opening (string) – (或 url) 可以是将在标签页中加载的字符串 URL，也可以是将被调用的函数以打开前台标签页。默认为“about:blank”。
waitForLoad (boolean) – 如果要等待新标签页中的页面加载，则为 true。默认为 true。
waitForStateStop (boolean) – 如果要等待 Web 进度侦听器发送标签页中文档的 STATE_STOP，则为 true。默认为 false。
forceNewProcess (boolean) – 如果要强制新标签页在新进程中加载，则为 true。默认为 false。

返回值：

Promise – 当标签页准备就绪并根据需要加载时解析。

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

创建足够的标签页以在给定窗口中导致标签页溢出。

参数：

registerCleanupFunction (function) – 测试框架不会将其清理内容保存在任何可访问的地方，因此第一个参数是对您的清理注册函数的引用，允许我们根据需要在您之后进行清理。
win (Window) – 需要溢出标签页的窗口。
params (object) – [可选] BrowserTestUtils.overflowTabs 的参数对象。overflowAtStart: bool 确定新标签页是在 URL 地址栏的开头还是结尾添加。overflowTabFactor: 3 | 1.1 有助于确定溢出标签页计数的因子。

static BrowserTestUtils.promiseAlertDialog(buttonNameOrElementID, uri)¶

等待对话框打开，然后单击指定的按钮，并等待对话框关闭。

参数：

buttonNameOrElementID (string) – 要单击的按钮的名称（“accept”、“cancel”等）或元素 ID。
uri (string) – 要等待的对话框的 URI。默认为通用对话框。

返回值：

Promise – 当窗口观察程序已触发对话框的“domwindowopened”通知并单击了指定的按钮，并且对话框已完全关闭时解析的 Promise。

static BrowserTestUtils.promiseAlertDialogOpen(buttonNameOrElementID, uri)¶

等待对话框打开，然后单击指定的按钮。

参数：

buttonNameOrElementID (string) – 要单击的按钮的名称（“accept”、“cancel”等）或元素 ID。
uri (string) – 要等待的对话框的 URI。默认为通用对话框。

返回值：

Promise – 当窗口观察程序已触发对话框的“domwindowopened”通知并单击了指定的按钮时解析的 Promise。

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

在父进程和任何内容进程中使用特定标志注册 about: 页面。返回一个 promise，该 promise 在注册完成后解析。

参数：

registerCleanupFunction (function) – 测试框架不会将其清理内容保存在任何可访问的地方，因此第一个参数是对您的清理注册函数的引用，允许我们根据需要在您之后进行清理。
aboutModule (String) – about 页面的名称。
pageURI (String) – about: 页面应指向的 URI。
flags (Number) – 用于注册的 nsIAboutModule 标志。

返回值：

Promise – 注册完成后解析的 Promise。

static BrowserTestUtils.reloadTab(tab, includeSubFrames=false)¶

参数：

tab (tab) – 将重新加载的标签页。
includeSubFrames (Boolean) – 一个布尔值，指示在等待框架重新加载时是否应包含来自子框架的加载。

返回值：

Promise –

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

从其父 tabbrowser 中删除给定的标签页。此方法不使用 SessionStore 等。

参数：

(tab) – tab 要删除的标签页。
(Object) – options 要传递给 tabbrowser 的 removeTab 方法的额外选项。

static BrowserTestUtils.sendAsyncMessage(aBrowsingContext, aMessageName, aMessageData)¶

向特定的 BrowserTestUtils 窗口 actor 发送消息。

参数：

aBrowsingContext (BrowsingContext) – actor 所在的 browsing context。
aMessageName (string) – 要发送到 actor 的消息的名称。
aMessageData (object) – 要传递给 actor 的额外信息。

static BrowserTestUtils.sendChar(char, browsingContext)¶

EventUtils 的 sendChar 函数的版本；它将在子进程中合成一个键盘按下事件，并返回一个 Promise，该 Promise 在事件触发时解析。需要传递 Browser 或 Browsing Context 而不是 Window 到此函数。

参数：

char (String) – 发送到浏览器的键盘按下事件的字符。
browsingContext (BrowserContext|MozFrameLoaderOwner) – Browsing context 或浏览器元素，不得为 null

返回值：

Promise –

static BrowserTestUtils.sendQuery(aBrowsingContext, aMessageName, aMessageData)¶

向特定的 BrowserTestUtils 窗口 actor 发送查询。

参数：

aBrowsingContext (BrowsingContext) – actor 所在的 browsing context。
aMessageName (string) – 要发送到 actor 的消息的名称。
aMessageData (object) – 要传递给 actor 的额外信息。

static BrowserTestUtils.simulateProcessLaunchFail(browser)¶

尝试通过崩溃浏览器来模拟启动失败，但会剥夺浏览器的 childID，以便 TabCrashHandler 认为这是一个启动失败。

参数：

浏览器 – (<xul:browser>) 要在其上模拟内容进程启动失败的浏览器。

返回值：

Promise

static BrowserTestUtils.startLoadingURIString(browser, uri)¶

在给定的浏览器中启动加载新的 URI，由系统主体触发。请注意，这不会等待加载完成。为此，您可以使用 BrowserTestUtils.browserLoaded()、BrowserTestUtils.waitForErrorPage() 或创建自己的处理程序。

参数：

browser (xul:browser) – 一个 xul:browser。
uri (字符串) – 要加载的 URI。

static BrowserTestUtils.startObservingTopics(aBrowsingContext, aTopics)¶

开始在内容进程中观察主题列表。使用 contentTopicObserved 允许观察者通知。发生的任何其他与指定主题之一匹配的观察者通知都将导致 Promise 拒绝。

多次调用此函数会添加其他要观察的主题，而不会替换现有的主题。

参数：

aBrowsingContext (BrowsingContext) – 与要监听的内容进程关联的浏览上下文。
aTopics (Array.<String>) – 观察者主题数组

返回值：

Promise – 在添加侦听器后解析。

static BrowserTestUtils.stopObservingTopics(aBrowsingContext, aTopics)¶

停止侦听一组观察者主题。

参数：

aBrowsingContext (BrowsingContext) – 与要监听的内容进程关联的浏览上下文。
aTopics (Array.<String>) – 观察者主题数组。如果为空，则删除当前正在侦听的所有主题。

返回值：

Promise – 如果发生意外的观察者，则此 Promise 会失败。

static BrowserTestUtils.switchTab(tabbrowser, tab)¶

切换到一个标签页并在准备好后解析。

参数：

tabbrowser (tabbrowser) – tabbrowser。
tab (tab) – 要切换到的标签页元素或执行切换的功能。

返回值：

Promise – 切换到标签页后解析。

static BrowserTestUtils.synthesizeComposition(event, browsingContext)¶

EventUtils 的 synthesizeComposition 函数的版本；它将在子进程中合成一个合成事件，并返回一个 Promise，该 Promise 在事件触发时解析。需要将浏览器或浏览上下文而不是窗口传递给此函数。

参数：

event (对象) – 请参阅 EventUtils#synthesizeComposition 提供的文档。
browsingContext (BrowserContext|MozFrameLoaderOwner) – Browsing context 或浏览器元素，不得为 null

返回值：

Promise –

static BrowserTestUtils.synthesizeCompositionChange(event, browsingContext)¶

EventUtils 的 synthesizeCompositionChange 函数的版本；它将在子进程中合成一个 compositionchange 事件，并返回一个 Promise，该 Promise 在事件触发时解析。需要将浏览器或 Browsing Context 对象而不是窗口传递给此函数。

参数：

event (对象) – 请参阅 EventUtils#synthesizeCompositionChange 提供的文档。
browsingContext (BrowserContext|MozFrameLoaderOwner) – Browsing context 或浏览器元素，不得为 null

返回值：

Promise –

static BrowserTestUtils.synthesizeKey(key, event, browsingContext)¶

EventUtils 的 synthesizeKey 函数的版本；它将在子进程中合成一个键盘事件，并返回一个 Promise，该 Promise 在事件触发时解析。需要将浏览器或浏览上下文而不是窗口传递给此函数。

参数：

key (字符串) – 请参阅 EventUtils#synthesizeKey 提供的文档。
event (对象) – 请参阅 EventUtils#synthesizeKey 提供的文档。
browsingContext (BrowserContext|MozFrameLoaderOwner) – Browsing context 或浏览器元素，不得为 null

返回值：

Promise –

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

EventUtils.sys.mjs synthesizeMouse 函数的版本，用于在子进程中合成: 鼠标事件并返回 Promise，这些 Promise 在事件触发并完成时解析。需要将浏览器或浏览上下文而不是窗口传递给此函数。

参数：

target – 以下之一： - 用于识别要定位元素的选择器字符串。语法与 querySelector 相同。 - 要在内容进程中运行以返回要定位元素的功能 - null，在这种情况下，偏移量来自内容文档的边缘。
offsetX (整数) – 相对于目标左侧边界的 x 偏移量
offsetY (整数) – 相对于目标顶部边界的 y 偏移量
event (对象) – 对象其他参数，类似于 EventUtils.sys.mjs 版本
browsingContext (BrowserContext|MozFrameLoaderOwner) – Browsing context 或浏览器元素，不得为 null
handlingUserInput (布尔值) – 是否应在模拟用户交互时执行合成（使 windowUtils.isHandlingUserInput 为 true）。

返回值：

Promise –

static BrowserTestUtils.synthesizeMouseAtCenter()¶

使用目标中心作为鼠标的 synthesizeMouse 版本: 位置。参数和返回值相同。

static BrowserTestUtils.synthesizeMouseAtPoint()¶

使用子窗口内的客户端点而不是目标作为偏移量的 synthesizeMouse 版本。: 否则，参数和返回值与 synthesizeMouse 相同。

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

EventUtils.sys.mjs synthesizeTouch 函数的版本，用于在子进程中合成: 触摸事件并返回 Promise，这些 Promise 在事件触发并完成时解析。需要将浏览器或浏览上下文而不是窗口传递给此函数。

参数：

target – 以下之一： - 用于识别要定位元素的选择器字符串。语法与 querySelector 相同。 - 要在内容进程中运行以返回要定位元素的功能 - null，在这种情况下，偏移量来自内容文档的边缘。
offsetX (整数) – 相对于目标左侧边界的 x 偏移量
offsetY (整数) – 相对于目标顶部边界的 y 偏移量
event (对象) – 对象其他参数，类似于 EventUtils.sys.mjs 版本
browsingContext (BrowserContext|MozFrameLoaderOwner) – Browsing context 或浏览器元素，不得为 null

返回值：

Promise –

static BrowserTestUtils.waitForAttribute(attr, element, value)¶

返回一个 Promise，当元素获得属性（或可选地，当它设置为 value 时）时解析。

参数：

attr (字符串) – 要等待的属性
element (元素) – 应该获得该属性的元素
value (字符串) – （可选）可选，属性应具有的值。

返回值：

Promise –

static BrowserTestUtils.waitForAttributeRemoval(attr, element)¶

返回一个 Promise，当元素失去属性时解析。

参数：

attr (字符串) – 要等待的属性
element (元素) – 应该失去该属性的元素

返回值：

Promise –

static BrowserTestUtils.waitForBrowserStateChange(browser, expectedURI, checkFn)¶

等待与此标签关联的 Web 进度侦听器触发与顶级文档的 checkFn 匹配的状态更改。

参数：

browser (xul:browser) – 一个 xul:browser。
expectedURI (String) – (可选) 要检查通道加载的特定 URL
checkFn (函数) – 如果 checkFn(aStateFlags, aStatus) 返回 false，则忽略状态更改，我们继续等待。

返回值：

Promise –

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

类似于 waitForEvent，但将事件侦听器添加到浏览器的消息管理器全局。

参数：

eventName (string) – 要监听的事件的名称。
capture (布尔值) – [可选] 是否使用捕获侦听器。
checkFn (函数) – [可选] 使用事件对象作为参数调用，如果事件是预期的事件，则应返回 true，否则应返回 false，并且侦听应继续。如果未指定，则具有指定名称的第一个事件会解析返回的 Promise。
wantUntrusted (布尔值) – [可选] 是否接受不受信任的事件

返回值：

Promise –

static BrowserTestUtils.waitForDateTimePickerPanelShown(win)¶

等待日期时间选择器弹出窗口显示。

参数：

win (Window) – 期望弹出窗口所在的窗口。

返回值：

Promise – 弹出窗口完全打开后解析。解析值为选择弹出窗口。

static BrowserTestUtils.waitForDialogClose(dialog)¶

等待包含 id 为 window-modal-dialog 的对话框变为空并关闭。

参数：

dialog (HTMLDialogElement) – 要等待的对话框。

返回值：

Promise – 对话框关闭后解析

static BrowserTestUtils.waitForDocLoadAndStopIt(expectedURL, browser, checkFn)¶

等待当前浏览器中下一个顶级文档加载。文档的 URI 与 expectedURL 进行比较。然后在加载实际开始之前停止加载。

参数：

expectedURL (string) – 预期加载的文档的 URL。
browser (object) – 要等待的浏览器。
checkFn (function) – (可选) 在停止通道之前在其上运行的函数。

返回值：

Promise –

static BrowserTestUtils.waitForErrorPage(browser)¶

类似于 browserLoaded，但等待错误页面出现。

参数：

browser (xul:browser) – 一个 xul:browser。

返回值：

Promise –

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

等待在指定元素上触发事件。

参数：

subject (Element) – 应该接收事件的元素。
eventName (string) – 要监听的事件的名称。
capture (bool) – 为 true 表示使用捕获监听器。
checkFn (function) – 使用 Event 对象作为参数调用，如果事件是预期事件则应返回 true，否则如果应忽略它并且监听应该继续则返回 false。如果未指定，则第一个具有指定名称的事件将解析返回的 promise。
wantsUntrusted (bool) – 为 true 表示接收由 Web 内容分派的合成事件。

返回值：

Promise –

示例

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

等待在给定浏览器窗口的全局 <xul:notificationbox> 中出现具有特定值的 <xul:notification>。

参数：

win (Window) – 预期在其中显示通知的浏览器窗口的全局 notificationbox。
notificationValue (String) – 通知的值，通常用作唯一标识符。例如：“captive-portal-detected”。

返回值：

Promise – 解析为正在显示的 <xul:notification>。

static BrowserTestUtils.waitForLocationChange(tabbrowser, url)¶

等待 onLocationChange。

参数：

tabbrowser (tabbrowser) – 要等待其位置更改的 tabbrowser。
url (string) – 要查找的字符串 URL。URL 必须与地址栏中的 URL 完全匹配。

返回值：

Promise –

static BrowserTestUtils.waitForMessage(messageManager, message, checkFn)¶

等待从特定消息管理器触发消息

参数：

messageManager (nsIMessageManager) – 应该使用的消息管理器。
message (String) – 我们正在等待的消息。
checkFn (function) – (可选) 用于检查消息的可选函数。

static BrowserTestUtils.waitForMigrationWizard(window)¶

此测试的辅助函数，它返回一个 Promise，该 Promise 在迁移向导出现后解析。

参数：

window (DOMWindow) – 如果启用了新的迁移向导，则 about:preferences 选项卡可能会在其中打开的顶级窗口。

返回值：

Promise.<Element> – 解析为打开的 about:preferences 选项卡，其中迁移向导正在运行并已加载。

static BrowserTestUtils.waitForMutationCondition(target, options, checkFn)¶

等到 DOM 突变导致 checkFn 中表达的条件通过。

旨在作为 waitForCondition 的易于使用的替代方案。

参数：

target (Element) – 要在其中观察突变的目标。
options (Object) – 传递给 MutationObserver.observe() 的选项；
checkFn (function) – 当它希望 promise 解析时返回 true 的函数。

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

等待选项卡打开并加载给定 URL。

默认情况下，此方法不会等待选项卡内容加载。

参数：

tabbrowser (tabbrowser) – 要在其中查找下一个新选项卡的 tabbrowser。
wantLoad (string|function) – 如果是函数，则获取 URL 并返回 true（如果那是我们感兴趣的加载）。如果是字符串，则提供我们感兴趣的加载的 URL。如果不存在，则使用第一个非 about:blank 加载。
waitForLoad (boolean) – 为 true 表示等待新选项卡中的页面加载。默认为 false。
waitForAnyTab (boolean) – 为 true 表示等待 URL 在任何新选项卡中加载，而不仅仅是打开的下一个选项卡。
maybeErrorPage (boolean) – 请参阅 browserLoaded 函数。

返回值：

Promise –

static BrowserTestUtils.waitForNewWindow(aParams)¶

等待下一个浏览器窗口打开并完全加载。

参数：

aParams (Object)
aParams.url (string) – 要等待加载的 url。如果未设置，则根据 waitForAnyURLLoaded 参数，这可能会或可能不会等待任何页面加载。
aParams.waitForAnyURLLoaded (bool) – 当 url 未设置时，这将控制是否等待任何初始 URL 加载。默认为 false，这意味着当此值解析时，初始浏览器可能已完成加载其第一个页面，也可能未完成。当 url 设置时，将忽略此值，因此始终等待加载。
aParams.anyWindow (bool)
aParams.maybeErrorPage (bool) – 请参阅 browserLoaded 函数。

返回值：

Promise – 当下一个 DOM 窗口打开并延迟启动观察者通知触发时解析的 Promise。

static BrowserTestUtils.waitForNotificationBar(tabbrowser, browser, notificationValue)¶

等待在传递的浏览器的 <xul:notificationbox> 中出现具有特定值的 <xul:notification>。

参数：

tabbrowser (xul:tabbrowser) – 托管应显示通知的浏览器的 gBrowser。对于大多数测试，这可能是 gBrowser。
browser (xul:browser) – 应该显示通知的浏览器。
notificationValue (String) – 通知的值，通常用作唯一标识符。例如：“plugin-crashed”。

返回值：

Promise – 解析为正在显示的 <xul:notification>。

static BrowserTestUtils.waitForPopupEvent(popup, eventSuffix)¶

类似于 waitForEvent，但作用于弹出窗口。它确保弹出窗口尚未处于预期状态。

参数：

popup (Element) – 应该接收事件的弹出窗口元素。
eventSuffix (string) – 预期接收的事件后缀，为“shown”或“hidden”之一。

返回值：

Promise –

static BrowserTestUtils.waitForSelectPopupShown(win)¶

等待选择弹出窗口显示。这是必需的，因为选择下拉菜单是延迟创建的。

参数：

win (Window) – 期望弹出窗口所在的窗口。

返回值：

Promise – 弹出窗口完全打开后解析。解析值为选择弹出窗口。

static BrowserTestUtils.waitForSessionStoreUpdate(tab)¶

返回一个 Promise，该 Promise 在给定选项卡的 SessionStore 信息更新且所有侦听器都已调用后解析。

参数：

tab (xul:tab) – 将被移除的选项卡。

返回值：

Promise –

static BrowserTestUtils.waitForTabClosing((tab))¶

返回一个 Promise，该 Promise 在选项卡开始关闭时解析。

参数：

(tab) – tab 将被移除的选项卡。

返回值：

(Promise)

static BrowserTestUtils.waitForTransition(element, timeout)¶

等待元素的 CSS 过渡完成。跟踪在此函数调用后开始的任何过渡，并在所有启动的过渡完成后解析。

参数：

element (Element) – 将过渡的元素。
timeout (Number) – 最多等待的时间（以毫秒为单位）。默认为 5 秒。

返回值：

Promise – 过渡完成后解析，或者如果超时则拒绝。

static BrowserTestUtils.windowClosed(win)¶

返回一个 Promise，该 Promise 在窗口完成关闭时解析。

参数：

win (Window) – 关闭的窗口。

返回值：

Promise – 提供的窗口完全关闭后解析。对于浏览器窗口，Promise 还将等待来自所有浏览器选项卡的所有最终 SessionStore 消息发送完成。

static BrowserTestUtils.withNewTab(options, taskFn)¶

在新的标签页中加载页面，执行一个任务，然后关闭标签页。

参数：

options (Object|String) – 如果这是一个字符串，则表示要打开的 URL，并且将在当前活动浏览器窗口中打开。
options.gBrowser (tabbrowser) – 对 tabbrowser 元素的引用，新标签页应在此处打开。
options.url (string) – 要加载的页面的 URL。
taskFn (function) – 表示将在标签页加载时执行的异步函数。传递给函数的第一个参数是对新标签页浏览器对象的引用。

返回值：

Any – 返回 taskFn 返回的值。