--- url: https://nsh.dev/versions/main/zh-CN/docs/testing-and-trace description: "无界面测试应用：用 Rust 配合 cargo test 和 nsh_testing，或用 TypeScript 配合 nsh test：像用户一样打开应用、点击、输入、滚动和等待，模拟网络和存储；读懂 --trace 打印的原生视图操作和耗时；以及用于 UI 测试的 testID。" --- # 测试 NSH 以 **无界面（headless）** 方式运行应用：使用真实的引擎（与设备上相同的响应式图、渲染器、组件、布局和列表虚拟化， TSX 还有 QuickJS），以 60 Hz 提供显示帧，但不需要模拟器、设备或窗口。只要 Cargo 或 CLI 能运行的地方它都能运行，包括 Linux CI 机器。它做两件事： - 运行测试：每个测试打开应用，像用户一样操作（点击、输入、滚动），并检查屏幕上的内容。Rust 应用的测试用 Rust 编写，由 `cargo test` 配合 `nsh-testing` crate 运行；用 TypeScript 编写的测试由 `nsh test` 运行，TSX 应用和 Rust 应用都适用； - 加上 `--trace` 时，打印运行时发送给原生视图的每一个操作并附带耗时：首帧、一次点击或一帧滚动的开销。 ## 编写测试 同一个测试，分别用 Rust 和 TypeScript 编写：它在存储中放一个空的待办列表打开应用，输入、点击，并检查屏幕显示的内容。 ```rust // tests/app/main.rs use nsh_engine::{EngineConfig, Root}; use nsh_testing::{Headless, MemoryStorage}; #[test] fn adds_a_todo() { let mut config = EngineConfig::new(Root::of::()); config.storage = Some(MemoryStorage::new([("todos".to_owned(), "[]".to_owned())])); let mut app = Headless::start(config).unwrap(); app.type_text("id:new-todo", "Buy milk").unwrap(); app.press("text:Add").unwrap(); app.wait_for("text:Buy milk").unwrap(); assert!(app.screen().texts().contains(&"1 item left")); } ``` ```tsx // App.test.tsx import { expect, open, test } from "nsh/test"; test("adds a todo", async () => { const app = await open("./App.tsx", { storage: { todos: "[]" } }); await app.type("id:new-todo", "Buy milk"); await app.press("text:Add"); await app.waitFor("text:Buy milk"); expect(app.texts()).toContain("1 item left"); }); ``` ## 用 cargo test 编写 Rust 测试 Rust 应用的测试是它的 crate 的集成测试，以 `nsh-engine` 和 `nsh-testing`（默认 feature，不含 QuickJS）作为 dev-dependencies： ```toml [dev-dependencies] nsh-engine = "0.1" nsh-testing = "0.1" ``` ```sh cargo test # crate 的所有测试 cargo test adds_a_todo # 名称包含 "adds_a_todo" 的测试 ``` `EngineConfig::new(root)` 是一个手机尺寸（390×844 点）、其余都未设置的引擎；它的字段对应下文 `open` 的选项：`storage` （`MemoryStorage::new(entries)`）、`network`（`StubNetwork`，见下文）、`viewport`、`environment`（外观、区域设置、减少动态效果）、 `clock`（`Clock::manual(time)`，见下文）。`nsh_testing::Headless::start(config)` 启动应用，并维护它所显示视图的模型。它的步骤就是 下文 `nsh test` 的步骤，选择器相同，只是用 Rust 写：`press`、`long_press`、`clear`、`type_text`、`submit`、 `scroll(selector, px(3000.0))`、`back`、`wait`、`wait_for`、`wait_for_gone`、`wait_until`、`run_for`、`fast_forward`、 `set_system_time`、`set_viewport`、`set_clipboard` 和 `on_dialog`；`app.shows(text)` 和 `app.screen()`（`texts()`、 `count(selector)`、`enabled(selector)`、`dialogs()`、`clipboard()`、`commands()`）读取屏幕上的内容。无法执行的步骤会返回一个错误， 附带屏幕上的文字。 `nsh_testing::tsx(entry, sets)`（feature `bundle`）以同样的方式打开应用的 TSX 入口，基于 NSH 的和 crate 的 UI 集合构建 （[用 Rust 开发](https://nsh.dev/versions/main/zh-CN/docs/rust.md#测试)）。`examples/gallery-rs` 就这样测试它的 Rust 根组件，每个演示一个模块；`examples/rust-exports` 从 Rust 测试它的 TSX 入口。 `nsh test` 也会运行这些测试：传入带有 Rust crate 的应用（`nsh.json` `"rust"`）的目录时，它会在测试文件之前为其中每个 crate 运行 `cargo test`，并把 Rust 测试与 TypeScript 测试一起显示和计数（`✓ src/lib.rs › tests::adds`），计入汇总和 `--junit` 报告。所以无论是 Rust 应用、带 crate 的 TSX 应用还是 TSX 应用，`nsh test` 都是同一个命令；`nsh check` 同样会先对 crate 运行 `cargo check --all-targets`，再对 TypeScript 做类型检查。 ## 用 nsh test 编写测试 测试文件是放在代码旁边的 `*.test.tsx` 或 `*.test.ts` 文件，它导入 `nsh/test`，就像上面的 `App.test.tsx`： ```sh nsh test # 当前目录中应用的所有测试文件 nsh test App.test.tsx # 一个文件 nsh test --filter "adds" # 名称包含 "adds" 的测试 ``` ```text ✓ App.test.tsx › adds a todo (84ms) ✗ App.test.tsx › keeps todos after a restart (312ms) expected ["Todos","0 items left"] to contain "1 item left" at (App.test.tsx:21:22) on screen: "Todos", "0 items left" error 2 tests: 1 passed, 1 failed (0.9s) ``` 失败的测试会显示抛出的内容、它在测试文件中的位置，以及所打开应用当时屏幕上的文字。只要有失败，`nsh test` 就以非零 退出码结束。`nsh init` 会随应用创建一个 `App.test.tsx`，`nsh check` 会连同其他代码一起对测试文件做类型检查 （`.nsh/types` 中声明了 `nsh/test`）。 每个测试文件在各自的引擎上运行，文件中的测试按顺序逐个运行。`open` 在另一个全新的引擎上启动应用，因此测试之间从不 共享状态；测试结束时，它打开的应用会被关闭。测试在抛出异常、返回的 promise 被 reject 或超时时失败：超时默认 30 秒， 也可以用 `test` 的第三个参数按毫秒指定（`test("syncs", body, 60_000)`）。带有自己 Rust crate 的应用（`nsh.json` 的 `"rust"`）以同样的方式，在 NSH 用这些 crate 构建的无界面运行器中运行测试；在 Rust 应用 （`nsh.json` 的 `"root"`，[用 Rust 开发](https://nsh.dev/versions/main/zh-CN/docs/rust.md)）中，`open(".")` 启动它的根组件。 ### 分组与准备测试 `describe`、各个钩子和 `test` 的变体与 Jest 的用法一致： ```tsx import { beforeEach, describe, expect, open, test } from "nsh/test"; import type { App } from "nsh/test"; describe("the cart", () => { let app: App; beforeEach(async () => { app = await open("./App.tsx", { storage: { cart: "[]" } }); await app.press("Cart"); }); test("starts empty", () => { expect(app.texts()).toContain("No items"); }); test.todo("applies a coupon"); }); ``` | 函数 | 说明 | |---|---| | `describe(name, body)` | 把 `body` 声明的测试和块归为一组（在文件加载时立即声明）：它们的名称以 `name` 开头（`the cart › starts empty`），其中声明的钩子只在它们前后运行。块可以嵌套。 | | `beforeEach(fn, timeout?)`、`afterEach(fn, timeout?)` | 在所在块（文件或某个 `describe`）的每个测试之前 / 之后运行 `fn`：`beforeEach` 外层块的先运行，`afterEach` 内层块的先运行。`beforeEach` 失败时该测试失败；无论如何 `afterEach` 都会运行。 | | `beforeAll(fn, timeout?)`、`afterAll(fn, timeout?)` | 当所在块有测试要运行时，在第一个测试之前、最后一个测试之后各运行一次 `fn`。`beforeAll` 失败时，该块的测试都失败；`afterAll` 失败时报告为一个失败的 `<块> › afterAll`。`beforeAll` 打开的应用在该块的测试期间保持打开，在其 `afterAll` 之后关闭。 | | `test.skip(name, body, timeout?)`、`describe.skip(name, body)` | 声明不运行的测试或块：它们报告为已跳过。 | | `test.only(name, body, timeout?)`、`describe.only(name, body)` | 测试文件中有它们时，只运行这些测试和块；文件中的其他测试报告为已跳过。 | | `test.todo(name)` | 还没写的测试，报告为 todo。 | 钩子可以是 `async` 函数；`timeout` 默认 30 秒。测试和钩子在文件加载时声明：在测试或钩子里声明测试会抛出异常。 ### 打开应用 `open(entry, options?)` 构建 `entry` 处的应用（路径相对于测试文件；每次运行中每个入口只构建一次），以 390×844 的视口 启动它，并在它完成渲染且空闲后 resolve。使用 `--target` 时，应用按测试给出的每个选项运行；目标平台无法满足的选项会让 `open` 以 `ERR_NSH_TEST_UNSUPPORTED` reject，并在消息中指出该选项（见[在真实平台上运行](#在真实平台上运行)）。 | 选项 | 默认值 | 说明 | |---|---|---| | `storage` | 空 | `Storage` 初始保存的内容：`{ todos: "[]" }`。 | | `network` | 无 | 应用的请求按路由得到的结果，见[模拟网络](#模拟网络)。`"live"`：请求、socket 和 WebSocket 都使用真实网络。 | | `width`、`height` | 390、844 | 视口大小，单位为点：headless、桌面平台的窗口、web 的页面。在 iOS 和 Android 上应用占满设备屏幕。 | | `safeArea` | 0 | 安全区域内边距，单位为点：`{ top: 47, bottom: 34 }`。 | | `clipboard` | 空 | 剪贴板初始的文字。 | | `colorScheme` | `"light"` | 系统外观：`"light"` 或 `"dark"`（`colorScheme()`、`dark:` 类）。 | | `locale` | `"en-US"` | 设备的区域设置，BCP 47 标签（`locale()`、`Intl` 的默认值）。 | | `reducedMotion` | `false` | 用户要求减少动态效果（`reduceMotion()`）。 | | `platform` | `"ios"` | headless 时应用运行所在的平台：`"ios"`、`"android"`，或桌面平台 `"macos"`、`"windows"`、`"linux"`，以及桌面形态的 `"web"`（`platform.os`、`ios={{…}}` / `android={{…}}` / `desktop={{…}}` 属性、键盘快捷键）。使用 `--target` 时，应用以目标平台运行：桌面平台的 `platform` 可用于任何桌面目标和 web，且总以桌面形态运行（在浏览器中无论宽度都是桌面形态，`platform.os` 仍是 `"web"`），`"ios"` 和 `"android"` 只用于各自的目标。 | | `clock` | 系统时钟 | 手动时钟，它的时间只随测试推进：`{}`，或者用 `{ time }` 从某个 `Date`（或自 Unix 纪元起的毫秒数）开始。见[控制时间](#控制时间)。 | | `host` | 无 | 由测试扮演的宿主应用：`{ params, handlers }`。见[扮演宿主应用](#扮演宿主应用)。 | ### 扮演宿主应用 嵌入在原生应用中的应用通过 [`host`](https://nsh.dev/versions/main/zh-CN/modules/nsh.md#host) 与宿主应用通信。在测试里由测试扮演宿主应用：`host.params` 是应用启动时读取的启动参数，`host.handlers` 按名称回答应用的 `host.call`、接收它的 `host.post`。处理函数可以是一个值，用它回答每次调用；也可以是一个函数，接收调用的数据并返回回答（或回答的 promise）。函数抛出的错误会让调用失败，与宿主应用出错时一样。`handlers` 没有列出的名称的调用会失败，与不处理任何调用的宿主应用一样。 ```tsx const app = await open("./App.tsx", { host: { params: { conversation: "c-42" }, handlers: { "user.profile": async ({ id }) => ({ id, name: "Ada" }), "feature.flags": { search: true }, analytics: null, }, }, }); await app.press("Profile"); expect(app.host.calls()).toEqual([{ name: "user.profile", data: { id: 7 } }]); expect(app.host.posts()).toEqual([{ name: "analytics", data: { screen: "profile" } }]); // 应用的 `host.on("conversation.open", …)` 会收到它。 await app.host.send("conversation.open", { id: "c-43" }); expect(app.shows("Conversation c-43")).toBe(true); ``` `app.host.send(name, data)` 发送一个事件，然后等待应用空闲。`app.host.calls()` 和 `app.host.posts()` 按顺序列出处理函数收到的调用和投递：`name` 和 `data`。 应用打开的 URL（[`openUrl`](https://nsh.dev/versions/main/zh-CN/modules/nsh.md#openurl)，以及 `links="open"` 的 `TextView` 中的链接）会被记录下来，并以“已打开”回报给应用，本机上不会真正打开任何东西。`app.openedUrls()` 列出它们： ```tsx await app.press("Contact us"); expect(app.openedUrls()).toEqual(["mailto:help@example.com"]); ``` ### 模拟网络 `network` 按 `" "` 列出路由（只写 URL 表示 `GET`；`*` 匹配任意文字）。没有路由匹配的请求会失败，因此测试不会在 未经允许时访问网络。路由是一个响应，或者一个接收请求、返回响应（或响应的 Promise）的函数；在 Rust 中， `StubNetwork::new(routes)` 接受同样的路由，每个是一个 `StubResponse` 或一个 `StubRoute::Handler`： ```rust use std::sync::Arc; use nsh_engine::{EngineConfig, Root}; use nsh_testing::{Headless, StubNetwork, StubResponse}; #[test] fn adds_a_todo_on_the_server() { let mut todos = StubResponse::default(); todos.status = 200; todos.headers = vec![("content-type".to_owned(), "application/json".to_owned())]; todos.body = br#"[{ "id": 1, "title": "Walk" }]"#.to_vec(); let mut created = StubResponse::default(); created.status = 201; let mut offline = StubResponse::default(); offline.error = Some("offline".to_owned()); let network = Arc::new(StubNetwork::new([ ("GET https://api.example.com/todos".to_owned(), todos), ("POST https://api.example.com/todos".to_owned(), created), ("GET https://api.example.com/sync".to_owned(), offline), ])); let mut config = EngineConfig::new(Root::of::()); config.network = Some(network.clone()); let mut app = Headless::start(config).unwrap(); app.press("Add").unwrap(); let methods: Vec = network.requests().iter().map(|r| r.method.clone()).collect(); assert_eq!(methods, ["GET", "POST"]); } ``` ```tsx const app = await open("./App.tsx", { network: { "GET https://api.example.com/todos": { body: [{ id: 1, title: "Walk" }] }, "POST https://api.example.com/todos": (request) => ({ status: 201, body: JSON.parse(request.body!) }), "GET https://api.example.com/todos/*": { status: 404 }, "GET https://api.example.com/sync": { error: "offline" }, "GET https://api.example.com/slow": { body: "done", delay: 2000 }, }, }); await app.press("Add"); expect(app.requests().map((r) => r.method)).toEqual(["GET", "POST"]); ``` | 响应成员 | 默认值 | 说明 | |---|---|---| | `status` | 200 | 状态码。 | | `headers` | 无 | 响应头的名称和值。 | | `body` | 空 | 字符串，或者作为 JSON 发送的值（`headers` 未指定时带上 `content-type: application/json`）。 | | `error` | 无 | 请求改为以这条消息失败，就像设备离线时那样。 | | `delay` | 0 | 响应需要的时间，单位为毫秒；步骤不会等它，`waitFor` 会。在手动时钟上，时钟走过这段时间后响应才到达。 | 路由的函数接收请求（`method`、`url`、`headers`，以及文字形式的 `body`），在测试文件中运行，所以可以统计请求次数，或者根据 测试准备好的数据作答。函数抛出异常时，请求失败，发出该请求的步骤也随之失败。`app.requests()` 以同样的形式按顺序列出应用发出的请求。 连接同样留在测试之内：除非 `network` 为 `"live"`，应用的 socket（`net`）和 WebSocket（全局 `WebSocket` 和 `websocket` 模块） 不会建立连接。在应用自身的能力检查通过之后，`net.connect` 和 `websocket` 模块的 `connect` 以 `code` 为 `ERR_NSH_TEST_NETWORK` 的错误 reject，全局 `WebSocket` 先触发 `error`，再触发 `close`（1006，非正常关闭），与网络拒绝连接时一样。使用 `"live"` 时，它们和应用的请求一起 连接真实网络。在 Rust 中，`EngineConfig::refuse_connections` 对 `Headless` 应用做同样的事：它是一个函数，接收应用要连接的目标 （WebSocket 的 URL、socket 的 `host:port`），返回这次调用失败时的错误。 ### 控制时间 在系统时钟上，应用的定时器和原生动画与在设备上耗时相同，等待它们的测试也一样慢。使用手动时钟（Rust 中的 `EngineConfig::clock`，TypeScript 中 `open` 的 `clock`）时，应用改在手动时钟上运行，就像 Jest 的假定时器或 Playwright 的 `page.clock`：时间只随测试推进，并且立即推进。`app.clock` 就是这个时钟，应用使用系统时钟时它为 `null`： ```rust use std::time::{Duration, SystemTime}; use nsh_engine::{Clock, EngineConfig, Root}; use nsh_testing::Headless; #[test] fn autosaves() { let mut config = EngineConfig::new(Root::of::()); // 2026-01-01T09:00:00Z config.clock = Clock::manual(SystemTime::UNIX_EPOCH + Duration::from_secs(1_767_258_000)); let mut app = Headless::start(config).unwrap(); app.type_text("label:Note", "Milk").unwrap(); app.run_for(Duration::from_secs(10)).unwrap(); // 十秒后的自动保存 assert!(app.shows("Saved at 09:00:10")); } ``` ```tsx const app = await open("./App.tsx", { clock: { time: new Date("2026-01-01T09:00:00Z") } }); await app.type("label:Note", "Milk"); await app.clock!.runFor(10_000); // 十秒后的自动保存 expect(app.texts()).toContain("Saved at 09:00:10"); ``` 响应带 `delay` 的 `StubNetwork` 用 `.with_clock(clock.clone())` 跟随手动时钟。下面是 `nsh test` 的步骤；`Headless` 都有对应的方法 （`run_for`、`fast_forward`、`set_system_time`）。 | 步骤 | 说明 | |---|---| | `await app.clock.runFor(ms)` | 把时钟推进 `ms` 毫秒，每次一个显示帧：定时器、`requestAnimationFrame`、原生动画和延迟的响应在到期时按顺序执行，各自在自己的时刻；应用空闲后 resolve。 | | `await app.clock.fastForward(ms)` | 一次把时钟推进 `ms` 毫秒，就像设备从睡眠中醒来：期间到期的定时器各执行一次。 | | `app.clock.setSystemTime(time)` | 把墙上时间（`Date.now()`、`new Date()`）设为某个 `Date` 或毫秒数，不触发任何定时器。 | `Date`、`performance.now()` 和 `Intl` 的默认日期都跟随这个时钟。步骤不再等待正在进行的内容：只要应用在请求帧或有原生 动画在运行，帧就一帧接一帧地立即到来，每帧在时钟上相隔一帧的时间（1/60 s）；300 ms 的转场只需几毫秒，期间到期的 定时器也会执行。无限循环的动画（加载指示器）随时钟运行：测试推进时钟时它跟着转动。`app.wait(ms)` 和长按会把时钟推进它们各自的时长。更晚到期的定时器只有在测试把时钟推进到那里时才会执行。 `waitFor` 和 `waitUntil` 在等待时推进时钟，每次一个显示帧，每帧之后检查一次，所以定时器显示的内容会在等待中很快出现： `waitFor("Saved", { timeout: 15_000 })` 最多把时钟推进十五秒。它们的超时同时按两个时钟计算：等待最多把应用的时钟推进这么久， 并且在真实时间也过去这么久之后才 reject，所以来自应用外部的内容（路由的函数、网络）和在系统时钟上一样有足够的时间到达。gallery 的测试就是这样运行的 （`examples/gallery/tests`）：其中十二个要等动画的测试用 6 s，而不是 28 s。 ### 操作步骤 步骤用 **选择器** 指定视图，写法和 Playwright 一致： | 选择器 | 匹配 | |---|---| | `id:` | 设置了该 `testID` 的视图。 | | `label: