语言简体中文

测试

在桌面端打开 工作区工具 → 测试,或在移动端打开 工具 → 测试,然后 选择项目。测试页面会以文本方式读取项目中的测试文件,并显示找到的每个测试:文件夹、文件、测试名称以及每个测试周围的代码。 读取过程从不运行、导入或安装任何内容;只有在您选择运行时,测试才会运行。

页面顶部有一条状态行和两张卡片。单元测试 和 回归测试 卡片分别显示最近一次运行中通过的测试数量、失败或不稳定的测试、近期的运行记录,以及 运行 按钮。 卡片下方是一个标签栏,包含 单元测试、回归测试、集成与 E2E、检查(lint、类型、构建和验证脚本)和 历史记录。

读懂状态行

卡片上方的状态行会根据测试的最新结果,先给出结论:

  • 还没有运行过任何测试时,显示 尚未检查。运行一次测试,即可了解项目的现状。
  • 有测试失败时,状态行会显示失败的数量和 查看失败项:失败的测试会以 失败 筛选条件打开;如果某个已修复的缺陷再次出现,对应的回归测试会排在最前。
  • 有不稳定的测试(先失败、重试后才通过)时,状态行会显示其数量和 查看不稳定的测试。
  • 其他情况下,状态行会显示通过的测试数量、尚未运行的测试数量,以及上次运行结束的时间。

计数包括单元测试、集成测试与端到端测试,以及检查。回归测试复用的正是这些测试,因此不会重复计数。

在 自动运行 按钮旁,状态行还会显示 下次自动运行 及其时间,或显示 自动运行已关闭。如果上次自动运行未能开始,状态行会说明原因。

查看测试

每个标签页按文件夹对测试文件分组。打开文件夹即可查看其中的文件,然后选择一个文件:其测试会显示在右侧(在手机上则显示在单独的屏幕中),失败的测试排在最前。 失败的测试会显示测试运行器报告的预期值和实际值,以及失败行周围的当前代码。 可按 失败、不稳定 或 尚未运行 筛选,也可按文件名或文件夹名称搜索。

从未运行过的测试显示为 尚未运行。只要有测试失败,通过率圆环就绝不会显示 100%。 每种状态都同时用图标和文字表示,而不只是靠颜色。

测试页面会自动为文件分类:单元测试,集成测试与端到端测试(例如 e2e、integration、routes 或 api 等文件夹、Playwright 文件和网页场景),以及检查。 检查包括 lint、类型检查、构建以及项目中的验证脚本,名称带有后缀的脚本也包括在内,例如 contrast:ui-check 或 tabs:guard。 如果某个文件夹的分类有误,请打开它的 ⋯ 菜单,然后选择 移至单元测试 或 移至集成与 E2E。

运行测试

选择 运行单元测试、运行回归测试、文件夹或文件的运行按钮,或其详情中的 运行文件。 无需事先配置:测试页面会根据项目中已在运行这些文件的脚本(保留其选项)或测试运行器的默认命令生成命令,保存后随即启动。 运行报告随之打开,显示进度和 停止 按钮。关闭应用不会停止运行;实例会保留结果。

一组测试运行期间,顶部的状态行会显示进度,并提供 查看进度(重新打开正在进行的运行)和 停止(停止整组测试:仍在等待的运行不会开始)。离开测试后再回来,进度仍然在。整组结束前,运行单元测试 会显示 正在运行…,因此再次点击不会把同样的测试启动两次。如果实例上缺少某个测试工具(例如 pytest),只有它的测试会显示为未开始,其他测试照常运行。

已保存的命令仍可编辑:通过 ⋯ → 编辑命令 可以更改其可执行文件、参数、层级、前置条件、服务、测试数据和时限。

选择同时运行多少个测试文件

状态行旁的 同时运行的测试文件 设置项目中同时运行多少个测试文件。默认的 自动 保留每个测试工具自己的设置。选择一个数字(最多为实例的处理器数量)后,项目的每次运行(无论手动还是自动)最多同时运行这么多文件:Node、Vitest、Jest 和 Playwright 会遵循它,其他测试工具保留自己的设置,项目的运行随后依次进行。已经开始的运行保留开始时的数字。

测试始终以低于实例的处理器优先级运行,因此测试运行期间,您的会话和应用仍能保持响应。只有您可以更改此设置:应用内助手可以按您的要求读取或修改它,项目中的会话绝不会修改它。

按计划运行测试

选择状态行旁的 自动运行,即可让项目的测试按自己的计划运行。每个项目有一个计划:

  • 自动运行测试:开启或关闭该计划。
  • 重复:每小时、每天、工作日、每周、每月,或自定义 cron 表达式。两次运行之间至少间隔 15 分钟。
  • 时区:计划所依据的时区。系统会优先提供您的显示时区;之后更改显示时区,不会改变已保存计划的运行时间。
  • 运行内容:从 单元测试、回归测试、集成与 E2E 和 检查 中至少选择一项。
  • 通知我:选择 仅在出现失败时(默认)时,通过的运行不会发出通知,而失败、中断或需要审核的运行仍会通知您;选择 每次运行后 时,每次都会通知。
  • 错过的运行:如果到了计划时间实例处于关闭状态,实例恢复运行后运行一次(默认)会在实例恢复后只补运行一次,无论错过了多少次;跳过错过的运行 则等待下一个计划时间。

自动运行就是普通的运行:它会更新卡片和状态行,并连同报告显示在 历史记录 中。它绝不会与上一次自动运行重叠。内存紧张或正在更新时,它会等待并重试,最长两小时,且绝不会被算作失败。 如果自动运行无法开始,例如上一次仍在进行、项目需要检查或没有可运行的内容,状态行会说明原因,下一个计划时间照常运行。某类测试没有可运行的内容时,不会影响其他类别。更新或恢复之后,自动运行会自行恢复;期间错过的计划时间按照您在 错过的运行 中的选择处理。

只有您可以设置计划:应用内助手可以按您的要求读取或修改计划;项目中的会话可以读取计划,但绝不会创建或修改计划。

创建测试

选择右上角的 新建测试:

  • 用 AI 编写测试:描述一项行为;AI 会提出测试,您在保存前进行审阅。在您运行之前,不会运行任何内容。
  • 保护已修复的缺陷:根据覆盖该缺陷的测试创建回归测试。
  • 网页场景:在内置浏览器中点击并检查的步骤。
  • 添加测试命令:项目中已有的脚本,例如 npm test。

编辑测试

选择一个文件,然后选择 在编辑器中打开 自行修改,或选择 用 AI 编辑,就该文件和测试打开新的会话(在您发送之前不会发送任何内容)。 测试失败时,用 AI 修复 会重现失败、修正代码,然后重新运行同一测试和您的回归测试。 在回归测试中,编辑测试 可添加或移除保护它的测试。

运行回归测试

为集合命名,描述其保护的行为或缺陷,并选择已保存的 套件、用例或场景的确切修订版本。单元、集成、API 和 E2E 测试可以放在 同一集合中,无需复制源码。Lint、类型检查和构建仍是独立检查。

保存后,再明确运行该修订版本。完整选择和部分选择会分别 标注。重叠项只执行一次;存在冲突的修订版本和空选择会被 拒绝。后续编辑集合不会改变某次运行已经捕获的成员组成。

集合仍保存在实例的私有状态中,尚无用于 Git 版本管理的导出功能。项目已有的 测试文件和明确导出的场景源码可以正常进行版本管理。

已修复的测试会成为回归测试

在任何项目中,只要缺陷的修复得到证明,该缺陷就会受到保护,无需任何人维护清单。当一个曾经失败的测试在代码更改后通过时,测试页面会把它变成回归测试:

  • 如果一个测试在某次运行的每次尝试中都通过,并且它在项目前五次运行中的最新结果是在不同代码上的失败,就视为已修复。重试后才通过,或在代码未更改时通过,都不算修复。
  • 每个已修复的文件会成为一个回归测试,以其中第一个被修复的测试命名,并使用项目脚本的选项单独运行该文件。其受保护的行为会列出已修复的测试。
  • 一次运行修复的文件超过五个时,不会保护任何内容:一次修复这么多,通常说明修好的是环境,而不是缺陷。
  • 已受回归测试保护的文件保持不变。

创建时不会运行任何内容:下一次回归测试运行(无论是您手动启动还是自动运行)会包含它。您可以像对待其他回归测试一样编辑或删除它。

选择基准并比较

将一次保留的运行选为集合的基准,再与另一次运行比较。 基准用于比较,并不是第三种执行源码模式。 成功的运行永远不会自动替换它。

基准要求断言非空且全部得到观测、预期已知、 数据已隔离,并具有完整的来源信息。失败的基准也可以识别既有失败; 部分结果、导入结果、跳过、不稳定或不完整的证据都不具备基准资格。

比较会区分新回归、既有失败、修复、新增、 删除、跳过、未执行的用例以及不稳定性,并报告预期变化和 配置、数据、运行时、目标的兼容性。部分执行中缺少某个用例,不等于该用例已被删除。 完整的比较证据也可能包含失败;“完整”不代表“通过”。

添加网页场景

编辑场景的行为、目标、数据、前置条件、步骤、断言和清理操作。 使用稳定的角色、标签、测试 ID 或文本定位器。这不是点击操作录制器。

例如,可以用以下步骤保护任务应用的持久化行为:

  1. 使用专用测试数据打开应用。
  2. 在新任务输入框中填写一个已知标题,并选择添加操作。
  3. 断言任务可见,然后将其标为完成。
  4. 重新加载页面。
  5. 断言同一任务仍然可见,且保持勾选状态。

先保存场景,再运行它。保存测试源码 是另一项需要明确触发的 操作:选择项目内的相对文件路径,保留生成的测试源码。 如果已有文件的字节内容不同,导出会被拒绝。编辑已导出的文件会使 映射失效并阻止重放。请审核场景修订版本及其源码映射, 不要覆盖并行进行的工作。之前的证据仍作为历史记录保留。 测试准备不会改变普通应用的启动、停止或激活状态。

集成浏览器使用临时的 Chromium 上下文,并阻止 service workers。 它不能验证离线或 PWA 行为、Safari、Firefox、Android/iOS 原生行为, 也不能验证真实设备的性能。当前目标与源码之间的对应关系可能仍不确定; 在这种情况下,浏览器断言成功时会显示 通过,这一事实写在 详情 中, 但这次运行不会成为完整验证或有资格作为完整基准的结果。 截图是证据;视觉回归判定需要实际执行的断言, 以及明确管理的视觉基准。

检查失败并保留证据

运行报告首先给出结果:通过、失败、不稳定,或用一句话说明为何没有结果, 同时显示所运行内容的名称、测试数量、时长和日期。失败的测试排在最前, 若引擎提供,还会显示预期值和实际值;显示日志 会打开日志,详情 汇总了备注 (运行期间更改的文件、使用项目自身数据的测试)、已保存的文件、运行方式以及与另一次运行的比较。 日志和列表有容量上限并采用分页;截断会明确显示。

命令成功、测试判定、报告完整性和来源信息彼此独立。 没有可用报告的退出码零,只能证明命令成功。零用例、 报告、认证或依赖缺失、跳过以及中断都不能算验证通过。 一次失败后重试成功,仍被标为 不稳定,两次尝试都会保留。

由测试功能保留的截图、跟踪和报告,不依赖原始浏览器会话的存续。 下载需要实例认证;具有活动内容的 HTML/SVG 会作为附件下载, 不会作为报告执行。证据缺失或损坏时会明确指出。 打开源码时定位的是当前项目文件,并不保证其字节内容仍与历史测试一致。 后续编辑不会改写已有结果。

停止 会等待其拥有的子进程退出,并保留无关的应用和 会话。清理被拒绝时仍会显示该状态。关闭页面、网络断开或将客户端 置于后台都不会停止运行。重新连接后,请打开对应的确切 报告。实例重启时,无法证明连续性的执行会被标为中断, 不会自动重放命令。运行列表和通知会链接到 保留的测试结果。

将缺陷转化为受测试保护的行为

保持这条链路:复现 → 保留红色测试 → 修正代码 → 同一预期变绿 → 重放回归集合。重放会创建相互关联的新记录。 更改、删除或削弱断言,并不自动表示缺陷已解决。

你可以自行编写测试,也可以选择 描述行为,获得可编辑的 单元测试或场景提案。使用已有的 Harness、Model、Effort 和 账号控件。审核具体的断言、文件、数据和前置条件; 补全未回答的问题,再明确标记审核就绪并保存。 生成、保存和运行是不同的操作。保存已审核的单元测试提案, 会写入项目的测试文件;保存场景则存储其定义, 源码导出是另一项可选操作。提案没有已执行的判定。 源码变更后,保存前可能需要重新审核。

用 AI 修复 会将确切的失败关联到复现、可查看的修正 会话和新的验证。尚未复现、预期发生变化以及回归证据不完整的情况 都会明确保留。模型的解释永远不能代替断言。 本地测试不需要模型;可选的 AI 功能遵循已有的提供商 用量、定价和配额控制。费用缺失表示未知,并不表示零。 参见用量核算。这些操作不会调用 Ship,也不会发布任何内容。

已验证的引擎及前置条件

以下确切版本已在 Node 22.22.2/22.23.2 下通过 Linux 源码环境验证。 依赖项必须事先存在;测试功能不会安装或升级它们,也不据此承诺任何版本范围的兼容性。

引擎 用例与定向重放 覆盖率与限制
Node test runner 22.22.2 / 22.23.2 结构化用例、钩子、skipped/todo;直接使用当前 Node 可执行文件。不支持精确的单用例重跑或重试历史。 明确显示测量范围的原生行、分支、函数覆盖率;覆盖率元数据最多 128 个文件、64 KiB。
Vitest 4.1.10 直接使用入口;在受监督的收集后精确选择已保留用例;尝试记录保留重试。 覆盖率和预期失败所导致的结果反转不在已验证能力中。生命周期包装器,以及无法保留证据插件的配置,会被拒绝。
Jest 30.2.0 固定文件中的唯一完整名称;每条命令选择一个用例,多个用例使用数量受限的多条命令。 不导入覆盖率。歧义名称、预设、多项目或 TypeScript 配置以及自定义运行器会被拒绝。
pytest 8.4.2 / CPython 3.10.12 直接使用虚拟环境中的 Python -m pytest;保留确切节点标识以及 setup/call/teardown。 覆盖率、包装器、分布式执行和重试插件尚未验证。缺少 pytest 时不会悄悄修复。
Playwright Test 1.63.0 使用项目已安装的运行器;保留项目和重复执行标识、重试尝试及附件。不支持精确的单用例重跑。 不支持覆盖率或预期失败的结果反转。项目自身的浏览器策略与集成浏览器不同。
自定义命令 / JUnit 不含用例细节的命令结果,或有界报告实际提供的用例。不支持精确的单用例重跑。 不猜测覆盖率、计数或重试含义;不支持的 XML 方言仍为无效或不完整状态。

自定义 JUnit 命令必须把本次报告写入私有的运行报告 目录,使用 TEST_REPORT_PATH / TEST_REPORT_DIR 或对应的显式参数 标记 {{TEST_REPORT_PATH}} / {{TEST_REPORT_DIR}}。旧的工作区报告 不能验证新的执行。外部 XML 可通过 API/操作 tests.importJUnit 导入,当前界面没有导入按钮。 导入的计数不能证明本地执行、当前来源信息或基准资格。

Linux 执行已验证。Windows 的进程所有权管理路径已经存在,但原生 Windows 执行仍未验证。目前不支持在 macOS 实例上执行; macOS 客户端可以控制受支持的远程实例。 Android/iOS 界面可用不等于已验证原生应用自动化测试。 源码、确切的载荷、私有安装候选、实际提供服务的客户端、公开发布版本 和真实设备的证据彼此独立,不能相互替代。

会话工具

普通且已获授权的项目会话可使用五个 MCP 工具和对应的 CLI 命令:aircode_tests_catalog / catalog、aircode_tests_describe / describe、 aircode_tests_run / run、aircode_tests_status / status,以及 aircode_tests_open / open。变更前先读取输入结构定义:

aircode-tests catalog
aircode-tests describe --input '{"action":"tests.launchUnits"}'
aircode-tests run --input '{"action":"tests.units","input":{}}'

单元测试套件使用 tests.launchUnits,确切的集合使用 tests.launchRegression, 并带上返回的作用域及固定的修订版本,以及结构定义中要求的显式键。 项目由会话能力提供;不要添加 project 字段。 --input - 接受标准输入中的有界 JSON。status 接受 {scopeId,ownerKind,ownerId};open 接受相同的标识,或用 {} 打开测试页面。 保持返回的 openPath 原样不变。使用 MCP 时,将相同参数传给 对应的 aircode_tests_* 工具。参见 AI 文档。

会话中的启动操作只接受发现过程已识别的执行配置和服务。 请使用已识别的项目脚本,或从所有者界面启动自定义命令。

响应丢失后,先检查状态;明确重试同一操作时,复用 相同的键和输入。 读取状态永远不会重新启动工作。Planning 模式和只读会话 不能写入;工具过期或被撤销后,需要按正常流程恢复会话。 这些工具不授予通用 shell 或公开传输证据的权限。 不要修改存储或伪造凭据来绕过拒绝。

存储与可操作的拒绝原因

定义、基准和不可变的执行事实存放在实例的 私有测试 SQLite 域中。大型日志、截图和跟踪保存在私有伴随 文件中。仅备份数据库并不包含这些字节内容;请在一致的实例备份中 同时保留伴随文件。不要复制正在使用的 WAL 数据库来充当备份。 独有和核心证据默认保留;只有经验证确属冗余的已结束执行附件 才能被明确删除。没有清除独有证据的通用操作。 可识别的秘密信息会被脱敏或拒绝接收,但过滤器无法找出任意日志、 图像、归档或项目数据中的每一项秘密。

拒绝或需要注意的状态 下一步操作
没有单元套件 / 集合为空 分类并保存套件,或添加确切的集合成员。
引擎缺失或不受支持 检查可执行文件、已安装依赖和已验证版本;合适时可使用如实呈现限制的自定义命令。
数据未隔离 / 源码不确定 报告显示通过,这一事实写在详情中;在这样的运行可以成为基准之前,请先建立专用测试夹具。
定向重放不可用 重跑完整选择,或检查保留的报告。
源码变化 / 基准不完整 检查当前源码、预期和兼容性,再明确选择适当的新范围或基准。
队列、内存、磁盘或配额导致延期 解决所指出的资源约束,再明确请求启动或恢复。不会虚构重置时间或重试。
清理被拒绝 / 证据缺失 检查保留的原因和证据;使用可用的证据恢复功能,不要重放测试或手动删除私有状态。