# bigstack-cloud-setup Test Harness

Automated test harness for the cloud-setup skill. Creates a headless
VirtualBox Windows 11 VM, runs every installation step, and reports
pass/fail. Snapshots enable fast reset on failure.

## Prerequisites

1. **VirtualBox 7+** — https://www.virtualbox.org/wiki/Downloads
2. **Windows 11 ISO** — either:
   - Evaluation (free, 90-day): https://www.microsoft.com/en-us/evalcenter/evaluate-windows-11-enterprise
   - Or your own ISO
3. **~25 GB free disk** for the VM

## Usage

```bash
# First run (creates VM from ISO, ~20 min):
bash bigstack-cloud-setup/test/run-test.sh --iso /path/to/Win11.iso

# Subsequent runs (restores from snapshot, ~10-15 min):
bash bigstack-cloud-setup/test/run-test.sh

# Skip WSL steps (if nested virtualization doesn't work):
bash bigstack-cloud-setup/test/run-test.sh --skip-wsl

# Resume from a specific step:
bash bigstack-cloud-setup/test/run-test.sh --step 3

# Keep VM after test (for debugging):
bash bigstack-cloud-setup/test/run-test.sh --keep-vm

# Destroy the VM:
bash bigstack-cloud-setup/test/run-test.sh --destroy

# Check VM status:
bash bigstack-cloud-setup/test/vm-manager.sh status
```

## What Gets Tested

| Step | Component | Where |
|------|-----------|-------|
| 00 | Baseline check (all MISSING) | VM |
| 01 | WSL2 + Ubuntu | VM (nested virt) |
| 02 | Volta | VM Windows |
| 03 | Node.js v24 | VM Windows |
| 04 | Yarn, tsc, ts-node, ts-mocha | VM Windows |
| 05 | Python 3.10.11 | VM Windows |
| 06 | Redis 6.2.6 (compile from source) | VM WSL |
| 07 | PostgreSQL 15 + localv1db | VM WSL |
| 08 | webpack + webpack-cli | VM Windows |
| 09 | Final check-prerequisites.sh | VM |

## Not Tested

These require private GitHub auth and secrets that can't be automated:

- Cloning the BigscreenVR/cloud repo
- Generating .env files from devops ServerEnvironmentBuilder
- `yarn install` and workspace installs
- `yarn dev` and `ts-mocha` test runs

## Nested Virtualization

WSL2 requires Hyper-V inside the VM. On hosts already running Hyper-V
(e.g., for WSL2), this means triple nesting which may not work.

Step 01 is a smoke test: if WSL2 can't start inside the VM, the harness
reports it immediately. Use `--skip-wsl` to still test the Windows-side
tools (Volta, Node, Python, Webpack).

## Failure Handling

When a step fails:
1. The failure log is saved to `C:/bigstack-test-vm/logs/`
2. The last 20 lines are printed
3. The VM is restored to the last good snapshot
4. The harness exits with code 1

Re-run `run-test.sh` to retry from scratch (snapshot restore takes seconds).

## Files

```
test/
  config.sh        — Shared constants, paths, color helpers
  vm-manager.sh    — VM create/snapshot/restore/destroy via VBoxManage
  vm-exec.sh       — Execute commands in the VM (cmd/ps/wsl/copy-to)
  run-test.sh      — Main orchestrator
  steps/
    00-09*.sh      — Individual test steps with run() and verify()
```