From cfd327f285e214728d58aef08f3d0352bf9d766a Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Sat, 14 Mar 2026 23:21:28 +0000 Subject: [PATCH] docs(preflight): add test suite summary MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- Build: pass | Tests: pass — Tests 414 passed | 10 skipped (424) --- setup/preflight.test.md | 52 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 setup/preflight.test.md diff --git a/setup/preflight.test.md b/setup/preflight.test.md new file mode 100644 index 0000000..556f3d1 --- /dev/null +++ b/setup/preflight.test.md @@ -0,0 +1,52 @@ +# preflight.test.ts — test suite summary + +Smoke tests for the preflight orchestrator (`setup/preflight.ts`), which runs +the 12 setup steps before installation. + +## Setup / mocks + +- `spawnSync` is stubbed so no real subprocesses run — every call returns exit 0 by default +- `fs.writeFileSync` / `mkdirSync` are stubbed to capture what gets written without touching disk +- `process.exit` is spied on so a failing preflight does not kill the test runner +- Two helpers extract the outputs: `getSummaryJson()` and `getSummaryEnv()` parse what was written to `summary.json` / `summary.env` + +## 5 describe blocks, 17 tests + +### basic run (no flags) + +All 12 steps run in the correct order: + +``` +environment → pi-config → jails → db → git → cms → +hosts → mounts → telegram-auth → service → verify → doctor +``` + +- `summary.json` has `overallStatus: success` +- `summary.env` has `OVERALL_STATUS=success`, `WITH_ONBOARDING=false`, `CAPTURE_PASSWORD_STEP=false` +- `process.exit` is not called + +### failure handling + +- A single failing step does not abort the run — all 12 still execute +- `overallStatus` becomes `failed` +- `process.exit(1)` is called +- `--fail-fast` stops after the first failure (only 1 npm call, then exit 1) + +### --with-onboarding + +- The interactive onboarding step skips gracefully in a non-TTY environment (test runner has no TTY) +- All 12 non-interactive steps still run +- `overallStatus` is `failed` because onboarding itself fails without a TTY +- `WITH_ONBOARDING=true` appears in `summary.env` + +### --capture-password-step + +- Implies `--with-onboarding` (verified via `summary.json` args) +- The Python screenshot capture does NOT run when onboarding failed (no TTY) +- `CAPTURE_PASSWORD_STEP=true` appears in `summary.env` + +### summary output structure + +- Every step result in `summary.json` has all required fields: `id`, `label`, `commandLine`, `exitCode`, `status`, `startedAt`, `finishedAt`, `logFile` +- Log file paths are bare filenames with no path separator (e.g. `environment.log`) +- `summary.env` contains a `*_STATUS=` and `*_EXIT_CODE=` line for every step