---
url: https://nsh.dev/de/docs/testing-and-trace
description: "Testen Sie Apps headless, in Rust mit cargo test und nsh_testing oder in TypeScript mit nsh test: Öffnen Sie die App, drücken, tippen, scrollen und warten Sie wie ein Benutzer, simulieren Sie Netzwerk und Speicher per Stub und lesen Sie die nativen View-Operationen und Zeitmessungen, die --trace ausgibt; testID für UI-Tests."
---
# Testen
NSH führt Apps **headless** aus: mit der echten Engine (derselbe reaktive Graph, derselbe Renderer, dieselben Komponenten, dasselbe Layout und dieselbe Listenvirtualisierung wie auf einem Gerät, und QuickJS für TSX), mit Display-Frames bei 60 Hz, aber ohne Simulator, Gerät und Fenster. Es läuft überall dort, wo Cargo oder die CLI läuft, auch auf Linux-CI-Maschinen, und erfüllt zwei Aufgaben:
- Es führt Tests aus: Jeder Test öffnet die App, führt die Schritte eines Nutzers aus (drücken, tippen, scrollen) und prüft, was auf dem Bildschirm steht. Die Tests einer Rust-App sind in Rust geschrieben und werden mit `cargo test` und dem Crate `nsh-testing` ausgeführt; in TypeScript geschriebene Tests laufen mit `nsh test`, für TSX-Apps und Rust-Apps gleichermaßen;
- mit `--trace` gibt es jede Operation aus, die die Runtime an die nativen Views sendet, samt Zeitangaben: was der erste Frame, ein Tap oder ein Frame beim Scrollen kostet.
## Tests schreiben
Derselbe Test in Rust und in TypeScript: Er öffnet die App mit einer leeren Todo-Liste im Storage, tippt, drückt und prüft, was der Bildschirm zeigt.
```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");
});
```
## Tests in Rust mit cargo test
Die Tests einer Rust-App sind Integrationstests ihres Crates, mit `nsh-engine` und `nsh-testing` (dessen Default-Features, ohne QuickJS) als 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)` ist eine Engine in Smartphone-Größe (390×844 Punkte), bei der sonst nichts gesetzt ist; ihre Felder setzen, was die Optionen von `open` weiter unten setzen: `storage` (`MemoryStorage::new(entries)`), `network` (`StubNetwork`, siehe unten), `viewport`, `environment` (das Erscheinungsbild, die Locale, reduzierte Bewegung), `clock` (`Clock::manual(time)`, siehe unten). `nsh_testing::Headless::start(config)` startet die App und hält ein Modell der Views, die sie anzeigt. Seine Schritte sind die von `nsh test` weiter unten, mit denselben Selektoren, in 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` und `on_dialog`; `app.shows(text)` und `app.screen()` (`texts()`, `count(selector)`, `enabled(selector)`, `dialogs()`, `clipboard()`, `commands()`) lesen, was auf dem Bildschirm steht. Ein Schritt gibt einen Fehler mit den Texten auf dem Bildschirm zurück, wenn er nicht ausgeführt werden kann.
`nsh_testing::tsx(entry, sets)` (Feature `bundle`) öffnet den TSX-Einstiegspunkt einer App auf dieselbe Weise, gebaut gegen die UI-Sets von NSH und des Crates ([Mit Rust bauen](https://nsh.dev/translations/de/docs/rust.md#testing)). `examples/gallery-rs` testet sein Rust-Root auf diese Weise, ein Modul pro Demo; `examples/rust-exports` testet seinen TSX-Einstiegspunkt aus Rust.
`nsh test` führt diese Tests ebenfalls aus: Erhält es das Verzeichnis einer App mit Rust-Crates (`nsh.json` `"rust"`), führt es vor den Testdateien `cargo test` für jedes darin enthaltene Crate aus und zeigt und zählt die Rust-Tests zusammen mit den TypeScript-Tests (`✓ src/lib.rs › tests::adds`), in seiner Zusammenfassung und in seinem `--junit`-Bericht. `nsh test` ist also der eine Befehl für eine Rust-App, eine TSX-App mit Crate und eine TSX-App gleichermaßen, und `nsh check` führt ebenso `cargo check --all-targets` auf den Crates aus, bevor es das TypeScript typprüft.
## Tests mit nsh test
Eine Testdatei ist eine `*.test.tsx`- oder `*.test.ts`-Datei neben Ihrem Code. Sie importiert `nsh/test`, wie `App.test.tsx` oben:
```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)
```
Ein fehlgeschlagener Test zeigt, was geworfen wurde, die Stelle in der Testdatei und die Texte auf dem Bildschirm der App, die er geöffnet hat. Jeder Fehlschlag lässt `nsh test` mit einem Exit-Code ungleich null enden. `nsh init` legt ein `App.test.tsx` mit der App an, und `nsh check` typprüft Testdateien zusammen mit dem Rest (`.nsh/types` deklariert `nsh/test`).
Jede Testdatei läuft auf einer eigenen Engine, und ihre Tests laufen nacheinander in der angegebenen Reihenfolge. `open` startet die App auf einer weiteren, jedes Mal neuen Engine, sodass Tests nie Zustand teilen; die Apps, die ein Test geöffnet hat, werden geschlossen, wenn er endet. Ein Test schlägt fehl, wenn er wirft, wenn das zurückgegebene Promise abgelehnt wird und nach Ablauf seines Timeouts: 30 Sekunden oder die Millisekunden, die das dritte Argument von `test` angibt (`test("syncs", body, 60_000)`). Eine App mit eigenen Rust-Crates (`nsh.json` `"rust"`) führt ihre Tests auf dieselbe Weise in einem Headless-Runner aus, den NSH mit ihnen baut; in einer Rust-App (`nsh.json` `"root"`, [Mit Rust bauen](https://nsh.dev/translations/de/docs/rust.md)) startet `open(".")` ihre Root-Komponente.
### Tests gruppieren und einrichten
`describe`, die Hooks und die Varianten von `test` funktionieren wie bei 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");
});
```
| Funktion | Beschreibung |
|---|---|
| `describe(name, body)` | Gruppiert die Tests und Blöcke, die `body` deklariert (sofort, beim Laden der Datei): Ihre Namen beginnen mit `name` (`the cart › starts empty`), und die Hooks, die es deklariert, laufen nur um sie herum. Blöcke lassen sich verschachteln. |
| `beforeEach(fn, timeout?)`, `afterEach(fn, timeout?)` | Führen `fn` vor / nach jedem Test des Blocks aus, in dem sie deklariert sind (die Datei, ein `describe`): `beforeEach` der äußeren Blöcke zuerst, `afterEach` der inneren zuerst. Ein `beforeEach`, das fehlschlägt, lässt den Test fehlschlagen; `afterEach` läuft in jedem Fall. |
| `beforeAll(fn, timeout?)`, `afterAll(fn, timeout?)` | Führen `fn` einmal vor dem ersten und nach dem letzten Test ihres Blocks aus, wenn einer seiner Tests läuft. Ein `beforeAll`, das fehlschlägt, lässt die Tests des Blocks fehlschlagen; ein `afterAll`, das fehlschlägt, wird als fehlgeschlagenes ` › afterAll` gemeldet. Eine App, die ein `beforeAll` öffnet, bleibt für die Tests des Blocks geöffnet und wird nach seinem `afterAll` geschlossen. |
| `test.skip(name, body, timeout?)`, `describe.skip(name, body)` | Deklariert einen Test oder einen Block, dessen Tests nicht laufen: Sie werden als übersprungen gemeldet. |
| `test.only(name, body, timeout?)`, `describe.only(name, body)` | Solange eine Testdatei einen solchen enthält, laufen nur diese Tests und Blöcke; die übrigen der Datei werden als übersprungen gemeldet. |
| `test.todo(name)` | Ein noch zu schreibender Test, der als solcher gemeldet wird. |
Ein Hook darf `async` sein; sein `timeout` beträgt 30 Sekunden, sofern nicht anders angegeben. Tests und Hooks werden beim Laden der Datei deklariert: Ein Test, der innerhalb eines Tests oder eines Hooks deklariert wird, wirft einen Fehler.
### Die App öffnen
`open(entry, options?)` baut die App unter `entry` (relativ zur Testdatei; jeder Einstiegspunkt wird pro Lauf einmal gebaut), startet sie in einem 390×844-Viewport und wird aufgelöst, sobald sie gerendert hat und ruhig ist. Mit `--target` läuft die App mit den Optionen, wie der Test sie angibt: Eine Option, die die Plattform des Ziels nicht erfüllen kann, lässt `open` mit `ERR_NSH_TEST_UNSUPPORTED` ablehnen und nennt sie dabei (siehe [Auf einer echten Plattform](#on-a-real-platform)).
| Option | Standard | Beschreibung |
|---|---|---|
| `storage` | leer | Was `Storage` zu Beginn enthält: `{ todos: "[]" }`. |
| `network` | keine | Was die Requests der App erhalten, nach Route: siehe [Das Netzwerk stubben](#stubbing-the-network). `"live"`: das echte Netzwerk, für ihre Requests, Sockets und WebSockets. |
| `width`, `height` | 390, 844 | Der Viewport in Punkten: headless, das Fenster der Desktops, die Seite im Web. Unter iOS und Android füllt die App den Bildschirm des Geräts. |
| `safeArea` | 0 | Die Safe-Area-Insets in Punkten: `{ top: 47, bottom: 34 }`. |
| `clipboard` | leer | Der Text in der Zwischenablage zu Beginn. |
| `colorScheme` | `"light"` | Das Erscheinungsbild des Systems: `"light"` oder `"dark"` (`colorScheme()`-, `dark:`-Klassen). |
| `locale` | `"en-US"` | Die Locale des Geräts, ein BCP-47-Tag (`locale()`, der Standard von `Intl`). |
| `reducedMotion` | `false` | Der Nutzer hat um weniger Bewegung gebeten (`reduceMotion()`). |
| `platform` | `"ios"` | Die Plattform, als die die App headless läuft: `"ios"`, `"android"` oder die eines Desktops, `"macos"`, `"windows"`, `"linux"`, oder `"web"` im Desktop-Idiom (`platform.os`, `ios={{…}}`- / `android={{…}}`- / `desktop={{…}}`-Props, Tastaturkürzel). Mit `--target` läuft die App als die Plattform des Ziels: ein Desktop-`platform` auf jedem Desktop und im Web immer als Desktop (im Browser im Desktop-Idiom bei jeder Breite, wobei `platform.os` auf `"web"` bleibt), `"ios"` und `"android"` jeweils als sie selbst. |
| `clock` | die des Systems | Eine manuelle Uhr, deren Zeit sich nur so weit bewegt, wie der Test sie bewegt: `{}`, oder `{ time }`, um bei einem `Date` zu starten (oder bei Millisekunden seit der Unix-Epoche). Siehe [Die Zeit steuern](#controlling-time). |
| `host` | keine | Die Rolle der einbettenden App, die der Test spielt: `{ params, handlers }`. Siehe [Die Host-App simulieren](#playing-the-host-app). |
### Die Host-App simulieren
Eine in eine native App eingebettete App spricht mit dieser über [`host`](https://nsh.dev/translations/de/modules/nsh.md#host). In einem Test spielt der Test die Host-App: `host.params` liefert die Startparameter, die die App beim Start liest, und `host.handlers` beantwortet die `host.call` der App und hört ihre `host.post`, jeweils nach Namen. Ein Handler ist ein Wert, der jeden Aufruf beantwortet, oder eine Funktion der Daten des Aufrufs, die die Antwort zurückgibt (oder ein Promise darauf). Was die Funktion wirft, lehnt den Aufruf ab, so wie der Fehler einer Host-App es tut. Ein Aufruf eines Namens, den `handlers` nicht auflistet, schlägt fehl, wie in einer Host-App, die keinen behandelt.
```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)` sendet ein Event und wartet dann, bis die App ruhig ist. `app.host.calls()` und `app.host.posts()` listen der Reihe nach auf, was die Handler erhalten haben: `name` und `data`.
Die URLs, die die App öffnet ([`openUrl`](https://nsh.dev/translations/de/modules/nsh.md#openurl), die Links eines `TextView` mit `links="open"`), werden aufgezeichnet und der App als geöffnet gemeldet; auf diesem Rechner öffnet sich nichts. `app.openedUrls()` listet sie auf:
```tsx
await app.press("Contact us");
expect(app.openedUrls()).toEqual(["mailto:help@example.com"]);
```
### Das Netzwerk stubben
`network` listet Routen nach `""` auf (eine bloße URL ist ein `GET`; `*` passt auf jeden Text). Ein Request, auf den keine Route passt, schlägt fehl, sodass Tests das Netzwerk nie ungefragt erreichen. Eine Route ist eine Antwort oder eine Funktion des Requests, die eine zurückgibt (oder ein Promise darauf); in Rust akzeptiert `StubNetwork::new(routes)` dieselben Routen, jeweils ein `StubResponse` oder ein `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"]);
```
| Antwortfeld | Standard | Beschreibung |
|---|---|---|
| `status` | 200 | Der Statuscode. |
| `headers` | keine | Header-Namen und -Werte. |
| `body` | leer | Ein String oder ein als JSON gesendeter Wert (mit `content-type: application/json`, sofern `headers` keinen angibt). |
| `error` | keine | Der Request schlägt stattdessen mit dieser Meldung fehl, wie wenn das Gerät offline ist. |
| `delay` | 0 | Wie lange die Antwort braucht, in Millisekunden; ein Schritt wartet nicht darauf, `waitFor` schon. Auf einer manuellen Uhr kommt sie, sobald die Uhr sie überschreitet. |
Die Funktion einer Route erhält den Request (`method`, `url`, `headers`, `body` als Text) und läuft in der Testdatei, sodass sie Requests zählen oder aus dem antworten kann, was der Test eingerichtet hat. Eine Funktion, die wirft, lässt den Request und den Schritt, der ihn ausgelöst hat, fehlschlagen. `app.requests()` listet die Requests auf, die die App gemacht hat, der Reihe nach, auf dieselbe Weise.
Auch Verbindungen bleiben im Test: Die Sockets der App (`net`) und WebSockets (das globale `WebSocket` und das Modul `websocket`) öffnen keine, es sei denn, `network` ist `"live"`. Nach den Capability-Prüfungen, die der eigene Lauf der App besteht, lehnen `net.connect` und `connect` des Moduls `websocket` mit `code` `ERR_NSH_TEST_NETWORK` ab, und ein globales `WebSocket` löst `error` aus, dann `close` (1006, nicht sauber), wie bei einer vom Netzwerk verweigerten Verbindung. Mit `"live"` verbinden sie sich zusammen mit den Requests der App mit dem echten Netzwerk. In Rust leistet `EngineConfig::refuse_connections` dasselbe für eine `Headless`-App: eine Funktion dessen, womit sich die App verbindet (die URL eines WebSockets, der `host:port` eines Sockets), die den Fehler zurückgibt, mit dem ihr Aufruf fehlschlägt.
### Die Zeit steuern
Auf der Systemuhr brauchen die Timer und nativen Animationen einer App so lange wie auf einem Gerät, und ebenso die Tests, die auf sie warten. Mit einer manuellen Uhr (`EngineConfig::clock` in Rust, `clock` von `open` in TypeScript) läuft die App auf einer Uhr, deren Zeit sich nur so weit bewegt, wie der Test sie bewegt, und zwar sofort, wie bei den Fake-Timern von Jest oder `page.clock` von Playwright. `app.clock` ist diese Uhr, und `null`, wenn die App auf der Systemuhr läuft:
```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");
```
Ein `StubNetwork`, dessen Antworten ein `delay` haben, folgt einer manuellen Uhr mit `.with_clock(clock.clone())`. Die folgenden Schritte sind die von `nsh test`; `Headless` hat jeden davon (`run_for`, `fast_forward`, `set_system_time`).
| Schritt | Beschreibung |
|---|---|
| `await app.clock.runFor(ms)` | Bewegt die Uhr um `ms` Millisekunden, jeweils einen Display-Frame auf einmal. Timer, `requestAnimationFrame`, native Animationen und verzögerte Antworten laufen, sobald sie fällig werden, der Reihe nach, jeweils zu ihrem Zeitpunkt. Wird aufgelöst, sobald die App ruhig ist. |
| `await app.clock.fastForward(ms)` | Bewegt die Uhr auf einmal um `ms` Millisekunden, wie ein Gerät, das aus dem Ruhezustand aufwacht: Die in der Zwischenzeit fälligen Timer laufen je einmal. |
| `app.clock.setSystemTime(time)` | Setzt die Wanduhrzeit (`Date.now()`, `new Date()`) auf ein `Date` oder Millisekunden, ohne einen Timer zu bewegen. |
`Date`, `performance.now()` und das Standarddatum von `Intl` folgen der Uhr. Schritte beenden, was gerade läuft, ohne darauf zu warten: Solange die App Frames anfordert oder eine native Animation läuft, kommen Frames nacheinander, jeder um die Zeit eines Frames (1/60 s) später auf der Uhr. Ein 300-ms-Übergang dauert einige Millisekunden, und ein währenddessen fälliger Timer läuft. Eine Animation, die endlos wiederholt wird (ein Spinner), läuft mit der Uhr mit: Sie dreht sich, wie der Test die Uhr bewegt. `app.wait(ms)` und ein langer Druck bewegen die Uhr um ihre Dauer. Ein Timer, der später fällig wird, läuft erst, wenn der Test die Uhr dorthin bewegt. `waitFor` und `waitUntil` bewegen die Uhr, während sie warten, jeweils einen Display-Frame auf einmal und schauen nach jedem Frame nach, sodass das, was ein Timer anzeigt, in einem Moment erscheint, während sie darauf warten: `waitFor("Saved", { timeout: 15_000 })` bewegt die Uhr um bis zu fünfzehn Sekunden. Ihr Timeout zählt auf beiden Uhren: Ein Warten bewegt die Uhr der App höchstens um diesen Wert und lehnt ab, sobald ebenso viel echte Zeit vergangen ist, sodass das, was von außerhalb der App kommt (die Funktion einer Route, das Netzwerk), so lange Zeit hat wie auf der Systemuhr. Die Tests der Galerie laufen auf diese Weise (`examples/gallery/tests`): Ihre zwölf Tests, die auf Animationen warten, dauern 6 s statt 28 s.
### Schritte
Schritte benennen Views mit **Selektoren**, geschrieben wie bei Playwright:
| Selektor | Findet |
|---|---|
| `id:` | Die View mit dieser `testID`. |
| `label: