write-tests

# Writing & Running ryOS Tests ryOS uses **Bun's native test runner** (`bun:test`). Suites live under `tests/`, are named `test-*.test.ts` or `test-*.test.tsx`, and use `describe` / `test` / `expect`. ## Layout ``` tests/ ├── setup.ts # Global preload ├── helpers/ # Shared helpers (not suites) ├── fixtures/ ├── unit/<domain>/ # No-server unit / wiring └── integration/ ├── api/ # Needs `bun run dev:api` └── opt-in/ # Env-gated (e.g. REALTIME_LOCAL_URL) ``` ## Two Kinds of Tests | Kind | What it covers | Needs API server? | Suite command | |------|----------------|-------------------|---------------| | Unit / wiring | Pure logic, Zod schemas, store reducers, helper functions, "is X wired to Y" checks | No | `bun run test:unit` | | API integration | Real HTTP against `api/*` endpoints | **Yes** (`bun run dev:api`) | `bun run test:api` | Prefer a **unit test** when the logic can be exercised without a server (most schema/util/store work). Add an **API integration test** when you need the real request → handler → Redis path. ## Quick Start Checklist ``` - [ ] 1. Decide: unit/wiring (no server) or API integration (needs server) - [ ] 2. Create tests/unit/<domain>/test-<feature>.test.ts or tests/integration/api/test-<feature>.test.ts - [ ] 3. Use describe / test / expect from "bun:test" - [ ] 4. For API tests, use helpers from tests/helpers/test-utils.ts - [ ] 5. For API or opt-in tests, add the file to `scripts/test-groups.ts` - [ ] 6. Run `bun run test:registration`; iterate until green - [ ] 7. Run it; iterate until green ``` ## Unit / Wiring Test No server required. Import the code under test directly. Schema tests are the highest-value, lowest-friction kind. ```typescript import { describe, expect, test } from "bun:test"; import { mediaControlSchema } from "../../../api/chat/tools/schemas"; describe("mediaControlSchema", () => { test("accepts a valid 'list' call", () => { expect( mediaControlSchema.safeParse({ target: "tv", action: "list" }).success ).toBe(true); }); test("rejects 'tune' with neither channelId nor channelNumber", () => { expect( mediaControlSchema.safeParse({ target: "tv", action: "tune" }).success ).toBe(false); }); }); ``` Run a single file or domain: ```bash bun test tests/unit/media/test-media-control-unified.test.ts bun test tests/unit/media/ ``` ## API Integration Test Requires the standalone server running in a separate terminal: ```bash # Terminal 1 bun run dev:api # port 3000; exports TRUSTED_PROXY_COUNT=1 and a Telegram mock API base URL # Terminal 2 bun run test:api # or a single file: bun test tests/integration/api/test-<feature>.test.ts ``` Use the shared HTTP helpers from `tests/helpers/test-utils.ts` — they set the required `Origin` header and auth: ```typescript import { describe, test, expect } from "bun:test"; import { BASE_URL, fetchWithOrigin, fetchWithAuth, ensureUserAuth, makeRateLimitBypassHeaders, getTokenFromAuthCookie, } from "../../helpers/test-utils"; describe("My feature", () => { test("requires auth → 401", async () => { const res = await fetchWithOrigin(`${BASE_URL}/api/my-feature`, { method: "POST" }); expect(res.status).toBe(401); }); test("creates when authed", async () => { const token = await ensureUserAuth("testuser_feat", "testtest"); const res = await fetchWithAuth(`${BASE_URL}/api/my-feature`, "testuser_feat", token!, { method: "POST", headers: makeRateLimitBypassHeaders(), body: JSON.stringify({ name: "hi" }), }); expect(res.status).toBe(201); }); }); ``` ### Helpers in `tests/helpers/` | Helper | Purpose | |--------|---------| | `test-utils.ts` → `BASE_URL` | `process.env.API_URL` or `http://localhost:3000` | | `fetchWithOrigin(url, opts)` | adds `Origin: http://localhost:3000` | | `fetchWithAuth(url, username, token, opts)` | adds Origin + `Authorization` + `X-Username` | | `makeRateLimitBypassHeaders()` | `Content-Type` + random `X-Forwarded-For` to dodge per-IP limits | | `ensureUserAuth(username, password)` | register-or-login, returns a token (or null) | | `getTokenFromAuthCookie(res)` / `getAuthFromCookie(res)` | read token from the `ryos_auth` httpOnly cookie | | `fake-redis.ts` | In-memory Redis double for unit suites | | `local-storage-stub.ts` | Early `localStorage` install for store-heavy suites | | `theme-css-fixtures.ts` | Shared CSS fixture strings | ### Integration test conventions - Generate fresh usernames per run to avoid cross-run collisions; reuse via `ensureUserAuth`. - Always include `makeRateLimitBypassHeaders()` (or a unique IP) on rate-limited routes. - Tolerate rate limiting where the suite expects it: `if (res.status === 429) return;` is an accepted skip pattern in existing suites. - Auth endpoints set the token in the `ryos_auth` cookie, not the JSON body — read it via the cookie helpers. ## Registering New Test Files Unit/wiring tests under `tests/unit/` are discovered automatically by `bun run test:unit`. Server-backed and opt-in suites are explicit in `scripts/test-groups.ts`: - Unit/wiring → no manual registration; place under `tests/unit/<domain>/`. - API integration → append to `API_TEST_FILES` (path under `tests/integration/api/`). - Opt-in/local-service suites → append to `OPT_IN_TEST_FILES` (path under `tests/integration/opt-in/`). - Optionally add a focused `"test:<feature>"` script for fast local runs. - Run `bun run test:registration` after adding or renaming tests. `bun test` (no args / `"test"`) runs everything, including API suites, so it needs the server too. ## Running Subsets ```bash bun run test:unit # all no-server suites bun run test:api # all API suites (server required) bun test tests/unit/chat/ # one domain bun test tests/unit/realtime/test-pusher-*.test.ts ``` See `package.json` for targeted suites (`test:ai`, `test:song`, `test:new-api`, `test:sync-v2`, `test:chat-regression`, …). ## When to Add Tests (match repo conventions) - Adding/altering a Zod schema, util, store reducer, or API contract → add or extend a test. - Touching code that already has a sibling `tests/unit/<domain>/test-*.test.ts` → update it. - Do **not** build large new test infrastructure unrelated to the change unless asked.