Documentation
¶
Overview ¶
Package testmatrix provides a multi-environment test harness. A plugin lifecycle test wrapped in ForEachEnvironment runs once per available execution backend (native, docker, nix), with t.Run sub-tests so failures are attributed to a specific mode.
This is the guardrail for the "every plugin tests all three execution environments" architectural rule: plugin authors write one test, and parity across modes becomes a CI-enforced guarantee rather than a claim.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ForEachEnvironment ¶
func ForEachEnvironment(t *testing.T, dir string, fn func(t *testing.T, env runners.RunnerEnvironment), opts ...Option)
ForEachEnvironment runs fn against each supported backend as a sub-test. A backend that isn't available on the host (Docker not running, nix not installed, missing flake.nix) FAILS the sub-test loudly — silent skips hide drift. To exclude an irrelevant backend at the call site, use Only("native", "nix"). To exclude all infra-dependent backends from a build, set the `skip_infra` build tag at the test-file level.
`dir` is the workspace or source directory the plugin expects to operate on. For native/nix it's used as cwd; for docker it's bind-mounted.
Types ¶
type Case ¶
type Case struct {
Name string
Factory EnvFactory
}
Case wraps a (name, factory) pair for a single backend.
type EnvFactory ¶
EnvFactory is a constructor that returns a RunnerEnvironment bound to dir. Each backend provides one. Returning (nil, nil) is a programmer error — backends MUST be available when the matrix runs. If a backend can't be available on every dev/CI box, exclude it via Only(...) at the call site instead.
type Option ¶
type Option func(*options)
Option tweaks the set of backends used by ForEachEnvironment.
func Only ¶
Only restricts the matrix to the named backends (e.g. "native", "nix"). Useful when a plugin genuinely cannot support one — prefer Skip-in-factory over Only when the backend is merely unavailable on the host.
func WithDockerImage ¶
func WithDockerImage(img *resources.DockerImage) Option
WithDockerImage overrides the Docker image for the `docker` case. Most plugins want their language's canonical image (golang:1.26, python:3.12, node:22-alpine) rather than the default alpine:3.20 which has no toolchains beyond /bin/sh.
Source Files