टेस्टिंग

NSH ऐप्स को headless चलाता है: असली इंजन (वही reactive graph, renderer, कंपोनेंट, layout और list virtualization जो डिवाइस पर होते हैं, और TSX के लिए QuickJS), 60 Hz पर display frames के साथ, लेकिन न कोई सिमुलेटर, न कोई डिवाइस और न कोई विंडो। यह हर उस जगह चलता है जहाँ Cargo या CLI चलता है, Linux CI मशीनों सहित, और दो काम करता है:

• यह टेस्ट चलाता है: हर टेस्ट ऐप खोलता है, वही स्टेप लेता है जो एक उपयोगकर्ता लेता (press, type, scroll), और जाँचता है कि स्क्रीन पर क्या है। Rust ऐप के टेस्ट Rust में होते हैं, जिन्हें cargo test nsh-testing crate के साथ चलाता है; TypeScript में लिखे टेस्ट nsh test से चलते हैं, TSX ऐप्स और Rust ऐप्स दोनों के लिए;
• --trace के साथ, यह रनटाइम द्वारा नेटिव views को भेजा गया हर ऑपरेशन टाइमिंग के साथ प्रिंट करता है: पहला फ्रेम, एक tap या स्क्रॉलिंग का एक फ्रेम कितना खर्च करता है।

#टेस्ट लिखना

वही टेस्ट, Rust और TypeScript में: यह ऐप को उसके storage में खाली todo सूची के साथ खोलता है, टाइप करता है, press करता है और जाँचता है कि स्क्रीन क्या दिखाती है।

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

#cargo test के साथ Rust में टेस्ट

Rust ऐप के टेस्ट उसके crate के integration tests होते हैं, जिनमें nsh-engine और nsh-testing (इसकी default features, QuickJS के बिना) 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) फ़ोन-आकार का इंजन (390×844 points) है जिसमें और कुछ सेट नहीं होता; इसके फ़ील्ड वही सेट करते हैं जो नीचे open के विकल्प सेट करते हैं: storage (MemoryStorage::new(entries)), network (StubNetwork, नीचे), viewport, environment (appearance, locale, reduced motion), clock (Clock::manual(time), नीचे)। nsh_testing::Headless::start(config) ऐप शुरू करता है और उसके दिखाए views का एक मॉडल रखता है। इसके स्टेप वही हैं जो नीचे nsh test के हैं, उन्हीं selectors के साथ, 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()) स्क्रीन पर मौजूद चीज़ें पढ़ते हैं। जब कोई स्टेप नहीं लिया जा सकता, तो वह स्क्रीन के टेक्स्ट के साथ एक error लौटाता है।

nsh_testing::tsx(entry, sets) (feature bundle) किसी ऐप की TSX entry को उसी तरह खोलता है, जिसे NSH और crate के UI sets के विरुद्ध बनाया गया हो (Building with Rust)। examples/gallery-rs अपने Rust root को इसी तरह टेस्ट करता है, हर डेमो के लिए एक मॉड्यूल; examples/rust-exports अपनी TSX entry को Rust से टेस्ट करता है।

nsh test ये टेस्ट भी चलाता है: Rust crates वाले ऐप की डायरेक्टरी (nsh.json "rust") दिए जाने पर, यह टेस्ट फ़ाइलों से पहले उसके हर crate के लिए cargo test चलाता है, और Rust टेस्ट को TypeScript टेस्ट के साथ दिखाता और गिनता है (✓ src/lib.rs › tests::adds), अपने सारांश और अपनी --junit रिपोर्ट में। इसलिए nsh test Rust ऐप, crate वाले TSX ऐप और सामान्य TSX ऐप, सभी के लिए एक ही कमांड है, और nsh check भी इसी तरह TypeScript को type check करने से पहले crates पर cargo check --all-targets चलाता है।

#nsh test के साथ टेस्ट

टेस्ट फ़ाइल आपके कोड के बगल में एक *.test.tsx या *.test.ts फ़ाइल होती है। यह nsh/test import करती है, जैसा ऊपर App.test.tsx करता है:

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)

विफल टेस्ट दिखाता है कि क्या throw हुआ, टेस्ट फ़ाइल में कहाँ, और जो ऐप उसने खोला उसकी स्क्रीन के टेक्स्ट। कोई भी विफलता nsh test को non-zero कोड के साथ बंद करती है। nsh init ऐप के साथ एक App.test.tsx बनाता है, और nsh check टेस्ट फ़ाइलों को बाकी कोड के साथ type check करता है (.nsh/types nsh/test घोषित करता है)।

हर टेस्ट फ़ाइल अपने अलग इंजन पर चलती है, और उसके टेस्ट क्रम से एक के बाद एक चलते हैं। open ऐप को दूसरे इंजन पर शुरू करता है, हर बार नया, इसलिए टेस्ट कभी state साझा नहीं करते; टेस्ट के खत्म होने पर उसके खोले ऐप्स बंद हो जाते हैं। टेस्ट तब विफल होता है जब वह throw करे, जब उसका लौटाया promise reject हो, और अपने timeout के बाद: 30 सेकंड, या वे मिलीसेकंड जो test का तीसरा आर्गुमेंट देता है (test("syncs", body, 60_000))। जिस ऐप के अपने Rust crates हैं (nsh.json "rust") वह अपने टेस्ट एक headless runner में चलाता है जिसे NSH उनके साथ बनाता है, उसी तरह; Rust ऐप में (nsh.json "root", Building with Rust), open(".") उसका root कंपोनेंट शुरू करता है।

#टेस्ट को समूहबद्ध करना और सेट अप करना

describe, hooks और test के variants 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");
});

कोई hook async हो सकता है; उसका timeout 30 सेकंड है जब तक दिया न जाए। टेस्ट और hooks फ़ाइल लोड होते समय घोषित होते हैं: किसी टेस्ट या hook के भीतर घोषित टेस्ट throw करता है।

#ऐप खोलना

open(entry, options?) entry पर मौजूद ऐप को बनाता है (टेस्ट फ़ाइल के सापेक्ष; हर entry प्रति run एक बार बनती है), उसे 390×844 viewport पर शुरू करता है और तब resolve होता है जब वह render हो चुका हो और शांत हो। --target के साथ, ऐप विकल्पों के साथ वैसे ही चलता है जैसे टेस्ट उन्हें देता है: जिस विकल्प को target का प्लेटफ़ॉर्म पूरा नहीं कर सकता, वह open को ERR_NSH_TEST_UNSUPPORTED के साथ reject करवाता है, और उसका नाम बताता है (देखें On a real platform)।

#host ऐप की भूमिका निभाना

किसी नेटिव ऐप में embed किया गया ऐप उससे host के ज़रिए बात करता है। टेस्ट में, टेस्ट host ऐप की भूमिका निभाता है: host.params वे launch parameters देता है जिन्हें ऐप शुरू में पढ़ता है, और host.handlers ऐप के host.call का जवाब देता है और उसके host.post सुनता है, नाम के अनुसार। Handler एक value होता है, जो हर call का जवाब देता है, या call के data का एक फ़ंक्शन जो जवाब लौटाता है (या उसका promise)। फ़ंक्शन जो throw करता है वह call को reject करता है, जैसा host ऐप की error करती है। जिस नाम को handlers सूचीबद्ध नहीं करता उसकी call विफल होती है, जैसा उस host ऐप में होता है जो कुछ handle नहीं करता।

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) एक event भेजता है, फिर तब तक इंतज़ार करता है जब तक ऐप शांत न हो जाए। app.host.calls() और app.host.posts() वह सूचीबद्ध करते हैं जो handlers को मिला, क्रम से: name और data।

ऐप जो URLs खोलता है (openUrl, किसी TextView के links links="open" के साथ) वे रिकॉर्ड किए जाते हैं और ऐप को खुले हुए के रूप में बताए जाते हैं, और इस मशीन पर कुछ नहीं खुलता। app.openedUrls() उन्हें सूचीबद्ध करता है:

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

#नेटवर्क को stub करना

network routes को "<METHOD> <URL>" के अनुसार सूचीबद्ध करता है (सादा URL एक GET है; * किसी भी टेक्स्ट से मेल खाता है)। जिस अनुरोध से कोई route मेल नहीं खाता वह विफल होता है, इसलिए टेस्ट बिना कहे कभी नेटवर्क तक नहीं पहुँचते। Route एक response होता है, या अनुरोध का एक फ़ंक्शन जो एक लौटाता है (या उसका promise); Rust में, StubNetwork::new(routes) वही routes लेता है, हर एक StubResponse या 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"]);

Route का फ़ंक्शन अनुरोध पाता है (method, url, headers, body टेक्स्ट के रूप में) और टेस्ट फ़ाइल में चलता है, इसलिए यह अनुरोध गिन सकता है या उस चीज़ से जवाब दे सकता है जो टेस्ट ने सेट की। जो फ़ंक्शन throw करता है वह अनुरोध को और उस स्टेप को विफल करता है जिसने उसे किया। app.requests() ऐप द्वारा किए गए अनुरोध क्रम से सूचीबद्ध करता है, उसी तरह।

Connections भी टेस्ट में ही रहते हैं: ऐप के sockets (net) और WebSockets (global WebSocket और websocket मॉड्यूल) कोई connection नहीं खोलते जब तक network "live" न हो। ऐप की अपनी capability जाँचें पास होने के बाद, net.connect और websocket मॉड्यूल का connect code ERR_NSH_TEST_NETWORK के साथ reject होते हैं, और global WebSocket error फ़ायर करता है, फिर close (1006, clean नहीं), जैसे उस connection के लिए जिसे नेटवर्क ने ठुकरा दिया। "live" के साथ, वे ऐप के अनुरोधों के साथ असली नेटवर्क से जुड़ते हैं। Rust में, EngineConfig::refuse_connections Headless ऐप के लिए यही करता है: ऐप जिससे जुड़ता है उसका एक फ़ंक्शन (WebSocket का URL, socket का host:port) जो वह error लौटाता है जिससे उसकी call विफल होती है।

#समय को नियंत्रित करना

सिस्टम की clock पर, ऐप के timers और नेटिव animations उतना ही समय लेते हैं जितना डिवाइस पर, और उनका इंतज़ार करने वाले टेस्ट भी। Manual clock के साथ (Rust में EngineConfig::clock, TypeScript में open का clock), ऐप एक ऐसी clock पर चलता है जिसका समय केवल तब बढ़ता है जब टेस्ट उसे बढ़ाता है, और तुरंत, जैसे Jest के fake timers या Playwright के page.clock के साथ। app.clock वही clock है, और null जब ऐप सिस्टम की clock पर चलता है:

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

जिस StubNetwork के responses में delay है वह .with_clock(clock.clone()) के साथ manual clock का अनुसरण करता है। नीचे के स्टेप nsh test के हैं; Headless में इनमें से हर एक है (run_for, fast_forward, set_system_time)।

Date, performance.now() और Intl की डिफ़ॉल्ट तारीख clock का अनुसरण करती हैं। स्टेप जो चल रहा है उसे इंतज़ार किए बिना पूरा करते हैं: जब तक ऐप frames माँगता है या कोई नेटिव animation चलती है, frames एक के बाद एक आते हैं, हर एक clock पर एक frame के समय (1/60 s) बाद। 300 ms का transition कुछ मिलीसेकंड लेता है, और उस दौरान देय timer चलता है। जो animation हमेशा loop करती है (एक spinner) वह clock के साथ चलती है: वह तब घूमती है जब टेस्ट clock को बढ़ाता है। app.wait(ms) और long press अपने समय के बराबर clock बढ़ाते हैं। जो timer बाद में देय होता है वह तभी चलता है जब टेस्ट clock को वहाँ तक ले जाए। waitFor और waitUntil इंतज़ार करते समय clock को बढ़ाते हैं, एक बार में एक display frame, हर frame के बाद देखते हुए, इसलिए timer जो दिखाता है वह इंतज़ार करते ही, एक पल में आ जाता है: waitFor("Saved", { timeout: 15_000 }) clock को अधिकतम पंद्रह सेकंड बढ़ाता है। उनका timeout दोनों clocks पर गिना जाता है: इंतज़ार ऐप की clock को अधिकतम उतना ही बढ़ाता है, और तब reject होता है जब उतना असली समय भी बीत चुका हो, इसलिए जो ऐप के बाहर से आता है (route का फ़ंक्शन, नेटवर्क) उसके पास उतना ही समय होता है जितना सिस्टम की clock पर। Gallery के टेस्ट इसी तरह चलते हैं (examples/gallery/tests): animations का इंतज़ार करने वाले इसके बारह टेस्ट 28 s की जगह 6 s लेते हैं।

#चरण

चरण व्यूज़ को सेलेक्टर से नाम देते हैं, जो Playwright की तरह लिखे जाते हैं:

जो हिस्सा छोटे अक्षरों के शब्द और कोलन से शुरू होता है, वह एक प्रीफ़िक्स का नाम होता है (id, label, role, text, view), इसलिए tapped: solo एक स्टेप एरर है जो उन्हें सूचीबद्ध करता है। जो टेक्स्ट, लेबल या टेस्ट id इस तरह शुरू होता है, वह अपना प्रीफ़िक्स लेता है, जो बाकी हिस्से को जैसा लिखा है वैसा पढ़ता है: text:tapped: solo, label:note: draft, id:row:2। नए प्रीफ़िक्स आने पर भी सेलेक्टरों का अर्थ वही रहता है।

label:, text: और किसी role का नाम रेगुलर एक्सप्रेशन भी ले सकते हैं: text:/^Buy/i, जो Rust के regex क्रेट के सिंटैक्स में लिखा जाता है (JavaScript के क्लास, ग्रुप, एंकर और क्वांटिफ़ायर, लीनियर टाइम में मैच होते हैं; फ़्लैग i, m और s)। >> उसके अंदर देखता है जो पिछले हिस्से ने मैच किया था (id:cart >> role:button[Remove]), और nth=<n> मैचों में से एक रखता है, 0 से शुरू करके (text:Delete >> nth=1)। सेलेक्टर वे व्यूज़ ढूँढता है जिन्हें उपयोगकर्ता सबसे पहले देखेगा: सबसे ऊपर के मोडल में, फिर स्क्रीन पर, और नेविगेशन स्टैक में केवल सबसे ऊपर की स्क्रीन। यह वही मैच करता है जो उपयोगकर्ता को दिखता है: वे व्यूज़ जिनका क्षेत्रफल हो, visibility: hidden के बाहर हों, विंडो के अंदर हों और उन व्यूज़ के अंदर हों जो उन्हें क्लिप करते हैं (overflow: hidden), या किसी ऐसे स्क्रॉल व्यू की सामग्री में कहीं भी, जिसे उपयोगकर्ता स्क्रॉल कर सकता है और जिसे स्क्रॉल करने पर वे सामने आ जाते हैं (opacity और transforms को छोड़कर, जैसा Playwright में होता है)। जो चरण किसी व्यू पर कार्य करता है (press, type, clear, submit, scroll, longPress) उसे ठीक एक व्यू चाहिए: कई व्यूज़ से मैच करने वाला सेलेक्टर चरण को विफल कर देता है, और एरर बताता है कि उसे कैसे सीमित करें।

एक चरण तब रिज़ॉल्व होता है जब ऐप ने 100 ms तक कुछ रेंडर नहीं किया हो और कोई नेटिव एनिमेशन न चल रहा हो जो अपने आप खत्म होता है (अधिकतम 2 s, उन ऐप्स के लिए जो हर समय रेंडर करते हैं; मैनुअल क्लॉक पर, ऐप के समय के भी 2 s), ताकि अगली लाइन चलने तक उसने जो बदला वह स्क्रीन पर हो; जो बाद में आता है (रिस्पॉन्स, टाइमर) उसके लिए waitFor का उपयोग करें। मैनुअल क्लॉक पर चरण उन 100 ms की प्रतीक्षा नहीं करता: वह तब रिज़ॉल्व होता है जब ऐप वह सब चला चुका हो जो चरण और क्लॉक के समय ने देय बनाया था (अभी देय टाइमर, प्रॉमिस, तुरंत उत्तर दिया गया स्टब्ड रिस्पॉन्स) और कोई फ़्रेम नहीं चाहता, जब तक कोई रिक्वेस्ट अब भी जारी न हो, इसलिए मैनुअल क्लॉक पर टेस्ट अपने चरणों के बीच बिना ठहराव के चलते हैं। जिसका उत्तर कोई दूसरा थ्रेड देता है (nsh/host कॉल, फ़ाइल रीड, थ्रेड पर Rust टास्क का काम) वह चरण के रिज़ॉल्व होने के बाद पहुँचता है: जो वह दिखाता है उसके लिए waitFor करें। जो एनिमेशन हमेशा लूप में चलता है, जैसे लोडिंग स्पिनर, वह पृष्ठभूमि में चलता रहता है जबकि चरण और waitFor आगे बढ़ते हैं, जैसे ब्राउज़र के टेस्ट में अनंत CSS एनिमेशन चलता है। चरण तब रिजेक्ट होता है, और टेस्ट विफल हो जाता है, जब उसके सेलेक्टर से कुछ मैच न हो (एरर स्क्रीन पर मौजूद टेक्स्ट सूचीबद्ध करता है), जब इस बीच ऐप ने कोई exception फेंका हो, और जब ऐप ने वह माँगा हो जिसका उत्तर केवल असली प्लेटफ़ॉर्म देता है।

जिन विफलताओं की टेस्ट अपेक्षा कर सकता है उनमें एक code होता है, जो जैसा है वैसा रहता है; उनके संदेश लोगों के लिए हैं और बदल सकते हैं, इसलिए टेस्ट कोड से मैच करता है:

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

app.spanStyle("id:guide") एक नेस्टेड <Text testID="guide"> पढ़ता है; text:word उस मैच का पहला अक्षर पढ़ता है। क्वेरी को id:note >> text:word से सीमित करें और दोहराए गए मैचों में से >> nth=0 से चुनें। क्वेरी किसी अनुपस्थित, अस्पष्ट या खाली स्पैन के लिए एरर रिपोर्ट करती है। किसी स्पैन का testID अपडेट करने पर उसका टेक्स्ट लेआउट दोबारा इस्तेमाल होता है और onTextLayout कॉलबैक की गिनती बनी रहती है।

#Headless रन platform की कौन-सी भूमिका निभाते हैं

Headless रन में असली runtime होता है, पर platform नहीं। यह platform की वही भूमिका निभाता है जो NSH का protocol परिभाषित करता है, और वह कुछ नहीं करता जो केवल असली platform कर सकता है:

• Native animations चलती हैं frame दर frame, अपने अंत तक: start(callback) callbacks चलते हैं, और जो उनकी प्रतीक्षा करता है वह भी चलता है। बिना अंत वाले loops तब तक चलते हैं जब तक app उन्हें रोक नहीं देता।
• पीछे जाना screens को pop करता है और modals को बंद करता है, जैसा platform करता है (app.back())।
• Dialogs का उत्तर दिया जाता है: test के onDialog से, नहीं तो उनके cancel बटन से, नहीं तो वे बंद कर दिए जाते हैं जब बंद किए जा सकें; जिस dialog का उत्तर केवल उसके अन्य बटन देते हैं, वह उस step को fail कर देता है जिसने उसे दिखाया, जब तक test यह न बता दे कि कौन-सा दबाना है।
• Clipboard में text रहता है: app जो copy करता है, वही paste करते समय वापस पढ़ा जाता है (clipboard से कुछ text के साथ शुरू किया जा सकता है)।
• पेज का host host का उत्तर देता है जब app का nsh.json web.host में किसी को नाम देता है (पेज का host)।
• App अपनी capabilities के अंतर्गत चलता है: उसका nsh.json capabilities में जो घोषित करता है, वह device की तरह लागू किया जाता है, इसलिए जो घोषित नहीं है वह अस्वीकार हो जाता है।
• URLs दर्ज किए जाते हैं: app जो खोलता है उसे खुला हुआ बताया जाता है, और app.openedUrls() उसे सूचीबद्ध करता है।
• Picks का उत्तर दिया जाता है: test की files से (onPick), नहीं तो रद्द कर दिया जाता है, इसलिए Picker.pickImages [] के साथ resolve होता है।
• Speech test की होती है: Speech.available() true के साथ resolve होता है, session तुरंत शुरू होता है और वही सुनता है जो hear कहता है।
• Modals तुरंत दिखते हैं: जब कोई modal प्रस्तुत होता है तब onShow आता है।
• Images load नहीं होतीं: कोई onLoad या onError नहीं आता, और Image.getSize तथा Image.prefetch reject हो जाते हैं।
• जिसका उत्तर केवल असली platform देता है, वह step को fail कर देता है: clipboard पर कोई image या files।

#पेज का host

वेब पर प्रकाशित app को अपना host अपने पेज से मिलता है: nsh.json web.host, एक module जो createHost(player) export करता है (Web)। Headless रन उस module को test द्वारा खोले गए हर app के लिए, app शुरू होने से पहले, अपने अलग JavaScript context में load करते हैं (timers और console, browser का कुछ नहीं, कोई imports नहीं): उसका call app के host.call का उत्तर देता है, उसका player.hostEvent host.on तक पहुँचता है, और host.available() true है। जो call throw करता है, reject करता है या JSON न होने वाला मान लौटाता है, वह app की call को अपने संदेश के साथ reject कर देता है, जैसा पेज पर होता है, और app शुरू होने से पहले भेजे गए events उसके शुरू होते ही उसके top-level listeners तक पहुँचते हैं। --web-host <module> किसी दूसरे module को नाम देता है। App के capabilities.host में वह सब सूचीबद्ध होना चाहिए जिसे वह call करता है, जैसा पेज पर। किसी call का timeout और host के अपने timers app के समय पर चलते हैं, इसलिए manual clock उन्हें आगे बढ़ाती है (app.clock.runFor)। Browser में (--target web) development पेज हर app के लिए nsh.json का web.host चलाता है, जैसा प्रकाशित पेज करता है; अन्य platforms पर (--target) apps का कोई host नहीं होता: host.available() 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 में एक app, उसका host और उनके tests हैं।

#Expectations

expect(value) मानों की जाँच Jest की तरह करता है, जैसा JS ने उन्हें बनाया: toBe Object.is है, toEqual सदस्य दर सदस्य तुलना करता है, और Date, Map या Uint8Array की तुलना वैसी ही की जाती है जैसा वह है। जब कोई जाँच सही नहीं होती तो वह throw करती है। .not उन्हें उलट देता है: expect(app.texts()).not.toContain("Error")। किसी function को देने पर toThrow जाँचता है कि उसे call करने पर क्या throw होता है; किसी promise को, या ऐसे function को जो promise लौटाता है, देने पर rejects और resolves जाँचते हैं कि वह किस पर settle होता है, जैसा Jest में: await expect(save()).rejects.toMatchObject({ code: "ERR_ACCESS_DENIED" })।

विफल होने वाली जाँच बताती है कि उसे क्या मिला और क्या अपेक्षित था, जैसा JS उन्हें लिखता: expected Date(2024-01-02T00:00:00.000Z) to equal Date(2024-01-01T00:00:00.000Z)।

rejects और resolves का भी अपना .not है: await expect(load()).resolves.not.toBe(null)।

#असली platform पर

nsh test --target macos (या linux, windows, gpui, web, ios, android) वही tests headless के बजाय platform के development host पर चलाता है: हर open app को अपनी अलग window में, नई data directory के साथ शुरू करता है, और steps platform के अपने input से उन views पर काम करते हैं जिन्हें उनके selectors नाम देते हैं, जैसा Playwright browser में करता है:

• press view के बीच में एक click है, long press एक रोका हुआ click है, type input पर click करता है और उसकी keys टाइप करता है, scroll scroll view पर एक trackpad gesture है, back वह है जो एक उपयोगकर्ता करता है (macOS और Linux पर Escape, Windows और GPUI में mouse का back बटन, web पर browser का back बटन, नीचे swipe की गई sheet, जब कोई menu, popover या Sheet खुला हो तब VoiceOver का escape gesture, अन्यथा iOS पर header का back बटन, Android पर back बटन);
• screen से बाहर का view पहले scroll करके दिखाया जाता है, एक बार में एक gesture; touch screen पर उँगली वहाँ पड़ती है जहाँ पेज खुद उसे ले जाता है, उन views के बगल में जो drag का अनुसरण करते हैं (slider, drawing area), जैसे उपयोगकर्ता scroll करता है;
• selectors, waits और queries app का वही model देखते हैं जो headless रन देखते हैं, जो host जो बनाता है उसी से तैयार होता है, इसलिए वे वही views ढूँढ लेते हैं;
• dialogs platform के अपने होते हैं: app.dialogs() उन्हें पढ़ता है, और किसी का उत्तर देना (onDialog, या जब test कुछ न कहे तो उसका cancel बटन) उसका बटन दबाता है;
• app.screenshot(path) window की तस्वीर लेता है।

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

Window viewport के आकार में खुलती है (390 × 844 जब तक open कुछ और न कहे), screen के भीतर; iOS और Android पर app device की screen भर देता है, device के आकार में। App target के platform के रूप में चलता है (platform.os)। Manual clock वैसे ही काम करता है जैसे headless में: app.clock.runFor, fastForward और setSystemTime app का समय तुरंत आगे बढ़ाते हैं (timers, requestAnimationFrame एक frame के अंतर पर, Date), app.wait(ms), waitFor और waitUntil भी उसे आगे बढ़ाते हैं, और platform जो हर frame दिखाता है वह उसे एक frame (1/60 s) आगे बढ़ाता है, इसलिए app का समय तब भी बीतता है जब वह animate हो रहा हो। Platform की अपनी animations, और route का delay, असली समय लेते हैं। App के requests test तक वैसे ही आते हैं जैसे headless में: network routes उनका उत्तर देते हैं, जिस request से कोई route मेल नहीं खाता वह fail होती है, और "live" उन्हें host के network तक जाने देता है; app.requests() उन सबको सूचीबद्ध करता है। Sockets और WebSockets host के network पर "live" के साथ connect होते हैं, अन्यथा headless की तरह अस्वीकार कर दिए जाते हैं। storage app के शुरू होने पर उसके storage में होता है, और app.storage() उसे app से पढ़ता है। locale, reducedMotion और safeArea, जब open उन्हें देता है (default मान सहित), वही रखते हैं जो platform बताता है, और colorScheme जो वह देता है वह system की appearance बदल देता है ("light" भी); जो वह छोड़ देता है वह platform का अपना रहता है, और app की clipboard calls test की अपनी clipboard से पूरी की जाती हैं (clipboard शुरू में उसका text है, app.clipboard() उसे पढ़ता है), इसलिए machine की clipboard जैसी थी वैसी रहती है; text input का अपना copy और paste system की clipboard का उपयोग करता है। host.params app तक पहुँचता है, app.host.send events भेजता है, और app जो URLs खोलता है वे खोले जाने के बजाय app.openedUrls() के लिए दर्ज किए जाते हैं। host.handlers headless चलता है, जहाँ test app की calls का उत्तर देता है। open अपने options को target के विरुद्ध जाँचता है: iOS और Android पर width और height, किसी दूसरी तरह के device का platform (desktop या web पर फ़ोन का, iOS या Android पर desktop का या दूसरे फ़ोन का) और host.handlers ERR_NSH_TEST_UNSUPPORTED के साथ reject होते हैं, इसलिए test वैसे ही चलता है जैसा लिखा है या बताता है कि उसे क्या चाहिए। Desktop का platform (desktop के mouse और keys के लिए "macos") हर desktop target और web पर चलता है, उस target के platform के रूप में और हमेशा desktop के रूप में: browser में पेज चौड़ाई जो भी हो desktop idiom में शुरू होता है, जहाँ platform के बिना (या "web" के साथ) वह अपना idiom वैसे नापता है जैसे browser करता है (600 points चौड़ाई से desktop)। जिस app के अपने Rust crates हैं वह ऐसे development host में चलता है जो उसके crates के साथ बना है, जिसे NSH platform के लिए बनाता है; Rust app का host अपना root चलाता है, इसलिए open(".") उसे वहाँ वैसे ही शुरू करता है जैसे headless में।

Web पर, apps development host के पेज में headless Chrome, Edge या Chromium में चलते हैं: इस machine पर स्थापित वाला, या वह executable जिसे --browser <PATH> नाम देता है (browser चाहिए: कोई न मिलने पर nsh test बताता है कि उसने कहाँ देखा)। एक browser पूरे रन की सेवा करता है, और हर open को अपने storage वाला एक पेज मिलता है। Input browser का trusted input है, जैसा उपयोगकर्ता का: mouse clicks, wheel scrolling और keys।

iOS पर, apps development host में iOS simulator में चलते हैं: जो booted हो, नहीं तो सबसे नया iPhone, जिसे nsh test boot करता है। Steps एक उँगली के touches और software keyboard की typing हैं, जैसा UIKit को device से मिलता है। setColorScheme simulator की appearance बदलता है, जिसे nsh test app के बाद वापस सेट करता है, और screen का आकार simulated device का होता है।

Android पर, apps development host में पहले device या emulator पर चलते हैं जिसे adb devices सूचीबद्ध करता है, अपने storage के साथ। Steps एक उँगली के touches और keyboard की keys हैं, जैसा app के views को device से मिलता है; back system का back है। setColorScheme device की dark theme बदलता है, जिसे nsh test app के बाद वापस सेट करता है।

#Standard input से steps

Tests की जगह app की entry दी जाए, तो nsh test app को असली network पर खोलता है, उसे 1.2 s चलने देता है, फिर वे steps लेता है जो standard input देता है, app app के साथ:

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

1.2 s engine की idle garbage collection को पहले step से पहले चलने देते हैं, ताकि जो app उसे छोड़ देता है जिसका वह अब भी उपयोग करता है, वह दिख जाए: उसके handlers काम करना बंद कर देते हैं।

Examples में शुरू करने के लिए tests हैं: Rust app के लिए examples/gallery-rs (cargo test, हर demo के लिए एक module, और App.test.tsx), Rust crate वाले app के लिए examples/rust-exports, examples/counter और examples/gallery/tests (storage, inputs, लंबी list, stubbed requests, dark mode, manual clock) TSX apps के लिए।

#—trace के साथ Tracing

--trace उन apps का हर mount batch प्रिंट करता है जिन्हें tests खोलते हैं, उस step के नीचे जिसमें वह आया, और हर commit का समय। Rust में, test वही प्रिंट करता है: observe उसे हर batch उसके step के साथ देता है, और EngineConfig::trace perf पंक्तियाँ log crate के माध्यम से log करता है (target nsh::perf; test में env_logger जैसा कोई logger install करें):

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 test file पर --trace लेता है, या app की entry पर standard input के steps के साथ:

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

--target के साथ, trace platform का होता है: host ने जो batches लागू किए, उन steps के नीचे जो उन्हें लाए, और हर commit और event के host के अपने timings, device के hardware पर।

इसका उपयोग इनके लिए करें:

• जाँचने के लिए कि कोई app (या demo) बिना errors के build, evaluate और render होता है;
• ठीक-ठीक देखने के लिए कि कोई बदलाव कौन-से native views बनाता, हटाता या update करता है, और कितने;
• पहले frame, किसी tap और हर scrolling frame की लागत नापने के लिए;
• CI में regressions पकड़ने के लिए।

#आउटपुट पढ़ना

यहाँ एक प्रेस के साथ counter का उदाहरण है (echo 'await app.press("+1")' | nsh test examples/counter/App.tsx --trace), संक्षिप्त रूप में:

✓ 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 और mount items

हर ── step: N items ब्लॉक एक mount batch है, जो उस step के अंतर्गत दिखता है जिसमें वह आया: यानी एक फ़्रेम के लिए प्लेटफ़ॉर्म जो कुछ भी नेटिव views पर लागू करता है, मुख्य थ्रेड तक एक ही hop में। इसकी पंक्तियाँ mount items हैं:

केवल वही भेजा जाता है जो बदला है: जो टैप एक संख्या बदलता है वह एक Text आइटम भेजता है; views को कोई डिफ़ॉल्ट style नहीं मिलता और न ही कोई खाली event mask; अपरिवर्तित फ़्रेम नहीं भेजे जाते। स्क्रॉलिंग का जो फ़्रेम कोई नई row नहीं दिखाता, वह कोई batch ही नहीं बनाता।

#perf पंक्तियाँ

एक बार के रन के समय CPU की clock स्थिति पर बहुत निर्भर करते हैं (जो मशीन अभी-अभी idle से जागी हो वह धीमी होती है)। रन की तुलना एक ही मशीन पर करें, कई रन का न्यूनतम मान देखें, और माइक्रोसेकंड से ज़्यादा op और item की संख्या पर भरोसा करें।

#स्क्रॉलिंग

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

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

scroll सूची को प्रति फ़्रेम 10 points खिसकाता है, प्रति सेकंड 60 फ़्रेम पर, और हर फ़्रेम का batch प्रिंट होता है:

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

list के लिए यह virtualization को काम करते हुए दिखाता है: कौन-से फ़्रेम नई rows को bind करते हैं, एक row में कितने operations लगते हैं, और जो फ़्रेम कोई नई row नहीं दिखाते वे कुछ नहीं बनाते। सार्थक समय के लिए इसे release build के साथ उपयोग करें (cargo test --release, या checkout में ./target/release/nsh)।

#CI में

Headless टेस्ट को किसी डिवाइस या डिस्प्ले की ज़रूरत नहीं होती, इसलिए वे Linux runners पर चलते हैं: Rust ऐप के टेस्ट के लिए cargo test, और nsh test, जिसे CLI के अलावा कुछ नहीं चाहिए। कोई भी विफल टेस्ट दोनों को non-zero कोड के साथ बाहर निकालता है: जो टेस्ट विफल हो, जो ऐप बिल्ड न हो या कुछ रेंडर न करे, या कोई exception जो ऐप किसी step के दौरान फेंके।

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

(runner पर nsh CLI को उसी तरह इंस्टॉल करें जैसे आप उसे लोकली करते हैं; देखें Installation।)

--junit <FILE> परिणामों को JUnit XML रिपोर्ट के रूप में भी लिखता है, जिसे CI सेवाएँ (GitHub Actions test reporters, GitLab, Jenkins, Azure Pipelines) प्रति टेस्ट दिखाती हैं: प्रति टेस्ट फ़ाइल एक testsuite, प्रति टेस्ट एक testcase, साथ में यह कि क्या विफल हुआ, कहाँ, और स्क्रीन पर मौजूद टेक्स्ट।

परफ़ॉर्मेंस की सुरक्षा के लिए, कुछ interactions के item counts दर्ज करें (── … : N items पंक्तियाँ और --trace की ops / mount items संख्याएँ) और जब वे बढ़ें तो विफल करें। गिनतियाँ निश्चित होती हैं; साझा CI मशीनों पर समय निश्चित नहीं होते।

#UI टेस्ट के लिए testID

Headless टेस्ट जाँचते हैं कि runtime क्या रेंडर करता है, और उनके id: selectors views को test id से खोजते हैं। प्लेटफ़ॉर्म के टेस्ट टूल (XCUITest, Espresso / UI Automator, Appium, Maestro) से असली नेटिव UI को चलाने के लिए, views को एक test id दें: Rust में .test_id(…), TSX में testID:

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>

Test id Rust में हर element का एक method है, components के elements सहित (button().test_id("save"), जो component की root को नाम देता है), और testID हर element और हर Rust component का एक prop है (Button, Dialog, …)। यह स्क्रीन रीडर के बोलने की सामग्री को नहीं बदलता; उसके लिए accessibilityLabel का उपयोग करें (देखें Accessibility)। --trace आउटपुट में यह view के ViewProps आइटम में test_id: Some("add-to-cart") के रूप में दिखता है।

#यह भी देखें

• Performance: इन संख्याओं में क्या देखना चाहिए
• Dev server and debugging
• Architecture: ops, commits और mount batches