harness

package
v0.2.13 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 32 Imported by: 0

Documentation

Overview

Package harness runs the acceptance phases test/e2e carries, inside the cluster hack/e2e-kind.sh stands up.

The driver keeps the bootstrap: the kind cluster, the images, the registry, the databases and the chart install. It builds one test binary from test/e2e, and for a phase ported to Go it runs that binary with the phase's name. Main picks the test that is the phase out of package phases, bounds it by the phase's own timeout, and fails a run in which no test reached the end of the phase, so a binary asked for a phase it does not carry cannot pass by running nothing; only a phase that passed writes the completion record the driver passes it on. Begin loads the inputs the driver bound, and Run records the phase's scenarios in the same timing ledger the shell phases write.

Index

Constants

View Source
const FieldOwner = "ptah-e2e"

FieldOwner is the field manager every write the harness makes carries, so a phase's own writes can be told apart from the operator's and Helm's in managedFields.

Variables

View Source
var ErrWaitTimeout = errors.New("did not arrive in time")

ErrWaitTimeout is what Wait wraps when the awaited state did not arrive.

Functions

func CreateAfterRoleBinding

func CreateAfterRoleBinding(ctx context.Context, writer client.Client, object client.Object, opts ...client.CreateOption) error

CreateAfterRoleBinding waits for a newly installed RoleBinding to reach the API server's authorizer. Only a definitive Forbidden response is retryable: retrying an ambiguous write failure could duplicate a successful request. The same identity, object, and admission options are used on every attempt.

func DeploymentRolledOut

func DeploymentRolledOut(deployment *appsv1.Deployment) (bool, string, error)

DeploymentRolledOut is `kubectl rollout status deployment` read once: the same four checks in the same order, so a phase that waited on the command and a phase that waits on this accept and refuse the same Deployments.

It reports whether the rollout is complete and, when it is not, what it is waiting for in kubectl's words. A rollout past its progress deadline is an error, as kubectl makes it, because no amount of waiting completes it.

func Main

func Main(m *testing.M) int

Main runs the phase named by -e2e.phase and returns the exit code. A package of acceptance phases calls it from TestMain:

func TestMain(m *testing.M) { os.Exit(harness.Main(m)) }

func ParallelPair

func ParallelPair(t *testing.T, name string, cases [2]ParallelCase) bool

ParallelPair overlaps two independent lanes and joins them before returning. A skipped or filtered lane fails the pair, just as it fails a Scenario. The caller must keep cluster-wide faults outside the pair and isolate any database-server locks; distinct database names do not always isolate locks.

func PodReady

func PodReady(pod *corev1.Pod) bool

PodReady reports whether the Pod carries a Ready condition that is True.

func Wait

func Wait(ctx context.Context, what string, timeout, interval time.Duration, check Check) error

Wait calls check until it reports done, returns an error, the timeout passes, or ctx ends. check runs at least once, and once more at the deadline if the interval would carry it past, so the last reading is taken no earlier than the deadline allows.

A failure names what was awaited, how long it was given and the last thing check saw. A bare timeout costs whoever reads the log the whole investigation.

Types

type Check

type Check func(ctx context.Context) (done bool, observed string, err error)

Check reads the cluster once. It reports whether the awaited state holds, and says what it saw in a form a failure message can carry. An error ends the wait at once: it is for a reading that no later poll can fix, and a transient failure a wait should ride out is an observation instead.

type Cluster

type Cluster struct {
	Kubeconfig string
	Config     *rest.Config
	Client     client.Client
	Clientset  kubernetes.Interface
	Scheme     *runtime.Scheme
	// Namespace is the kubeconfig context's namespace, "default" when it
	// names none: what kubectl sends for a request that names no namespace.
	Namespace string
}

Cluster is the cluster the driver stood up, reached through the kubeconfig it wrote.

Client reads straight from the API server. A phase asserts what the cluster holds now, and a cache that trails a write by one watch event would make an assertion about the harness rather than the operator.

func Connect

func Connect(kubeconfig string) (*Cluster, error)

Connect reaches the cluster the kubeconfig names, with the built-in types and the operator's own API registered.

func (*Cluster) As

func (c *Cluster) As(identity rest.ImpersonationConfig) (client.Client, error)

As returns a client that sends every request as the given identity. The administrator the kubeconfig names has to be allowed to impersonate it, which kind's is.

func (*Cluster) CanI

func (c *Cluster) CanI(ctx context.Context, user string, attributes authorizationv1.ResourceAttributes) (bool, error)

CanI asks the API server what `kubectl auth can-i --as=<user>` asks: a SelfSubjectAccessReview sent as the user alone, whose groups the server derives itself.

func (*Cluster) ContainerLog

func (c *Cluster) ContainerLog(ctx context.Context, namespace, pod, container string) ([]byte, error)

ContainerLog reads what one container of a Pod has written so far.

func (*Cluster) Describe

func (c *Cluster) Describe(ctx context.Context, w io.Writer, namespace, kind, name string)

Describe writes `kubectl describe` of one object to w. It is diagnostics for a failure the phase is about to report, so its own failure is written down rather than returned.

func (*Cluster) Helm

func (c *Cluster) Helm(ctx context.Context, arguments ...string) ([]byte, error)

Helm runs the helm CLI against the cluster and returns what it printed on standard output. Its standard error goes to the phase's as it is written, as it did when a shell phase ran it, so a refusal is in the log above the failure that reports it.

func (*Cluster) Kubectl

func (c *Cluster) Kubectl(ctx context.Context, arguments ...string) (stdout, stderr []byte, err error)

Kubectl runs the kubectl CLI against the cluster and returns what it wrote on standard output and standard error, separately. A phase reaches for it where the API has no typed call that says the same thing: running a command inside a Pod, which kubectl streams over a protocol the client libraries the harness links do not carry. Everything a phase reads or writes goes through Client.

func (*Cluster) Raw

func (c *Cluster) Raw(ctx context.Context, path string) ([]byte, error)

Raw reads one path from the API server, as `kubectl get --raw` does: a Pod's proxy subresource, which answers with whatever the Pod serves.

func (*Cluster) WaitForRollout

func (c *Cluster) WaitForRollout(ctx context.Context, namespace, name string, timeout time.Duration) error

WaitForRollout waits for the Deployment the way `kubectl rollout status` does, reading DeploymentRolledOut every two seconds.

type Ledger

type Ledger struct {
	// contains filtered or unexported fields
}

Ledger appends stage rows to the timing ledger the driver names in E2E_TIMING_LEDGER. It writes the row hack/e2e-timing.sh writes, byte for byte, so hack/e2etiming reads a Go phase's scenarios exactly as it reads a shell phase's.

Nothing here can decide a run. The outcome comes from the caller, a ledger that cannot be written is reported once and skipped, and a Ledger with no path does nothing, which is what a phase run by hand without a ledger gets.

func NewLedger

func NewLedger(path string, warnings io.Writer) *Ledger

NewLedger returns a ledger appending to path, reporting a failed append to warnings once. An empty path records nothing.

func (*Ledger) Row

func (l *Ledger) Row(kind, name, outcome string, start, end time.Time)

Row appends one stage. Kind is bootstrap, phase or scenario; outcome is what the caller already decided.

type ParallelCase

type ParallelCase struct {
	Name string
	Run  func(*testing.T)
}

ParallelCase owns the test state and fixtures used by one parallel lane.

type Run

type Run struct {
	// contains filtered or unexported fields
}

Run is one phase in progress: the scenarios it has run and where their durations go.

func Begin

func Begin[T any](t *testing.T, p phases.Of[T]) (*Run, T)

Begin starts phase p in test t. It holds t to the phase the binary was asked for, loads the inputs the driver bound, and returns them with the Run the phase records its scenarios through. The Run's context ends at the phase's timeout.

func (*Run) Context

func (r *Run) Context() context.Context

Context ends when the phase's timeout passes.

func (*Run) Logf

func (r *Run) Logf(format string, arguments ...any)

Logf writes a progress line the way the shell phases printed theirs.

func (*Run) Prepared

func (r *Run) Prepared()

Prepared ends the phase at its preparation boundary: the scenarios another suite runs it for have passed, and the phase's own acceptance is not what this run is for. It has to be called exactly there. A phase with no preparation mode, or a run that has not reached the boundary or has gone past it, fails, so preparation cannot pass for a phase that stopped early.

func (*Run) Scenario

func (r *Run) Scenario(name string, body func(t *testing.T)) bool

Scenario runs body as the phase's next scenario, as a subtest named for it, and records its duration and outcome in the timing ledger. It returns whether the scenario passed; a phase stops at the first one that did not, because each scenario starts from the state the one before it left.

The name has to be the next one the phase declared. A skipped scenario fails the phase: it would otherwise read as a scenario that passed.

func (*Run) Stderr

func (r *Run) Stderr() io.Writer

Stderr is where diagnostics for a failure go, ahead of the failure itself.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL