Skip to content

Manual Test Runbook — V3: Runbook Generator

Owner: Sagar  |  Time: ~5 min (offline)  |  Sandbox: None (offline tool)

Overview

V3 is the Baseline-tier documentation generator. It parses standard Terraform outputs and renders client-facing operational runbooks. Two modes:

  • Model-driven (default) — shape-detects all 7 F0 contracts (identity, observability, network, cluster, registry, kv, object_store) from terraform output -json, normalizes them into a StackModel (src/adapt.ts), and renders one runbook per resource domain plus a master infrastructure.md index (src/render.ts). Each runbook carries key-facts tables, a Day-Zero Hardening posture check (✅/⚠️), operational CLI, and failure modes.

  • Legacy Handlebars (--templates) — the original path: render each .hbs template against the flattened outputs. Kept for bespoke client templates.

  • apps/runbook-generator/ — the TS tool that executes the CLI to generate markdown.

The catalog test criterion: unit tests cover parsing + shape-based adaptation + rendering (and legacy Handlebars). Live sample drill generates the full runbook set.

Part A — Offline (no cloud, ~2 min)

A1. Build + typecheck

cd apps/runbook-generator
npm ci
npx tsc -p tsconfig.json --noEmit
npx tsc -p tsconfig.test.json --noEmit
npm run build

A2. Unit tests

npm test

Expect: 4 suites, 16 tests pass (parser mapping + legacy Handlebars generator + shape-based adapter + model-driven renderer).

Part B — Model-driven generation (~2 min)

B1. Run CLI against the sample stack

node dist/index.js --input examples/stack.sample.tfoutputs.json --output out

Confirm the CLI completes with: Runbook generation complete — 8 file(s).

B2. Validate the runbook set

ls out
cat out/infrastructure.md

Confirm: - 8 files: infrastructure.md + identity.md, network.md, compute.md, registry.md, secrets.md, storage.md, observability.md. - infrastructure.md shows the Inventory table and a Security posture digest with ✅/⚠️ markers (the sample's registry has signing disabled → ⚠️). - Per-domain files show interpolated values (e.g. aks-northwind, 10.1.0.0/22, stnorthwindstate), not raw {{handlebars}} tags.

Part C — Legacy Handlebars mode (~1 min)

C1. Render bespoke templates

node dist/index.js --input mock-output.json --templates templates --output out-legacy
cat out-legacy/infrastructure.md

Confirm the CLI completes with Runbook generation complete (template mode). and that out-legacy/infrastructure.md has interpolated Scope ID, Tenant ID, Workspace Name, Retention (Days).

Pass criteria

  • npm test green (4 suites, 16 tests)
  • Model-driven generation (B1) produces 8 files without error
  • infrastructure.md (B2) shows inventory + posture digest with correct interpolated values
  • Legacy mode (C1) still renders the Handlebars template

Teardown

  • Offline: rm -rf out out-legacy

Sign-off

  • Tester: Sagar Chhabra  |  Date: 3/6/2026  |  Result: PASS
  • Notes: