TPS¶
目录¶
本文档的大部分内容针对希望了解 TPS 和/或编写 TPS 测试的 Firefox 开发人员。如果您只想运行 TPS，请参阅如何运行 TPS部分。
什么是 TPS¶
TPS 是 Firefox Sync 的一个测试自动化框架。TPS 将测试配置作为定义在配置文件中的 JavaScript 文件输入，并按顺序运行所有测试。
每个 TPS 测试都由一个或多个阶段组成，每个阶段都有自己的断言并按顺序运行。如果**任何**阶段失败，则测试失败，并且不会运行剩余的阶段。但是，其他测试仍将运行。
TPS 存在的原因¶
TPS 针对真实的 Mozilla 账户服务器和 Sync 服务器运行，因此是端到端测试 Firefox Sync 的好方法，无需模拟服务器。
架构¶
高级别图¶
下图描述了运行 TPS 时的流程。
单个测试序列图¶
以下序列图描述了执行单个 TPS 测试时涉及的实体。
阶段¶
每个阶段都映射到一个 Firefox 配置文件，如果阶段映射到它们，则阶段可能会重复使用配置文件，有关映射的详细信息，请参阅phases 对象。所有阶段都登录到同一个 Mozilla 账户。
示例¶
例如，一个简单的测试定义了两个阶段，一个上传书签，另一个下载书签，可以描述如下，有关测试格式的详细信息，请参阅测试格式部分。
EnableEngines(["bookmarks"]); // Enables the bookmark engine across all profiles(phases) that this test runs
/*
* The list of phases mapped to their corresponding profiles. The object
* here must be in JSON format as it will get parsed by the Python
* testrunner. It is parsed by the YAML package, so it relatively flexible.
*/
var phases = {
phase1: "profile1",
phase2: "profile2",
};
// the initial list of bookmarks to add to the browser
var bookmarksInitial = {
menu: [
{ folder: "foldera" },
{ folder: "folderb" },
],
"menu/foldera": [{ uri: "http://www.cnn.com", title: "CNN" }], // One bookmark in menu/foldera pointing to CNN
"menu/folderb": [{ uri: "http://www.apple.com", title: "Apple"}], // One bookmark in menu/folderb pointing to apple
};
// Add bookmarks to profile1 and sync.
Phase("phase1", [
[Bookmarks.add, bookmarksInitial],
[Bookmarks.verify, bookmarksInitial],
[Sync],
[Bookmarks.verify, bookmarksInitial],
]);
// Sync, then verify that bookmarks added by phase 1 are present.
Phase("phase2", [
[Sync],
[Bookmarks.verify, bookmarksInitial],
]);
TPS 扩展¶
当表示阶段的 Firefox 配置文件加载时，它首先安装一个扩展。扩展通过指示 Firefox 并从 Firefox 读取来断言 Sync 是否正常工作，从而执行测试。
测试文件在扩展中执行，并且扩展定义了测试文件可以使用的所有函数。例如，在上面的示例中，Phase函数定义在此处
测试格式¶
测试组配置¶
测试由一个json文件引用，该文件引用了 TPS 将运行的所有测试。默认情况下，TPS 将运行services/sync/tests/tps/all_tests.json中的配置。测试组配置是一个json对象，其中一个键名为tests，它本身是一个json对象。tests对象为要运行的每个测试提供一个键，并且键应为测试文件的名称。如果测试应运行，则每个测试文件的值为空对象{}，或者{"disabled": "Bug <BUG NUMBER>"}，其中<BUG NUMBER>是 Bugzilla 错误编号，引用了禁用测试的原因。
测试文件¶
phases 对象¶
测试文件是 JavaScript 文件，加载 Firefox 配置文件后，TPS 扩展将运行这些文件。但是，在此之前，TPS 框架将加载测试文件中定义的第一个对象作为yaml。换句话说，对于以下示例
var phases = {
phase1: "profile1",
phase2: "profile2",
phase3: "profile1", // phase 1 and 3 reuse the same profile, "profile1"
}
// ... rest of the test file
大括号内的内容将被解析为 yaml 以识别 TPS 将运行的配置文件并将每个阶段映射到一个配置文件。在上面的示例中，phase1和phase3重复使用相同的配置文件，但phase2使用它自己的配置文件。文件的其余部分是将在TPS 扩展中加载的常规 JavaScript。
测试文件功能¶
TPS 扩展导出了一组测试文件可以使用函数和对象。有关最新详细信息，请参阅tps.sys.mjs，以下截至 2024 年 4 月 10 日的导出功能列表
启用 Sync 引擎¶
要启用 Sync 引擎（在执行依赖于引擎的测试之前，您应该执行此操作），请使用EnableEngines函数。该函数采用表示引擎名称的字符串数组。例如
EnableEngines(["bookmarks", "history"]);
启动阶段¶
阶段按它们在phases 对象中声明的顺序在其分配的配置文件中运行。要定义阶段的作用，请使用Phase函数，该函数将阶段名称作为第一个参数 - **这应该与phases 对象中定义的名称相同** - 并将操作的二维数组作为第二个参数。二维数组中的每个操作数组都按顺序运行。内部数组定义操作是什么以及该操作的任何参数。例如
Phase("phase1", [[Sync], [Bookmarks.add, bookmarkInitial]]);
请注意，该示例假设 phases 对象和 bookmarkInitial在测试文件中定义。
在上面的示例中
"phase1"是阶段的名称，应与phases 对象中定义的阶段名称完全匹配。作为第二个参数传递的二维数组具有
[Sync]作为其第一个数组，这意味着该阶段将首先进行同步。[Bookmarks.add, bookmarkInitial]作为其第二个成员，这意味着在同步之后，将运行 Bookmarks.add 操作，它将添加bookmarkInitial。
操作¶
操作在阶段内作为Phase函数的参数运行。
常规操作¶
有一些与数据类型无关的常规操作。
Sync：将触发同步。Login：登录到 Mozilla 账户。**在大多数情况下，您不需要执行此操作，因为它会自动完成。**WipeServer：将从服务器擦除所有数据。EnsureTracking：将等待直到同步跟踪开始。**在大多数情况下，您不需要执行此操作。**
特定于数据类型操作¶
某些操作受单个数据类型的支持。这些操作通过使用<DataType>.<Action>触发。以下是所有可能的<DataType>值列表：有关哪些操作受哪些数据类型支持的更多详细信息，请参阅以下部分。
书签标签页表单数据历史记录密码附加组件地址信用卡扩展存储首选项窗口
书签操作
在test_existing_bookmarks.js中的示例
add：添加书签树。modify：修改现有的书签树。delete：从树中删除书签节点。verify：验证书签树是否与给定的树完全匹配，否则阶段失败。verifyNot：verify 的反义词，如果书签树与给定的树匹配，则阶段失败。skipValidation：告诉 Firefox 停止验证书签树。
地址操作
在test_addresses.js中的示例
add：添加地址数组。modify：将地址列表修改为给定的内容。delete：删除给定的地址。verify：验证地址是否与给定的列表完全匹配，否则阶段失败。verifyNot：verify 的反义词，如果地址列表与给定的列表匹配，则阶段失败。
信用卡操作
在test_creditcards.js中的示例
add：添加信用卡数组。modify：将信用卡列表修改为给定的内容。delete：删除给定的信用卡。verify：验证信用卡是否与给定的列表完全匹配，否则阶段失败。verifyNot: 如果信用卡列表与给定列表匹配，则此操作与 verify 相反，导致阶段失败。
附加组件操作
installs: 安装附加组件列表。setEnabled: 启用或禁用附加组件列表。uninstall: 卸载附加组件列表。verify: 验证附加组件是否完全与给定列表匹配，否则导致阶段失败。verifyNot: 此操作与 verify 相反，如果附加组件列表与给定列表匹配，则导致阶段失败。skipValidation: 指示 Firefox 停止验证附加组件。
表单数据操作
示例见 test_formdata.js
add: 添加表单数据数组。delete: 删除给定的表单数据。verify: 验证表单数据是否完全与给定列表匹配，否则导致阶段失败。verifyNot: 此操作与 verify 相反，如果表单数据与给定列表匹配，则导致阶段失败。
历史记录操作
示例见 test_history.js
add: 添加历史记录项数组。delete: 删除给定的历史记录项。verify: 验证表单数据是否完全与给定列表匹配，否则导致阶段失败。verifyNot: 此操作与 verify 相反，如果表单数据与给定列表匹配，则导致阶段失败。
密码操作
add: 添加登录列表。modify: 根据给定列表中的更改修改现有的登录列表。delete: 删除登录列表。verify: 验证登录列表是否完全与给定列表匹配，否则导致阶段失败。verifyNot: 此操作与 verify 相反，如果登录信息与给定列表匹配，则导致阶段失败。skipValidation: 指示 Firefox 停止验证登录信息。
首选项操作
示例见 test_prefs.js
modify: 根据给定列表中的更改修改现有的首选项。verify: 验证给定首选项的值是否与给定值匹配，否则导致阶段失败。
标签页操作
示例见 test_tabs.js
add: 添加新的远程标签页列表，每个标签页都标注了它所属的配置文件。verify: 验证远程标签页的值是否与给定列表匹配，否则导致阶段失败。
窗口操作
add: 使用给定的配置添加一个新窗口。
扩展存储操作
set: 将给定键的值设置为给定值。verify: 验证给定键的值是否为给定值，否则导致阶段失败。
编写新的 TPS 测试¶
要编写新的 TPS 测试，请按照以下说明操作
如何运行 TPS¶
安装¶
TPS 需要几个软件包才能正常运行。要安装 TPS 和所需的软件包，请使用 testing/tps 目录中提供的 create_venv.py 脚本。
python3 create_venv.py /path/to/create/virtualenv
此脚本将创建一个虚拟环境并在其中安装 TPS。
然后，您必须通过执行以下操作激活虚拟环境：
(mac/linux)
source /path/to/virtualenv/Scripts/activate
(win)
/path/to/virtualenv/Scripts/activate.bat
然后可以通过执行以下操作运行 TPS：
runtps --binary=/path/to/firefox
注意：您可以使用
MOZ_HEADLESS=1在无头模式下运行 tps 测试。这将在测试运行时使您的计算机在一定程度上可用。
完成 TPS 后，可以通过执行 deactivate 来停用虚拟环境。
配置¶
要编辑 TPS 配置，请不要编辑树中的 config/config.json.in。相反，请编辑虚拟环境中的 config.json；它将位于您指定创建虚拟环境的顶层 - 例如，对于上面的示例，它将是 /path/to/create/virtualenv/config.json
设置测试账户¶
Mozilla 账户¶
要创建用于使用 Mozilla 账户身份验证的测试账户，请执行以下步骤
注意：目前，TPS 测试依赖于 restmail 如何返回验证码。您应该使用 restmail 或非常类似的东西。Gmail 和其他提供商可能会给出
The request was blocked for security reasons
转到 URL：http://restmail.net/mail/%account_prefix%@restmail.net
将
%account_prefix%替换为您自己的测试名称。
转到 https://accounts.firefox.com/signup?service=sync&context=fx_desktop_v1
使用之前选择的电子邮件地址和密码登录。
返回 Restmail URL，重新加载页面。
搜索验证链接并打开该页面。
现在，您就可以使用此账户进行 TPS 了。请注意，这些步骤可以在测试配置文件或隐私浏览窗口中完成 - 您可能希望避免在已连接到同步的“真实”配置文件中执行此操作。