测试¶

本文档讨论了如何为地址栏编写测试以及编写地址栏测试时有哪些有用的不同测试实用程序。

常见测试¶

Mochitests¶

地址栏的一些常见测试是 **mochitests**。mochitest 的目的是运行浏览器本身。Mochitests 可以称为“浏览器测试”、“mochitest-browser-chrome”或“browser-chrome-mochitests”。还有其他类型的 mochitests 不是用于测试浏览器，因此在地址栏的用途上可以忽略它们。mochitest 的一个示例是 tests/browser/browser_switchTab_currentTab.js

XPCShell¶

XPCShell 测试是另一种与地址栏相关的测试类型。XPCShell 测试通常称为单元测试，因为它们倾向于单独测试特定的模块或组件，而不是 mochitest，后者可以访问完整的浏览器 chrome。

XPCShell 测试不使用浏览器 UI，并且与浏览器 chrome 完全分离。XPCShell 测试在浏览器外部的 JavaScript shell 中执行。从历史背景来看，“XPC”命名约定来自 XPCOM（跨平台组件模型），这是一个较旧的框架，允许程序员用一种语言（如 C++）编写自定义函数，并将其连接到另一种语言（如 JavaScript）中的其他组件。

每个 XPCShell 测试都在一个新的 shell 实例中执行，因此当 XPCShell 测试正在执行时，您将看到几个 Firefox 图标弹出并关闭。以下是地址栏的两个 XPCShell 测试示例：test_providerHeuristicFallback 和 test_providerTabToSearch。

何时编写 XPCShell 或 Mochitest？¶

如果可能，始终默认编写 XPCShell 测试。XPCShell 测试的执行速度比浏览器测试快。尽管如此，大多数情况下您都会编写浏览器测试，因为您可能会修改 UI 中的内容或测试 UI 中的特定组件。

如果您正在为 urlbarProvider 编写测试，则可以通过 XPCShell 测试来测试 Provider。Provider 不会修改 UI，而是接收 url 字符串查询，搜索字符串并返回结果。例如，ProviderPlaces，它从书签数据库中获取结果。另一个适合编写 XPCShell 测试的组件是 urlbarMuxer。

有时可能需要同时编写 XPCShell 测试和浏览器测试。在这些情况下，您可能正在测试 Provider 的结果，以及测试 UI 中显示的内容是否正确。

如何编写测试¶

测试样板¶

此基本测试样板在顶部包含许可证代码，并且此许可证代码存在于每个测试文件的顶部，"use strict" 字符串用于在 JavaScript 中启用严格模式，以及 add_task 函数添加要由测试框架执行的测试。

/* Any copyright is dedicated to the Public Domain.
 * http://creativecommons.org/publicdomain/zero/1.0/ */

/**
 * This tests ensures that the urlbar ...
 */

"use strict";

add_task(async function testOne() {
  // testing code and assertions
});

add_task(async function testTwo() {
  // testing code and assertions
});

为了运行测试，请使用 ./mach 命令，例如，./mach test <path to test file> 在本地运行测试。在末尾使用带有 --jsdebugger 参数的命令以打开 DevTools 调试器来逐步执行测试，./mach test <path to test> --jsdebugger。

清单¶

清单的目的是列出目录中的所有测试，并指示测试框架哪些文件是测试以及测试框架应如何运行这些测试。每当创建测试时，都需要按字母顺序将测试文件名添加到清单中。

从清单文件开始，并按字母顺序添加您的测试名称。我们应该在其中添加测试的清单文件是 browser.ini。 urlbar/test/browser/ 目录是地址栏的主要浏览器测试目录，上面链接的清单文件是主要浏览器测试清单。 .ini 文件扩展名是 Windows 或 MS-DOS 的初始化文件。

清单元数据¶

清单文件可以定义公共键/元数据来影响测试的行为。例如，元数据 support-files 是运行测试所需的额外文件的列表。分配给键 support-files 的任何值仅适用于 support-files 键正上方的单个文件。如果更多文件需要 support-files，则需要在其他测试文件名下方直接添加 support-files。清单元数据的另一个示例是 [DEFAULT]。 [DEFAULT] 下的任何内容都将被清单文件中的所有测试获取。

有关所有可用清单元数据的信息，请访问测试清单。

常见测试实用程序¶

本节描述了一些在编写地址栏测试时可能很有用的常见测试实用程序。以下是您可以找到有帮助的测试方法的常见实用程序的描述。

许多测试实用程序模块以 TestUtils.sys.mjs 结尾。但是，并非每个测试函数都以 TestUtils.sys.mjs 结尾。例如，PlacesUtils 的名称中没有“Test”。

需要记住的一个关键函数是下面提到的 head.js 文件中的 registerCleanupFunction。此函数的目的是清理历史记录或测试完成后所需的任何其他清理。清理浏览器测试后是必要的，因为清理可以确保在一个测试中完成的操作不会影响后续测试。

head.js 和 common-head.js¶

head.js 文件在每个测试开始之前执行，并包含对每个测试都有用的模块的导入。 head.js 添加的任何任务（通过 add_task）将首先针对每个测试运行，并且它定义的任何变量和函数都将在每个测试的范围内可用。此文件很小，因为我们的大多数 Utils 实际上都在其他 .sys.mjs 文件中。

head.js 中的 XPCOMUtils.defineLazyModuleGetters 方法将模块名称设置到它们可以找到的位置，即它们的路径。 Lazy 意味着仅在使用时或使用时才导入文件。此目录中的任何测试都可以使用这些模块，而无需在其自己的文件中导入它。 head.js 为此目的提供了一个便利。 head.js 文件导入 common-head.js，使 head-common.js 中的所有内容也可在 head.js 中使用。

在浏览器 mochi 测试中，registerCleanupFunction 是一个重要的函数，它是测试框架的一部分。此函数注册一个回调函数，在测试完成后执行。其目的是清理历史记录或测试完成后所需的任何其他清理操作。例如，浏览器 mochi 测试在一个窗口实例中按顺序执行。每个测试中的全局对象都是浏览器 window 对象，例如，每个测试脚本都在浏览器窗口中运行。如果未清理历史记录，它将保留并可能影响后续的浏览器测试。对于地址栏之外的大多数测试，您可能不需要清除历史记录。除了清理之外，head.js 调用 registerCleanupFunction 以确保每个测试后 urlbar 面板关闭。

UrlbarTestUtils¶

UrlbarTestUtils.sys.mjs 对于 url 栏测试很有用。此文件包含可帮助在 url 栏中启动新搜索、等待新搜索完成、返回视图中的结果等的方法。

BrowserTestUtils¶

BrowserTestUtils.sys.mjs 对于浏览器窗口测试很有用。此文件包含可帮助打开选项卡、等待窗口中发生特定事件、打开新的或私有窗口等的方法。

TestUtils¶

TestUtils.sys.mjs 对于通用测试很有用，并且不依赖于浏览器窗口。此文件包含在等待条件返回 true、等待特定首选项更改等时有用的方法。

PlacesTestUtils¶

PlacesTestUtils.sys.mjs 对于添加访问、添加书签、等待已访问页面的通知等很有用。

EventUtils¶

EventUtils.js 是一个较旧的测试文件，不需要导入，因为它不是 .sys.mjs 文件。EventUtils 仅用于浏览器测试，与上面列出的其他 TestUtils 用于浏览器测试、XPCShell 测试和其他测试不同。

EventUtils.js 中的所有函数在浏览器测试中都可以自动使用。此文件包含可用于合成鼠标点击和按键的功能。一些常用的函数是 synthesizeMouseAtCenter，它将鼠标放置在 DOM 元素的中心，以及 synthesizeKey，它可用于通过使用 keydown 和 keyenter 参数来导航视图并启动搜索。