web-platform-tests¶

web-platform-tests 是一个跨浏览器的测试套件。将测试编写为 web-platform-tests 有助于确保所有浏览器对 web 平台功能都实现相同的行为。

上游文档¶

本文档涵盖了将 web-platform-tests 集成到 Firefox 代码树的过程。有关编写测试的文档，请参阅 web-platform-tests.org。特别是以下文档涵盖了常见的测试编写需求

Javascript 测试 (testharness.js)
- testharness.js API
- testdriver.js API - 用于编写需要特殊权限（例如用户发起的输入事件）的测试的功能。
- 消息通道 - 用于在不同全局对象之间进行通信的功能（包括不同浏览上下文组/进程中的全局对象）。
Reftests
Crashtests
服务器功能 - 例如多个来源、替换、服务器端 Python 脚本。

运行测试¶

可以使用 mach 运行测试。

mach wpt

要仅运行某些测试，请将这些测试作为附加参数传递给命令。例如，要包含 dom 目录中的所有测试

mach wpt testing/web-platform/tests/dom

也可以通过 ID 传递测试；这是路径加上 URL 的任何查询或片段部分，适合直接从日志（例如 Treeherder 上）复制

mach wpt /web-nfc/idlharness.https.window.html

单个文件可以生成多个测试，因此有时需要传递测试 ID 而不是路径才能准确地运行一个测试。

测试套件包含各种测试类型的混合，包括 Javascript (testharness) 测试、reftests 和 wdspec 测试。要限制要运行的测试类型，请使用 --test-type=<type>，例如 --test-type=reftest 用于 reftests。

请注意，如果只运行单个 testharness 测试，则浏览器默认情况下会保持打开状态（与 mochitest 的行为一致）。要防止这种情况，请将 --no-pause-after-test 传递给 mach wpt。

当源代码树配置为构建 Android 时，测试也将默认在 Android 上运行，使用本地模拟器。

在其他浏览器中运行测试¶

web-platform-tests 是跨浏览器的，并且运行器与多个浏览器兼容。因此，可以在其他浏览器中检查测试的行为。默认情况下，支持 Chrome、Edge 和 Servo。为了在这些浏览器中运行测试，请对 wptrunner 使用 --product 参数。

mach wpt --product chrome dom/historical.html

默认情况下，这些浏览器在没有预期元数据的情况下运行，但可以在 testing/web-platform/products/<product> 目录中添加元数据。要使用与 Firefox 相同的元数据运行（以便将差异报告为意外结果），请将 --meta testing/web-platform/meta 传递给 mach 命令。

许多浏览器的上游 CI 结果，包括 Chrome 和 Safari，都可以在 wpt.fyi 上获得。还有一个 gecko 仪表盘，默认情况下显示在 Gecko 中失败但在 Chrome 和 Safari 中未失败的测试，根据 wpt.fyi 数据按错误组件组织。

目录¶

在 testing/web-platform 下是以下目录

tests/: web-platform-tests 存储库的自动更新导入。对该目录的任何更改都会自动转换为针对上游存储库的拉取请求，并在通过 CI 后合并。
meta/: Gecko 特定的元数据，包括预期的测试结果和配置，例如在运行测试时设置的 prefs。这将在下一节中解释。
mozilla/tests: 不会上游的测试，可能会使用 Mozilla 特定的功能。它们可以访问 SpecialPowers API。
mozilla/meta: Mozilla 特定测试的元数据。

元数据¶

为了将共享测试套件与有关测试的 Firefox 特定元数据分开，所有元数据都存储在 meta/ 子目录中的单独的 ini 类文件中。

每个测试文件都有一个元数据文件，其中包含相关的 Gecko 特定数据。测试的元数据文件与测试文件具有相同的相对路径，并且具有 .ini 后缀，例如，对于 testing/web-platform/tests/example/example.html 中的测试，相应的元数据文件是 testing/web-platform/meta/example/example.html.ini。

这些文件的格式类似于 ini 文件，但有一些重要的区别；可以使用缩进嵌套节，并且仅允许 : 作为键值分隔符。例如

[filename.html]
    [Subtest 1 name]
        key: value

    [Subtest 2 name]
        key: [list, value]

对于单个文件生成多个测试（例如变体或 .any.js 测试）的情况，元数据文件为每个测试提供一个顶级节，例如

[test.any.html]
    [Subtest name]
        key: value

[test.any.worker.html]
    [Subtest name]
        key: other-value

可以使用类似 Python 的条件语法使值成为条件。

[filename.html]
    key:
        if os == "linux": linux-value
        default-value

条件的可用变量是 mozinfo 提供的变量，以及一些其他特定于 wpt 的值。

有关清单文件的更多信息，请参阅 wptrunner 文档

预期数据¶

在我们的 CI 中未通过的所有测试都将预期数据存储在元数据文件中，位于 expected 键下。例如，一个测试有一个失败的子测试和一个出错的子测试的预期文件可能如下所示

[filename.html]
    [Subtest name for failing test]
        expected: FAIL

    [Subtest name for erroring test]
        expected: ERROR

可以使用条件语法使预期成为特定于配置的。

[filename.html]
    expected:
        if os == "linux" and bits == 32: TIMEOUT
        if os == "win": ERROR
        FAIL

间歇性测试可以使用可能性列表标记多个状态，例如，对于一个通常通过但间歇性失败的测试

[filename.html]
    [Subtest name for intermittent test]
        expected: [PASS, FAIL]

自动生成预期数据¶

更改某些代码后，可能需要更新相关测试的预期数据。当然，这可以手动完成，但可以使用工具来自动化大部分流程。

首先，必须运行状态已更改的测试，并将原始日志输出保存到文件中

mach wpt /url/of/test.html --log-wptreport wptreport.json

然后，可以使用此日志数据运行 wpt-update 命令来更新预期文件

mach wpt-update wptreport.json

CI 运行还会生成可以作为工件下载的 wptreport.json 文件。当在多个平台上运行测试时，并且所有 wptreport 文件都一起处理时，工具将为任何特定于平台的结果设置适当的条件。

mach wpt-update logs/*.json

对于完整运行，--full 标志将在以下情况下导致元数据被删除：a) 测试已更新，并且 b) 存在与输入文件中的任何配置都不匹配的条件。

当测试运行多次时，--update-intermittent 标志会导致冲突的结果被标记为间歇性（否则在发生冲突的情况下不会更新数据）。

禁用测试¶

使用与设置预期值相同的清单文件禁用测试。例如，如果某个测试在 Windows 上不稳定，则可以使用内容为以下内容的 ini 文件禁用它

[filename.html]
    disabled:
        if os == "win": https://bugzilla.mozilla.org/show_bug.cgi?id=1234567

对于间歇性，通常最好为测试提供多个预期，而不是禁用它。

模糊 Reftests¶

测试与参考不完全匹配的 Reftests 可以标记为模糊。如果差异是测试固有的，则应将其编码在 meta 元素中，但如果是 Gecko 特定的差异，则可以使用相同的语法将其添加到元数据文件中

[filename.html]
    fuzzy: maxDifference=10-15;totalPixels=200-300

在这种情况下，我们预计会有 200 到 300 像素（含）的不同，并且任何 RGB 颜色通道的最大差异在 10 到 15 之间。

启用 Prefs¶

某些测试需要在运行之前启用特定的 prefs。这些 prefs 可以使用 prefs 键在预期数据中设置，该键包含以逗号分隔的 pref.name:value 项目列表

[filename.html]
    prefs: [dom.serviceWorkers.enabled:true,
            dom.serviceWorkers.exemptFromPerDomainMax:true,
            dom.caches.enabled:true]

禁用内存泄漏检查¶

当导入泄漏的测试时，可能需要暂时禁用该测试的内存泄漏检查，以允许导入继续进行。这与禁用测试的方式基本相同，但使用 leaks 键

[filename.html]
    leaks:
        if os == "linux": https://bugzilla.mozilla.org/show_bug.cgi?id=1234567

每个目录的元数据¶

有时需要为整个测试目录设置元数据，例如禁用所有测试或为每个测试启用 prefs。在这种情况下，可以在对应于要为其设置此元数据的测试的元数据目录中创建 __dir__.ini 文件，例如，要禁用 tests/feature/unsupported/ 中的所有测试，可以创建 meta/feature/unsupported/__dir__.ini，其内容如下

disabled: Feature is unsupported

以这种方式设置的设置将继承到子目录中。可以使用特殊标记 @Reset（通常与 prefs 一起使用）取消在父级中设置的值，或者使用 @True 和 @False 强制值设为 true 或 false。例如，要启用 meta/feature/unsupported/subfeature-supported 中的测试，可以创建类似于以下内容的 ini 文件 meta/feature/unsupported/subfeature-supported/__dir__.ini

disabled: @False

为发布分支设置元数据¶

运行信息属性可用于为发布分支设置与 nightly 不同的元数据（例如，当功能依赖于仅在 nightly 上设置的 prefs 时），例如

[filename.html]
  expected:
    if release_or_beta: FAIL

请注意，通常情况下，如果在条件语句中显式使用非标准配置，并将其放置在条件集的顶部，则自动元数据更新将效果更好，例如，以下操作会导致后续问题。

[filename.html]
  expected:
    if nightly_build: PASS
    FAIL

这是因为在导入时，自动元数据更新会针对夜间构建的结果运行，并且我们会删除与所有输入运行匹配的任何现有条件，以避免累积过时的配置选项。

测试清单¶

web-platform-tests 使用一个大型自动生成的 JSON 文件作为其清单。该文件存储有关测试类型、任何引用以及超时的数据，这些数据通过检查文件名和测试文件的内容收集而成。无需手动将新测试添加到清单中；在运行 mach wpt 时会自动保持其更新。

与上游同步¶

测试会使用 wpt-sync 机器人自动与上游同步。此操作执行以下任务

一旦 testing/web-platform/tests 中的更改进入 autoland，就会为其创建上游 PR，并在它们到达 mozilla-central 后自动合并它们。
通过 gecko CI 运行合并的上游 PR 以生成更新的预期元数据。
使用来自上游的更改更新 gecko 树中 web-platform-tests 的副本，以及使 CI 作业通过所需的预期元数据。

双向同步的特性意味着偶尔会出现合并冲突和其他问题。如果某些内容与您期望的上游不同步，请在 matritx 上的 #interop 上咨询。

wpt-serve¶

有时，最好单独运行 WPT 的 Web 服务器，并将不同的浏览器指向测试文件。

./mach wpt-serve

可以在简短的设置后使用它。

在 Unix 上，可以运行

./wpt make-hosts-file | sudo tee -a /etc/hosts

来自 WPT 检出的根目录，位于 testing/web-platform/tests/。

在 Windows 上，从管理员 mozilla-build shell 中，可以运行

./wpt make-hosts-file >> /c/Windows/System32/drivers/etc/host

来自 WPT 检出。

大多数情况下，浏览到 https://127.0.0.1:8000 将允许运行测试，尽管某些测试有特殊要求，例如在特定域上运行或使用 https 运行。