---
url: https://nsh.dev/ja/docs/testing-and-trace
description: "アプリをヘッドレスでテストします。Rust では cargo test と nsh_testing、TypeScript では nsh test を使い、ユーザーと同じようにアプリを開き、タップし、入力し、スクロールし、待機できます。ネットワークとストレージはスタブ化でき、--trace が出力するネイティブビュー操作とタイミングも確認できます。UI テストでは testID を使用します。"
---
# テスト
NSH はアプリを**ヘッドレス**で実行します。実際のエンジン(デバイス上と同じリアクティブグラフ、レンダラー、コンポーネント、レイアウト、リスト仮想化と、TSX 用の QuickJS)を使い、60 Hz でディスプレイフレームを生成しますが、シミュレーターもデバイスもウィンドウも使いません。Cargo または CLI が動く環境ならどこでも(Linux の CI マシンを含む)動作し、次の 2 つの役割を果たします。
- テストの実行: 各テストはアプリを開き、ユーザーが行う操作(押す、入力する、スクロールする)を行い、画面に表示されている内容を検証します。Rust アプリのテストは Rust で書き、`nsh-testing` クレートを使って `cargo test` で実行します。TypeScript で書いたテストは `nsh test` で実行し、TSX アプリにも Rust アプリにも使えます。
- `--trace` を使うと、ランタイムがネイティブビューに送るすべての操作をタイミング付きで出力します。最初のフレーム、タップ、スクロール 1 フレームにかかるコストがわかります。
## テストを書く
Rust と TypeScript で書いた同じテストです。ストレージに空の todo リストがある状態でアプリを開き、入力と押下を行い、画面に表示される内容を検証します。
```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 アプリのテストはそのクレートの統合テストで、`nsh-engine` と `nsh-testing`(デフォルト機能、QuickJS なし)を dev-dependencies に加えます。
```toml
[dev-dependencies]
nsh-engine = "0.1"
nsh-testing = "0.1"
```
```sh
cargo test # every test of the crate
cargo test adds_a_todo # the tests whose name contains "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)`(機能 `bundle`)は、アプリの TSX エントリを同じ方法で開きます。NSH とクレートの UI セットに対してビルドされます([Rust でのビルド](https://nsh.dev/translations/ja/docs/rust.md#testing))。`examples/gallery-rs` はこの方法で Rust のルートをテストしており、デモごとに 1 つのモジュールがあります。`examples/rust-exports` は TSX エントリを Rust からテストします。
`nsh test` はこれらのテストも実行します。Rust クレートを持つアプリのディレクトリ(`nsh.json` `"rust"`)を指定すると、テストファイルの前に各クレートに対して `cargo test` を実行し、Rust のテストを TypeScript のテストとともに(`✓ src/lib.rs › tests::adds`)、サマリーと `--junit` レポートに表示してカウントします。したがって `nsh test` は、Rust アプリ、クレートを持つ TSX アプリ、TSX アプリのいずれにも使える 1 つのコマンドです。同様に `nsh check` も、TypeScript の型チェックの前にクレートに対して `cargo check --all-targets` を実行します。
## nsh test によるテスト
テストファイルは、コードの隣に置く `*.test.tsx` または `*.test.ts` ファイルです。上の `App.test.tsx` と同じように `nsh/test` をインポートします。
```sh
nsh test # every test file of the app in the current directory
nsh test App.test.tsx # one file
nsh test --filter "adds" # the tests whose name contains "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)
```
テストが失敗すると、スローされた内容、テストファイル内の位置、開いたアプリの画面上のテキストが表示されます。失敗が 1 つでもあると、`nsh test` はゼロ以外のコードで終了します。`nsh init` はアプリ入りの `App.test.tsx` を作成し、`nsh check` はテストファイルを他のファイルとともに型チェックします(`.nsh/types` が `nsh/test` を宣言します)。
各テストファイルは専用のエンジンで実行され、そのテストは順番に 1 つずつ実行されます。`open` は毎回新しい別のエンジンでアプリを起動するため、テスト間で状態が共有されることはありません。テストが開いたアプリは、テストの終了時に閉じられます。テストは、例外をスローしたとき、返した Promise が reject されたとき、タイムアウトしたときに失敗します。タイムアウトは 30 秒で、`test` の第 3 引数でミリ秒単位で指定することもできます(`test("syncs", body, 60_000)`)。独自の Rust クレートを持つアプリ(`nsh.json` `"rust"`)は、NSH がそれらとともにビルドするヘッドレスランナーで同じようにテストを実行します。Rust アプリ(`nsh.json` `"root"`、[Rust でのビルド](https://nsh.dev/translations/ja/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)` | これから書くテストで、その旨が報告されます。 |
フックは `async` にできます。`timeout` は指定しない限り 30 秒です。テストとフックはファイルの読み込み時に宣言されます。テストやフックの内側でテストを宣言すると例外がスローされます。
### アプリを開く
`open(entry, options?)` は `entry` にあるアプリをビルドし(テストファイルからの相対パス。各エントリーは実行ごとに 1 回ビルドされます)、390×844 のビューポートで起動し、レンダリングが完了して静止した時点で resolve されます。`--target` を指定すると、アプリはテストが指定したとおりのオプションで実行されます。ターゲットのプラットフォームが対応できないオプションがあると、`open` はそれを示す `ERR_NSH_TEST_UNSUPPORTED` で reject されます([実機プラットフォームでの実行](#on-a-real-platform)を参照)。
| オプション | デフォルト | 説明 |
|---|---|---|
| `storage` | 空 | 開始時に `Storage` が保持する内容: `{ todos: "[]" }`。 |
| `network` | なし | アプリのリクエストに対する、ルートごとの応答: [ネットワークのスタブ化](#stubbing-the-network)を参照。`"live"`: リクエスト、ソケット、WebSocket に対して実際のネットワークを使用します。 |
| `width`、`height` | 390、844 | ポイント単位のビューポート。ヘッドレスではデスクトップのウィンドウ、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"` | ヘッドレスでアプリが動作するプラットフォーム: `"ios"`、`"android"`、またはデスクトップの `"macos"`、`"windows"`、`"linux"`、あるいはデスクトップ流儀(`platform.os`、`ios={{…}}` / `android={{…}}` / `desktop={{…}}` プロパティ、キーボードショートカット)の `"web"`。`--target` を指定すると、アプリはターゲットのプラットフォームとして動作します。デスクトップの `platform` はどのデスクトップや Web でも常にデスクトップとして動作し(ブラウザーではどの幅でもデスクトップ流儀で、`platform.os` は `"web"` のままです)、`"ios"` と `"android"` はそれぞれ自身として動作します。 |
| `clock` | システムのもの | テストが進めたときにだけ時刻が進む手動クロック: `{}`、または `{ time }` で `Date`(または Unix エポックからのミリ秒)から開始します。[時間の制御](#controlling-time)を参照。 |
| `host` | なし | 組み込み先アプリの役割で、テストがそれを演じます: `{ params, handlers }`。[ホストアプリを演じる](#playing-the-host-app)を参照。 |
### ホストアプリを演じる
ネイティブアプリに組み込まれたアプリは、[`host`](https://nsh.dev/translations/ja/modules/nsh.md#host)を通じてそのアプリと通信します。テストでは、テストがホストアプリの役を演じます。`host.params` は起動時にアプリが読み取る起動パラメーターを与え、`host.handlers` はアプリの `host.call` に応答し、`host.post` を名前で受け取ります。ハンドラーは、すべての呼び出しに応答する値か、呼び出しのデータを受け取って応答(またはその Promise)を返す関数です。関数がスローしたものは、ホストアプリのエラーと同様に、その呼び出しを reject します。`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" } }]);
// The app's `host.on("conversation.open", …)` hears it.
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/translations/ja/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()` は、アプリが行ったリクエストを同じ方法で順番に列挙します。
接続もテスト内に閉じられます。アプリのソケット(`net`)と WebSocket(グローバルの `WebSocket` と `websocket` モジュール)は、`network` が `"live"` でない限り何も開きません。アプリ自身の実行が通過するケイパビリティチェックの後、`net.connect` と `websocket` モジュールの `connect` は `code` `ERR_NSH_TEST_NETWORK` で reject され、グローバルの `WebSocket` は `error` に続いて `close`(1006、クリーンではない)を発火します。これは、ネットワークが拒否した接続の場合と同じです。`"live"` を指定すると、アプリのリクエストとともに実際のネットワークに接続します。Rust では、`EngineConfig::refuse_connections` が `Headless` アプリに対して同じことを行います。アプリの接続先(WebSocket の URL、ソケットの `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(); // the autosave, ten seconds later
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); // the autosave, ten seconds later
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` ミリ秒、1 ディスプレイフレームずつ進めます。タイマー、`requestAnimationFrame`、ネイティブアニメーション、遅延レスポンスは、期限が来た順に、それぞれの時刻で実行されます。アプリが静止した時点で resolve されます。 |
| `await app.clock.fastForward(ms)` | スリープから復帰するデバイスのように、クロックを `ms` ミリ秒一度に進めます。その間に期限が来たタイマーは 1 回ずつ実行されます。 |
| `app.clock.setSystemTime(time)` | タイマーを動かさずに、壁時計時刻(`Date.now()`、`new Date()`)を `Date` またはミリ秒に設定します。 |
`Date`、`performance.now()`、`Intl` のデフォルトの日付はクロックに従います。ステップは、実行中のものを待たずに完了させます。アプリがフレームを要求している間、またはネイティブアニメーションが実行されている間は、フレームが次々に進み、各フレームはクロック上で 1 フレーム分の時間(1/60 秒)ずつ後になります。300 ms のトランジションは数ミリ秒で終わり、その間に期限が来たタイマーは実行されます。永久にループするアニメーション(スピナー)はクロックとともに動き、テストがクロックを進めるにつれて回ります。`app.wait(ms)` と長押しは、その時間だけクロックを進めます。それより後に期限が来るタイマーは、テストがそこまでクロックを進めたときにのみ実行されます。`waitFor` と `waitUntil` は、待っている間、1 ディスプレイフレームずつクロックを進め、フレームごとに確認するため、タイマーが表示する内容は待っている間にすぐ現れます。`waitFor("Saved", { timeout: 15_000 })` はクロックを最大 15 秒進めます。タイムアウトは両方のクロックで数えられます。待機はアプリのクロックを最大でその分だけ進め、同じだけの実時間が経過した時点でも reject されるため、アプリの外から来るもの(ルートの関数、ネットワーク)には、システムのクロックの場合と同じだけの時間が与えられます。ギャラリーのテストはこの方法で実行されます(`examples/gallery/tests`)。アニメーションを待つ 12 個のテストは、28 秒ではなく 6 秒で終わります。
### ステップ
ステップは、Playwright と同じ書き方の**セレクター**でビューを指定します。
| セレクター | 一致するもの |
|---|---|
| `id:` | その `testID` を持つビュー。 |
| `label: