Skip to content

Testing

Run the tiers relevant to your change. Unit tests check logic; simulator tests check collection and CLI behavior; TUI scenarios check the model; PTY journeys check the running terminal process. The test catalogue lists suites and fixtures; testbed setup describes profile boundaries. Automated fixtures are synthetic and do not prove real-vSphere behavior.

Unit and package tests

Run the untagged suite and static checks:

go test -race ./...
go vet ./...

The CI build job runs these on Linux, macOS, and Windows. Linux also records whole-suite coverage, without enforcing a percentage threshold:

go test -race -covermode=atomic -coverpkg=./... -coverprofile=coverage.out ./...
go tool cover -func=coverage.out
go tool cover -html=coverage.out -o coverage.html

Keep -coverpkg=./...: the separate tests package exercises the CLI and internal packages through the simulator. Package-local coverage would miss those calls. CI retains the profile and HTML report.

In-process simulator tests

The untagged tests/ suite starts govmomi/simulator inside the test process and drives the real CLI through direct, SOCKS5, and HTTP(S) routes. It covers credentials, deadlines, partial collection, offline exports, and read-only SOAP auditing. It runs with the unit suite above.

License tests use labelled synthetic records and planted fake keys to check redaction, coverage, default-off collection, and deterministic offline export. File-inventory tests check bounds, denial, truncation, coverage, byte sizes, stable export, and that file inventory cannot change health or orphan verdicts. Neither validates real server behavior or RVTools values. See the recorded file-inventory comparison and remaining limits for real-datastore evidence.

Synthetic TUI scenarios

Use the checked-in harness to drive the Bubble Tea model with deterministic fixtures:

scripts/testbed list
scripts/testbed test
scripts/testbed test partial-failure

Scenarios check visible behavior, model observations, and read-only and credential-safety invariants. Critical screens also have ANSI-normalized goldens at 60x20, 100x30, and 140x40. Review rendering changes before using the explicit --update-goldens flag; see render contracts.

Linux PTY process tests

scripts/testbed pty --results-dir /tmp/vsfleet-pty

The tagged suite builds and runs cmd/vsfleet-testbed in a pseudo-terminal with key input, resize events, signals, loopback endpoints, and isolated state. It checks semantic output and clean exits rather than complete byte snapshots. The journey matrix records coverage. Failure artifacts include redacted process output, a normalized transcript, event logs, result metadata, and testbed state. PTY validation is Linux-only.

Out-of-process vcsim integration

Each endpoint runs in an independent cmd/vsfleet-vcsim process on a kernel-assigned loopback port. The suite fetches the TLS certificate thumbprint to check readiness and captures process output for failure artifacts. The launcher uses the govmomi version in go.mod; v0.56.0 provides the simulator library but no installable github.com/vmware/govmomi/vcsim module.

go build -o /tmp/vsfleet-vcsim ./cmd/vsfleet-vcsim
VSFLEET_VCSIM_BIN=/tmp/vsfleet-vcsim \
VSFLEET_VCSIM_REQUIRED=1 \
VSFLEET_VCSIM_LOG_DIR=/tmp/vsfleet-vcsim-logs \
go test -tags integration -race -run '^TestVCSIM' ./tests/... -timeout 20m

Fixture catalogue

See the fixture matrix and integration cases. Fixture topology is deterministic, but endpoint identities are independent. vcsim performance samples vary, so tests assert coverage, provenance, and status rather than sample values.

Fuzzing

Seeds run with go test ./...; CI also runs timed campaigns. Commit a failing input under the package's testdata/fuzz/<Target>/ so it becomes a regression seed. The target matrix lists inputs and invariants.

Kubernetes end-to-end

Create a kind cluster and load the vsfleet:ci-test and vsfleet-vcsim:ci-test images, then run:

scripts/test-kubernetes.sh

It runs the shipped CronJob against two vcsim Services and checks mounts, credentials, persistence, DNS, and partial-capture exits; see the case matrix. It validates deployment, not scheduled execution or CSI volume ownership.

Release checks

CI builds a full release snapshot, smoke-tests the binaries and image, and scans them; leave this to CI on a small workstation. See the release matrix and vulnerability scanning.

When each of these runs in CI is listed in the workflows README.

What vcsim does not prove

Simulators test process isolation, collection, identity joins, persistence, partial coverage, and exercised TLS/credential paths. Real validation is still needed for physical storage, ESXi kernel behavior, VMXNET3/UPT, SR-IOV, vGPU, RDM, patch-release differences, performance counters, and migration. Automated tests also leave real desktop keyrings, macOS/Windows terminal process behavior, and the published signed image unverified.

Real vCenter validation

vsfleet has been tested against vCenter Server 8.0.3. This does not establish acceptance of every feature. Record the server versions, fixture conditions, and results for each manual acceptance check in its issue or release PR.

Datastore browser acceptance

Relationship-aware datastore browsing still needs acceptance against a real read-only account on a nested VMFS or NFS datastore. Record vCenter and ESXi versions and check:

  • A base VMDK, snapshot-chain file, template disk, shared/multi-reference disk, and unreferenced descriptor.
  • Missing Datastore.Browse and partially unreadable VM configuration.
  • Path metadata, UNKNOWN/partial rendering, cancellation, and exact VM/template jumps.
  • No datastore or VM mutation.

Until those results are recorded, real-vSphere acceptance remains open.