Skip to content

Manual Test Runbook — V2: Architecture Diagrams Generator

Owner: Sagar  |  Time: ~10 min (offline) / +5 min with d2 render  |  Sandbox: none required

Overview

V2 (apps/diagram-generator/) renders a client-facing architecture diagram from a stack's Terraform outputs (the F0 contracts). It's 100% offline — it operates on terraform output -json, not the cloud. The catalog test criterion: regenerate; diff matches expected for sample stack — covered by the golden-file test in Part A.

Part A — Offline build + golden-file test (~5 min)

A1. Build + typecheck

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

A2. Unit tests (includes the golden-file match)

npm test

Expect: 2 suites, 9 tests pass — the adapter normalizes every F0 contract from the sample stack (incl. the spoke_network_contracts map expansion + shape-based classification regardless of output name), and the renderer's output matches examples/golden/architecture.d2 byte-for-byte (the "regenerate; diff matches expected" criterion).

A3. Regenerate the sample diagram + confirm no diff

node dist/index.js \
  --input examples/stack.sample.tfoutputs.json \
  --out-dir /tmp/v2-out
diff /tmp/v2-out/architecture.d2 examples/golden/architecture.d2 && echo "NO DIFF ✅"

Confirm the .d2 contains: the scope container, a hub + spoke_apps network, the AKS cluster (hexagon), the ACR registry, the Key Vault, the state store, and the architecture edges (peering, deployed in, image pull, secrets (workload identity), logs).

Part B — Render to an image (optional, ~5 min)

Requires the d2 binary on PATH.

node dist/index.js \
  --input examples/stack.sample.tfoutputs.json \
  --out-dir /tmp/v2-out --render --format svg
open /tmp/v2-out/architecture.svg   # macOS; or xdg-open on Linux

Confirm the SVG renders a readable architecture diagram with the scope, networks, and the labeled edges. (If d2 is absent the CLI prints a "render skipped" notice and still writes the .d2 source — that's expected.)

Part C — Real stack (optional)

Against any applied SnowOps stack (e.g. a Z1 composition or the sandbox):

terraform -chdir=<stack> output -json > /tmp/stack-outputs.json
node apps/diagram-generator/dist/index.js \
  --input /tmp/stack-outputs.json --out-dir /tmp/v2-real
cat /tmp/v2-real/architecture.d2

Confirm every F0 contract the stack exposes (identity, observability, networks, cluster, registry, KV, state) appears in the diagram.

Pass criteria

  • npm test green (2 suites, 9 tests, incl. golden-file match)
  • A3 regeneration produces zero diff against the golden file
  • (Optional) --render produces a readable SVG
  • (Optional) a real stack's outputs render every contract present

Teardown

rm -rf /tmp/v2-out /tmp/v2-real /tmp/stack-outputs.json

Sign-off

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