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.

// 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::<my_app::App>());
    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"));
}

// 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:

[dev-dependencies]
nsh-engine = "0.1"
nsh-testing = "0.1"

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). 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:

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"

✓ 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 <anonymous> (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) startet open(".") ihre Root-Komponente.

#Tests gruppieren und einrichten

describe, die Hooks und die Varianten von test funktionieren wie bei Jest:

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");
});

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).

#Die Host-App simulieren

Eine in eine native App eingebettete App spricht mit dieser über 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.

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, 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:

await app.press("Contact us");
expect(app.openedUrls()).toEqual(["mailto:help@example.com"]);

#Das Netzwerk stubben

network listet Routen nach "<METHOD> <URL>" 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:

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::<my_app::App>());
    config.network = Some(network.clone());
    let mut app = Headless::start(config).unwrap();
    app.press("Add").unwrap();
    let methods: Vec<String> = network.requests().iter().map(|r| r.method.clone()).collect();
    assert_eq!(methods, ["GET", "POST"]);
}

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"]);

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:

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::<my_app::App>());
    // 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"));
}

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).

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:

Ein Teil, der mit einem kleingeschriebenen Wort und einem Doppelpunkt beginnt, benennt ein Präfix (id, label, role, text, view), daher ist tapped: solo ein Schrittfehler, der sie auflistet. Ein Text, Label oder eine Test-ID, die so beginnt, bekommt ihr Präfix, das den Rest wie geschrieben liest: text:tapped: solo, label:note: draft, id:row:2. Selektoren behalten ihre Bedeutung, wenn neue Präfixe hinzukommen.

label:, text: und der Name einer Rolle nehmen auch einen regulären Ausdruck: text:/^Buy/i, geschrieben in der Syntax des Rust-Crates regex (die Klassen, Gruppen, Anker und Quantifizierer von JavaScript, in linearer Zeit abgeglichen; die Flags i, m und s). >> schaut in das hinein, was der vorherige Teil gefunden hat (id:cart >> role:button[Remove]), und nth=<n> behält einen der Treffer, ab 0 (text:Delete >> nth=1). Ein Selektor findet die Views, die ein Benutzer zuerst ansehen würde: im obersten Modal, dann auf dem Bildschirm, und von einem Navigation-Stack nur den obersten Screen. Er trifft zu auf das, was der Benutzer sieht: Views mit einer Fläche, außerhalb von visibility: hidden, innerhalb des Fensters und der Views, die sie beschneiden (overflow: hidden), oder irgendwo im Inhalt einer Scroll-View, die der Benutzer scrollen kann und die durch Scrollen hereingeholt wird (opacity und Transformationen ausgenommen, wie bei Playwright). Ein Schritt, der auf eine View wirkt (press, type, clear, submit, scroll, longPress), braucht genau eine: Ein Selektor, der mehrere findet, lässt den Schritt fehlschlagen, und der Fehler nennt, wie man ihn eingrenzt.

Ein Schritt wird aufgelöst, sobald die App 100 ms lang nichts gerendert hat und keine native Animation läuft, die von selbst endet (höchstens 2 s, für Apps, die ständig rendern; bei einer manuellen Uhr zusätzlich 2 s der App-Zeit), sodass das, was er geändert hat, auf dem Bildschirm steht, wenn die nächste Zeile läuft; nutze waitFor für das, was später kommt (eine Antwort, ein Timer). Bei einer manuellen Uhr wartet ein Schritt nicht auf diese 100 ms: Er wird aufgelöst, sobald die App alles ausgeführt hat, was der Schritt und die Zeit der Uhr fällig gemacht haben (jetzt fällige Timer, Promises, eine sofort beantwortete gestubbte Antwort) und keinen Frame verlangt, es sei denn, ein Request ist noch unterwegs; so laufen Tests mit einer manuellen Uhr ohne Pausen zwischen ihren Schritten. Was ein anderer Thread beantwortet (ein nsh/host-Aufruf, ein Dateilesevorgang, die Arbeit eines Rust-Tasks auf einem Thread), trifft nach dem Auflösen des Schritts ein: Warte mit waitFor auf das, was es zeigt. Eine Animation, die endlos läuft, etwa ein Lade-Spinner, läuft im Hintergrund weiter, während Schritte und waitFor fortfahren, so wie eine endlose CSS-Animation in den Tests eines Browsers. Ein Schritt schlägt fehl und lässt damit den Test fehlschlagen, wenn nichts zu seinem Selektor passt (der Fehler listet die Texte auf dem Bildschirm auf), wenn die App währenddessen eine Exception geworfen hat und wenn die App etwas angefordert hat, das nur eine echte Plattform beantwortet.

Die Fehler, die ein Test erwarten darf, tragen einen code, der unverändert bleibt; ihre Meldungen sind für Menschen gedacht und können sich ändern, daher prüft ein Test den Code:

await expect(app.press("Pay")).rejects.toMatchObject({ code: "ERR_NSH_TEST_DISABLED" });

app.spanStyle("id:guide") liest ein verschachteltes <Text testID="guide">; text:word liest das erste Zeichen dieses Treffers. Grenze Abfragen mit id:note >> text:word ein und wähle wiederholte Treffer mit >> nth=0 aus. Die Abfrage meldet einen Fehler für einen fehlenden, mehrdeutigen oder leeren Abschnitt. Das Aktualisieren des testID eines Abschnitts verwendet sein Text-Layout wieder und behält die Anzahl der onTextLayout-Callbacks bei.

#Was Headless-Läufe von der Plattform übernehmen

Ein Headless-Lauf hat die echte Runtime und keine Plattform. Er übernimmt die Rolle der Plattform, die das Protokoll von NSH festlegt, und nichts von dem, was nur eine echte Plattform kann:

• Native Animationen laufen Frame für Frame bis zum Ende: start(callback)-Callbacks werden ausgeführt, ebenso alles, was auf sie wartet. Endlose Schleifen laufen, bis die App sie stoppt.
• Zurückgehen entfernt Screens und schließt Modals wie eine Plattform (app.back()).
• Dialoge werden beantwortet: durch das onDialog des Tests, sonst durch ihren Abbrechen-Button, sonst werden sie geschlossen, sofern das möglich ist. Ein Dialog, den nur seine anderen Buttons beantworten, lässt den Schritt fehlschlagen, der ihn angezeigt hat, bis der Test angibt, welcher Button gedrückt werden soll.
• Die Zwischenablage enthält Text: was die App kopiert, wird beim Einfügen zurückgelesen (clipboard, um mit etwas Text zu starten).
• Der Host der Seite beantwortet host, wenn die nsh.json der App in web.host einen benennt (Der Host der Seite).
• Die App läuft mit ihren Capabilities: was ihr nsh.json in capabilities deklariert, wird wie auf einem Gerät durchgesetzt, sodass abgelehnt wird, was sie nicht deklariert.
• URLs werden aufgezeichnet: was die App öffnet, wird als geöffnet gemeldet, und app.openedUrls() listet es auf.
• Auswahlen werden beantwortet: mit den Dateien des Tests (onPick), sonst abgebrochen, sodass Picker.pickImages mit [] aufgelöst wird.
• Sprache kommt vom Test: Speech.available() wird mit true aufgelöst, eine Session startet sofort und hört, was hear sagt.
• Modals erscheinen sofort: onShow kommt, sobald eines präsentiert wird.
• Bilder werden nicht geladen: weder onLoad noch onError kommt, und Image.getSize und Image.prefetch werden abgelehnt.
• Was nur eine echte Plattform beantwortet, lässt den Schritt fehlschlagen: ein Bild oder Dateien in der Zwischenablage.

#Der Host der Seite

Eine für das Web veröffentlichte App erhält ihren Host von ihrer Seite: nsh.json web.host, ein Modul, das createHost(player) exportiert (Web). Headless-Läufe laden dieses Modul für jede App, die ein Test öffnet, vor dem Start der App, in einem eigenen JavaScript-Kontext (Timer und console, nichts vom Browser, keine Imports): Sein call beantwortet das host.call der App, sein player.hostEvent erreicht host.on, und host.available() ist true. Ein call, das einen Fehler wirft, abgelehnt wird oder etwas zurückgibt, das kein JSON ist, lässt den Aufruf der App mit seiner Meldung fehlschlagen, wie auf der Seite, und Events, die vor dem Start der App gesendet werden, erreichen ihre Top-Level-Listener, sobald sie läuft. --web-host <module> benennt ein anderes Modul. Das capabilities.host der App muss auflisten, was sie aufruft, wie auf der Seite. Das Timeout eines Aufrufs und die eigenen Timer des Hosts laufen auf der Zeit der App, sodass eine manuelle Uhr sie weiterbewegt (app.clock.runFor). In einem Browser (--target web) führt die Entwicklungsseite für jede App das web.host von nsh.json aus, wie eine veröffentlichte Seite; auf den anderen Plattformen (--target) haben die Apps keinen Host: host.available() ist false.

// nsh.json: { "capabilities": { "host": ["echo"] }, "web": { "host": "./host.js" } }
import { open, test } from "nsh/test";

test("calls reach the page's host", async () => {
  const app = await open("./App.tsx");
  await app.press("label:call");
  await app.waitFor('text:{"n":1}');
});

examples/host-echo enthält eine App, ihren Host und ihre Tests.

#Erwartungen

expect(value) prüft Werte wie Jest, so wie JS sie erzeugt hat: toBe ist Object.is, toEqual vergleicht Member für Member, und ein Date, ein Map oder ein Uint8Array wird als das verglichen, was es ist. Jede Prüfung wirft einen Fehler, wenn sie nicht erfüllt ist. .not kehrt sie um: expect(app.texts()).not.toContain("Error"). Bei einer Funktion prüft toThrow, was ihr Aufruf wirft; bei einem Promise oder einer Funktion, die eines zurückgibt, prüfen rejects und resolves, was es liefert, wie in Jest: await expect(save()).rejects.toMatchObject({ code: "ERR_ACCESS_DENIED" }).

Eine fehlgeschlagene Prüfung nennt, was sie erhalten hat und was sie erwartet hat, so geschrieben, wie JS es schreiben würde: expected Date(2024-01-02T00:00:00.000Z) to equal Date(2024-01-01T00:00:00.000Z).

rejects und resolves haben außerdem ein eigenes .not: await expect(load()).resolves.not.toBe(null).

#Auf einer echten Plattform

nsh test --target macos (oder linux, windows, gpui, web, ios, android) führt dieselben Tests auf dem Entwicklungshost der Plattform statt headless aus: Jeder open startet die App in einem eigenen Fenster mit einem frischen Datenverzeichnis, und die Schritte agieren mit der eigenen Eingabe der Plattform an den Views, die ihre Selektoren benennen, wie Playwright in einem Browser:

• Ein Press ist ein Klick in der Mitte der View, ein Long Press ein gehaltener Klick, type klickt das Input an und tippt seine Tasten, scroll ist eine Trackpad-Geste über der Scroll-View, back ist das, was ein Benutzer tut (Escape unter macOS und Linux, die Zurück-Taste der Maus unter Windows und in GPUI, die Zurück-Schaltfläche des Browsers im Web, ein nach unten gewischtes Sheet, die Escape-Geste von VoiceOver, solange ein Menü, ein Popover oder Sheet geöffnet ist, sonst die Zurück-Schaltfläche der Kopfzeile unter iOS, die Zurück-Taste unter Android);
• eine View außerhalb des Bildschirms wird zuerst in den sichtbaren Bereich gescrollt, Geste für Geste; auf einem Touchscreen setzt der Finger dort an, wo die Seite selbst ihn annimmt, abseits der Views, die einem Drag folgen (ein Slider, eine Zeichenfläche), wie ein Benutzer scrollt;
• Selektoren, Waits und Queries sehen dasselbe Modell der App wie Headless-Läufe, aufgebaut aus dem, was der Host zeichnet, sodass sie dieselben Views finden;
• Dialoge sind die der Plattform: app.dialogs() liest sie aus, und ihre Beantwortung (onDialog, oder ihr Abbrechen-Button, wenn der Test nichts angibt) drückt ihren Button;
• app.screenshot(path) erstellt ein Bild des Fensters.

nsh test --target macos                       # the app's tests in macOS windows
nsh test --target linux                       # in GTK windows (xvfb-run -a … on a machine without a display)
nsh test --target windows                     # in Win32 windows
nsh test --target ios                         # in an iOS simulator
nsh test --target android                     # on the Android device or emulator adb lists first
nsh test --target gpui                        # in GPUI windows (macOS, Windows, Linux)
nsh test --target web                         # in a headless Chrome, Edge or Chromium
nsh test tests/form.test.tsx --target macos   # one file

Das Fenster öffnet sich in der Größe des Viewports (390 × 844, sofern open nichts anderes angibt), innerhalb des Bildschirms; unter iOS und Android füllt die App den Bildschirm des Geräts aus, in der Größe des Geräts. Die App läuft als die Plattform des Targets (platform.os). Eine manuelle clock funktioniert wie headless: app.clock.runFor, fastForward und setSystemTime bewegen die Zeit der App sofort (Timer, requestAnimationFrame einen Frame auseinander, Date), app.wait(ms), waitFor und waitUntil bewegen sie ebenfalls, und jeder Frame, den die Plattform zeigt, bewegt sie um einen Frame (1/60 s), sodass die Zeit der App vergeht, während sie animiert. Die eigenen Animationen der Plattform und das delay einer Route brauchen echte Zeit. Die Requests der App erreichen den Test wie headless: network-Routen beantworten sie, ein Request, auf den keine Route passt, schlägt fehl, und "live" lässt sie ins Netzwerk des Hosts durch; app.requests() listet sie alle auf. Sockets und WebSockets verbinden sich mit "live" im Netzwerk des Hosts und werden sonst wie headless abgelehnt. storage liegt im Storage der App, wenn sie startet, und app.storage() liest es aus der App. locale, reducedMotion und safeArea enthalten, wenn open sie vorgibt (einschließlich eines Standardwerts), was immer die Plattform meldet, und ein von ihm vorgegebenes colorScheme schaltet das Erscheinungsbild des Systems um ("light" ebenfalls); was es weglässt, bestimmt die Plattform, und die Clipboard-Aufrufe der App werden aus der eigenen Zwischenablage des Tests bedient (clipboard ist zunächst ihr Text, app.clipboard() liest sie aus), sodass die Zwischenablage des Rechners unverändert bleibt; Kopieren und Einfügen eines Text-Inputs verwenden die des Systems. host.params erreicht die App, app.host.send sendet Events, und die URLs, die die App öffnet, werden für app.openedUrls() aufgezeichnet, statt geöffnet zu werden. host.handlers läuft headless, wo der Test die Aufrufe der App beantwortet. open prüft seine Optionen gegen das Target: width und height unter iOS und Android, ein platform einer anderen Geräteart (das eines Telefons auf einem Desktop oder im Web, das eines Desktops oder des anderen Telefons unter iOS oder Android) und host.handlers werden mit ERR_NSH_TEST_UNSUPPORTED abgelehnt, sodass ein Test so läuft, wie er geschrieben ist, oder sagt, was er braucht. Der platform eines Desktops ("macos" für Maus und Tasten eines Desktops) läuft auf jedem Desktop-Target und im Web, als die Plattform dieses Targets und immer als Desktop: Im Browser startet die Seite unabhängig von ihrer Breite im Desktop-Idiom, wo sie ohne platform (oder mit "web") ihr Idiom wie ein Browser bestimmt (ein Desktop ab 600 Punkten Breite). Eine App mit eigenen Rust-Crates läuft in einem Entwicklungshost, der mit ihren Crates gebaut wurde, den NSH für die Plattform baut; der Host einer Rust-App führt ihre Root aus, sodass open(".") sie dort startet wie headless.

Im Web laufen die Apps auf der Seite des Entwicklungshosts in einem Headless-Chrome, -Edge oder -Chromium: dem auf diesem Rechner installierten oder der ausführbaren Datei, die --browser <PATH> benennt (ein Browser ist erforderlich: nsh test gibt an, wo gesucht wurde, wenn keiner gefunden wird). Ein Browser bedient den Lauf, und jeder open erhält eine Seite mit eigenem Storage. Die Eingabe ist die vertrauenswürdige Eingabe des Browsers, wie die eines Benutzers: Mausklicks, Scrollen mit dem Mausrad und Tasten.

Unter iOS laufen die Apps im Entwicklungshost in einem iOS-Simulator: dem gestarteten, sonst dem neuesten iPhone, das nsh test bootet. Die Schritte sind Berührungen eines Fingers und die Eingabe der Software-Tastatur, wie UIKit sie vom Gerät erhält. setColorScheme schaltet das Erscheinungsbild des Simulators um, das nsh test nach der App zurücksetzt, und der Bildschirm hat die Größe des simulierten Geräts.

Unter Android laufen die Apps im Entwicklungshost auf dem ersten Gerät oder Emulator, das adb devices auflistet, mit eigenem Storage. Die Schritte sind Berührungen eines Fingers und Tasten einer Tastatur, wie die Views der App sie vom Gerät erhalten; back ist das Zurück des Systems. setColorScheme schaltet das Dark Theme des Geräts um, das nsh test nach der App zurücksetzt.

#Schritte von der Standardeingabe

Wenn statt Tests der Einstiegspunkt der App angegeben wird, öffnet nsh test die App im echten Netzwerk, lässt sie 1,2 s laufen und führt dann die Schritte aus, die die Standardeingabe liefert, mit app der App:

echo 'await app.press("text:+1"); expect(app.texts()).toContain("1");' | nsh test App.tsx

Die 1,2 s lassen die Idle-Garbage-Collection der Engine vor dem ersten Schritt laufen, sodass eine App, die loslässt, was sie noch verwendet, dies zeigt: Ihre Handler funktionieren nicht mehr.

Für die Beispiele gibt es Tests als Ausgangspunkt: examples/gallery-rs für eine Rust-App (cargo test, ein Modul pro Demo, und App.test.tsx), examples/rust-exports für eine App mit einem Rust-Crate, examples/counter und examples/gallery/tests (Storage, Inputs, eine lange Liste, gestubbte Requests, Dark Mode, eine manuelle Uhr) für TSX-Apps.

#Tracing mit —trace

--trace gibt jeden Mount-Batch der Apps aus, die die Tests öffnen, unter dem Schritt, in dem er kam, sowie die Zeit jedes Commits. In Rust gibt ein Test dasselbe aus: observe übergibt ihm jeden Batch mit seinem Schritt, und EngineConfig::trace protokolliert die perf-Zeilen über das Crate log (Target nsh::perf; installiere im Test einen Logger wie env_logger):

let mut config = EngineConfig::new(Root::of::<my_app::App>());
config.trace = true;
let mut app = Headless::start(config).unwrap();
app.observe(|step, batch| nsh_testing::print_batch(&mut std::io::stdout(), step, batch));
app.press("Add").unwrap();

nsh test akzeptiert --trace für eine Testdatei oder für den Einstiegspunkt der App mit den Schritten auf der Standardeingabe:

nsh test App.test.tsx --trace
nsh test App.tsx --trace                                   # the first frame, then 1.2 s idle
echo 'await app.press("Add")' | nsh test App.tsx --trace    # and a press
echo 'await app.press("Add")' | nsh test App.tsx --trace --target ios   # the same in an iOS simulator

Mit --target ist der Trace der der Plattform: die Batches, die der Host angewendet hat, unter den Schritten, die sie ausgelöst haben, und die eigenen Zeitmessungen des Hosts für jeden Commit und jedes Event, auf der Hardware des Geräts.

Verwende ihn, um:

• zu prüfen, dass eine App (oder eine Demo) ohne Fehler gebaut, ausgewertet und gerendert wird;
• genau zu sehen, welche nativen Views eine Änderung erzeugt, verschiebt oder aktualisiert und wie viele;
• die Kosten des ersten Frames, eines Taps und jedes Scroll-Frames zu messen;
• Regressionen in der CI zu erkennen.

#Die Ausgabe lesen

Hier ist das Counter-Beispiel mit einem Tastendruck (echo 'await app.press("+1")' | nsh test examples/counter/App.tsx --trace), gekürzt:

✓ bundled App.tsx (3255 B in 6.2 ms)
perf commit: 56 ops, 271µs (list js 5µs), 49 mount items, 21 nodes
perf first frame: eval 187µs, total 820µs
── open(App.tsx): 49 items
   LayoutDirection { rtl: false }
   Create { id: 2, kind: View }
   Create { id: 4, kind: Text }
   Insert { parent: 2, child: 4, before: None }
   ...
   Frame { id: 2, x: 0, y: 0, w: 390, h: 844 }
   Frame { id: 4, x: 24, y: 64, w: 342, h: 34 }
   ...
   Text { id: 4, text: "nsh counter", content: 342x34 @ 0,0 }
   Text { id: 14, text: "0", content: 36x77 @ 0,0 }
perf event Press on view 26
perf event js: 413µs
perf commit: 10 ops, 672µs (list js 7µs), 7 mount items, 24 nodes
── press(+1): 7 items
   Create { id: 42, kind: Text }
   Insert { parent: 32, child: 42, before: None }
   Frame { id: 32, x: 24, y: 366, w: 342, h: 43 }
   Frame { id: 42, x: 0, y: 23, w: 342, h: 20 }
   Text { id: 14, text: "1", content: 36x77 @ 0,0 }
   Text { id: 42, text: "• 1", content: 342x20 @ 0,0 }
   Text { id: 34, text: "Recent values: 1", content: 342x17 @ 0,0 }
✓ App.tsx › steps (1.4s)

#Batches und Mount-Items

Jeder ── step: N items-Block ist ein Mount-Batch unter dem Schritt, in dem er angekommen ist: alles, was die Plattform für einen Frame in einem Sprung zum Main-Thread auf native Views anwendet. Die Zeilen darin sind Mount-Items:

Es wird nur gesendet, was sich geändert hat: Ein Tap, der eine Zahl ändert, sendet ein einziges Text-Item; Views erhalten keinen Standardstil und keine leere Event-Maske; unveränderte Frames werden nicht gesendet. Ein Scroll-Frame, der keine neue Zeile sichtbar macht, erzeugt gar keinen Batch.

#Die perf-Zeilen

Einzelmessungen hängen stark vom Taktzustand der CPU ab (ein Rechner, der gerade aus dem Leerlauf aufgewacht ist, ist langsam). Vergleiche Läufe auf demselben Rechner, schau auf das Minimum mehrerer Läufe und vertraue den Op- und Item-Anzahlen mehr als den Mikrosekunden.

#Scrollen

app.scroll("id:photos", px(3000.0)).unwrap();

echo 'await app.scroll("id:photos", 3000)' | nsh test examples/gallery/Bench.tsx --trace

scroll bewegt die Liste 10 Punkte pro Frame, mit 60 Frames pro Sekunde, und der Batch jedes Frames wird ausgegeben:

perf commit: 55 ops, 1667µs (list js 771µs), 46 mount items, 414 nodes
── scroll(id:photos, 3000): 46 items
   Create { id: 792, kind: View }
   Insert { parent: 94, child: 792, before: None }
   ...

Bei einer Liste zeigt dies die Virtualisierung in Aktion: welche Frames neue Zeilen binden, wie viele Operationen eine Zeile kostet und dass Frames, die keine neue Zeile sichtbar machen, nichts erzeugen. Verwende es mit einem Release-Build (cargo test --release oder ./target/release/nsh in einem Checkout), um aussagekräftige Zeiten zu erhalten.

#In der CI

Headless-Tests brauchen weder Gerät noch Display und laufen daher auf Linux-Runnern: cargo test für die Tests einer Rust-App und nsh test, das nichts außer der CLI benötigt. Jeder fehlschlagende Test lässt beide mit einem Exit-Code ungleich null enden: ein Test, der fehlschlägt, eine App, die sich nicht bauen lässt oder nichts rendert, eine Exception, die die App während eines Schritts wirft.

# .github/workflows/test.yml
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: cargo test                            # a Rust app's tests
      - run: nsh test --junit test-results.xml     # its TypeScript tests, or a TSX app's

(Installiere die nsh-CLI auf dem Runner so, wie du sie lokal installierst; siehe Installation.)

--junit <FILE> schreibt die Ergebnisse außerdem als JUnit-XML-Bericht, den CI-Dienste (GitHub-Actions-Test-Reporter, GitLab, Jenkins, Azure Pipelines) pro Test anzeigen: ein testsuite pro Testdatei, ein testcase pro Test, mit dem, was fehlgeschlagen ist, wo, und den Texten auf dem Bildschirm.

Um die Performance abzusichern, zeichne die Item-Anzahlen einiger Interaktionen auf (die ── … : N items-Zeilen und die ops- / mount items-Zahlen von --trace) und lass den Test fehlschlagen, wenn sie wachsen. Anzahlen sind deterministisch; Zeiten auf geteilten CI-Rechnern sind es nicht.

#testID für UI-Tests

Headless-Tests prüfen, was die Runtime rendert, und ihre id:-Selektoren finden Views anhand der Test-ID. Um die echte native UI mit den Test-Tools der Plattform (XCUITest, Espresso / UI Automator, Appium, Maestro) zu steuern, gib Views eine Test-ID: .test_id(…) in Rust, testID in TSX:

view()
    .test_id("add-to-cart")
    .p_3()
    .on_press(add)
    .child(text(move || format!("{} items", count.get())).test_id("cart-count"))

<View testID="add-to-cart" onPress={add} style={{ padding: 12 }}>
  <Text testID="cart-count">{`${count()} items`}</Text>
</View>

Die Test-ID ist eine Methode jedes Elements in Rust, einschließlich der Elemente von Komponenten (button().test_id("save"), das die Wurzel der Komponente benennt), und testID eine Prop jedes Elements und jeder Rust-Komponente (Button, Dialog, …). Sie ändert nicht, was Screenreader vorlesen; verwende dafür accessibilityLabel (siehe Barrierefreiheit). In der Ausgabe von --trace erscheint sie im ViewProps-Item der View als test_id: Some("add-to-cart").

#Siehe auch

• Performance: worauf man bei diesen Zahlen achten sollte
• Dev-Server und Debugging
• Architektur: Ops, Commits und Mount-Batches