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. Backends unavailable on the host (e.g. Docker not running, nix not installed, no flake.nix in dir) are skipped via t.Skip rather than failing — so a dev without Docker still sees native + nix pass.
`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) signals "backend not available on this host" — ForEachEnvironment will Skip that sub-test rather than Fail.
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