fleetboxtest

Documentation

Overview

Package fleetboxtest provides testing.T integration for fleetbox VMs.

VMs created with Start or StartN are automatically destroyed when the test completes.

Example:

func TestMyApp(t *testing.T) {
	vm := fleetboxtest.Start(t, "debian-12")
	out, err := vm.SSH(context.Background(), "uname -a")
	if err != nil {
		t.Fatal(err)
	}
	t.Log(out)
}

Index

• func BootTimeout(n int) time.Duration
• func SkipIfCannotBootVM(t testing.TB)
• func SkipIfShort(t testing.TB, reason string)
• func Start(t testing.TB, image string, opts ...fleetbox.Option) *fleetbox.VM
• func StartN(t testing.TB, prefix string, n int, opts ...fleetbox.Option) []*fleetbox.VM

Functions

func BootTimeout

func BootTimeout(n int) time.Duration

BootTimeout returns the per-call boot budget for a fixture that boots n VMs. It honors FLEETBOX_IP_WAIT_TIMEOUT (a time.ParseDuration string) when set and valid — the same knob the holder uses for its IP-wait — so one env widens both the holder's wait and the test's context (e.g. inside a slow nested guest). Unset or unparseable falls back silently to the default of 5 minutes per VM (n is treated as at least 1).

func SkipIfCannotBootVM

func SkipIfCannotBootVM(t testing.TB)

SkipIfCannotBootVM skips the test unless the host can boot a leaf VM through the active backend. The gate is boot-capability, NOT the ability to offer nested virt to a guest: linux/{amd64,arm64} only needs an openable /dev/kvm (true even inside a nested arm64 guest, where NestedVirtSupported reports false); darwin/arm64 keeps the fleetbox.NestedVirtSupported gate (Apple Silicon M3+, macOS 26+ — the project's stated minimum for VM tests, which also makes the GitHub macOS runner skip). On any other platform the test is skipped, never failed.

func SkipIfShort

func SkipIfShort(t testing.TB, reason string)

SkipIfShort skips the test if -short is set.

func Start

func Start(t testing.TB, image string, opts ...fleetbox.Option) *fleetbox.VM

Start creates a VM and registers cleanup to destroy it when the test completes. The VM name is derived from the test name to ensure uniqueness in parallel tests.

func StartN

func StartN(t testing.TB, prefix string, n int, opts ...fleetbox.Option) []*fleetbox.VM

StartN creates N VMs with names prefix-1, prefix-2, etc. All VMs are destroyed when the test completes.

On a backend without clustering (macOS < 26) StartN(n≥2) returns the public fleetbox.ErrClustersUnsupported; the fixture turns that into t.Skip rather than a failure, so the cluster test self-skips where clustering is not available.