8.9 KiB
WS-T: Integration test suite (written first, user request)
Part of Phase 5: Consolidator. Contracts: contracts.md.
| Field | Value |
|---|---|
| Status | In progress: nix/tests/peers.nix is written; T7 runner and docs open |
| Owner | |
| Depends on | none (uses the module's freeform settings for [peers] and a systemd override for LoadCredential, so it needs no module changes). F1 later swaps this for the first-class module options |
| Blocks | nothing technically; it is the acceptance gate: goes green at the end of WS-E (with A, B, C, D landed), then F2 promotes it to checks |
| Can start when | day one |
| Owned files | nix/tests/peers.nix (done), flake.nix (the tests.<system>.peers output only), dev/test.nu, devenv.nix (nushell package, test script, completion hook), AGENTS.md and README.md (command lists only, see seams), docs/consolidator.md (creates the file with only a ## Testing section, see seams) |
| Do not touch | src/** (all streams), nix/module.nix, nix/tests/vm.nix, systemd/skyg-linux-tracker.service (F), config.example.toml (A/F), tests/peers.rs and tests/common/mod.rs (F; in-process variants by A/B live in their own test files, see ws-a, ws-b), docs/api.md (C) |
Shared-file seams:
flake.nix: T owns it until F2. F2 later moves exactly one attribute,tests.${system}.peers, intochecks(renamechecks.vm-peers). Nobody else editsflake.nix; it already carries the uncommitted peers output.devenv.nix: T only.README.md: T edits only the command/test list near the existing commands; F4 owns the new peers section. Different headings, so no overlap.AGENTS.md: T replaces the command list; F4 adds only the MCP tool-count note.docs/consolidator.md: T creates it with a single## Testingsection (the one-lineuse dev/test.nu *and the completion setup). F4 adds every other section and must not edit## Testing.
Goal
Executable acceptance criteria before the implementation. Two NixOS VMs each run the real slinuxm binary and consolidate each other: VM alpha declares beta as a peer, VM beta declares alpha, and each proxies the other's data. Expected to fail until WS-E lands, which is the point.
Note on the written test: nix/tests/peers.nix also contains a third node gamma (TLS-only, no peers) that alpha declares with a private CA via ca_file, covering the TLS variant. It is already written and, by design, fails at the first peers assertion (phase 2, "declared but token is still a placeholder -> auth rejected") against the current binary; phase 1 (boot, healthz, token minting, marker units, token-file placeholders) already passes.
Tasks
- T1 two machines
alphaandbetawith distinct hostnames, each with a distinct fake workload (a marker systemd unitmarker-alpha.service/marker-beta.service, and a deliberately failing unit on one side) so proxied data is distinguishable from local data. Done innix/tests/peers.nix(failing unit isbroken-beta.service;gammawithmarker-gamma.serviceadded). - T2 each mints a read-only token via
sudo -u skyg-linux-tracker slinuxm token create consolidator-<other>, writes the other's token to a root-only 0400 file (stand-in for an agenix path), and declares the other as a peer with thattoken_file. Done (files under/var/lib/peer-tokens, delivered viaLoadCredential). - T3 assertions on both directions:
/api/v1/peersshows the peer with server up, api up and auth ok;GET /api/v1/peers/<other>/systemd/units/marker-<other>.servicereturns the other machine's unit and not a local one; MCPlist_peersand alist_systemd_unitscall withpeerreturn the same data; response headerx-slinuxm-peer. Done in the test script. - T4 token rejected: revoke the token on
beta;alphareports server up, api up,auth = rejected,peer.api.auth_ok = 0, and proxy calls fail with 503 naming the peer, without becoming a 401 for the caller; restore with a new token file and no restart, status recovers. Done in the script except thepeer.api.auth_ok = 0metric check (needs WS-E; add it to the script, or leave to F2 which may query the collector/metrics endpoint, note in Log). - T5 outage: stop
beta's service:alphaflips server and api afterfail_threshold,alpha's own endpoints stay healthy, and recovery is detected; stopbetaentirely (VM down) and check thatalpha's requests are bounded by timeouts. Done in the script. - T6 no chaining and read-only: a request carrying
x-slinuxm-hopis rejected; non-GET to a proxy path is 405; a TLS variant with a test CA viaca_file. Done (405 for POST/DELETE, hop header 4xx,gammaover HTTPS). - T7 a simple test runner CLI written in Nushell:
dev/test.nu(devenv addspkgs.nushell; also exposed as the devenv scripttest, sodevenv shell -- test unitworks from any shell). One entry point so contributors and agents do not memorise cargo/nix incantations. Structure it as a Nushell script with amainandmain <sub>subcommands (def "main unit", ...) so--helpis generated and completion comes from the typed signatures:test unitrunscargo test --lib --bins(no sockets, no host access).test integration [filter]runscargo test --tests(plain, tls, integration, binary_smoke,peersonce it exists).filteris passed to cargo as a name filter;--nocaptureflag supported.test lintrunscargo fmt --check,cargo clippy --all-targets -- -D warningsand thecargo tree -i opensslemptiness check.test vm [name]runs a NixOS VM test.nameis one ofvm(fromchecks) orpeers(nix build .#tests.x86_64-linux.peers -L; moves tocheckswhen green). Refuses without/dev/kvmand says why; prints that it is slow.test all= lint, unit, integration, stopping at the first failure;test ci=allplusvm. No args prints help.- Each step prints a header and a final table (step, result, seconds); exit code non-zero on any failure (use
error make/exit 1, never swallow cargo's exit status). Read-only against the host: no/etc, systemd or Docker changes (live-host checks stay manual, see Verification plan in the README). - Autocomplete (must work, and is a done-criterion):
- Nushell: subcommands and flags complete natively once the script is loaded as a module. Dynamic values use custom completers (
def "nu-complete test vm" [] { ["vm" "peers"] }andname: string@"nu-complete test vm"; integration filters complete fromcargo test --tests -- --listtest names, cached for the session). The devenventerShellprints/loadsuse dev/test.nu *for Nushell users, anddocs/consolidator.mdshows the one-lineusefor a permanent setup. - Other shells (the repo owner's login shell is zsh):
test completions zsh|bashprints a small static completion script (subcommands,vmnames, flags) generated from the same command table in the script, so zsh/bash tab completion works throughdevenv shelltoo (source <(test completions zsh)inenterShell). - Verified by a self-test:
test --helpandtest vm --helplist every subcommand/flag, and a check indev/test.nu(test self-check) fails if the completion table and the defined subcommands diverge.
- Nushell: subcommands and flags complete natively once the script is loaded as a module. Dynamic values use custom completers (
- AGENTS.md and README replace their scattered command lists with
test ..., keeping the underlying commands visible in--help.
Inputs
- contracts.md section 10 (test config contract) and sections 5 and 7 (REST/MCP shapes the script asserts). No fakes: the test runs the real binary.
nix/tests/peers.nixis the source of truth for section 10; if the test must change, change it and update contracts.md in the same PR, then log in the affected streams.
Done when
The test builds under nix build .#tests.x86_64-linux.peers (or equivalent) and evaluates, fails cleanly at the first peers assertion against the current binary, and is documented in docs/consolidator.md. test unit|integration|lint|vm|all each run and report correctly on the current tree, and tab completion works in Nushell, zsh and bash (T7). It must pass at the end of WS-E, then move to checks.vm-peers (F2 does the move).
Handoff
- To everyone: the
testrunner and its subcommand names (referenced by AGENTS.md/README and by every stream's "Done when"). - To WS-F: a passing
peers.nix(ready to promote) and any changes made to its assumptions, recorded in contracts.md section 10. - To WS-A/B: the
test integrationstep picks up anytests/peers*.rsautomatically.
Log
- 2026-10-19: Split from the single phase plan 2026-10-19.
nix/tests/peers.nixalready written (T1 to T6) and failing at the first peers assertion by design;flake.nixexposes it astests.<system>.peers. T7 not started. Ownership change from the single plan:tests/peers.rsmoved to WS-F; WS-A/B in-process tests use their own files to avoid collisions.