Features

Ask for what you need by name. vitekube sets it up and cleans up after it.

What test gives you

test from vitekube is Vitest's test with these fixtures. Use only the ones you ask for.

Ask for	You get
k8s	Apply, wait, exec, read logs and port-forward on the real cluster
namespace	A new namespace for this test, deleted afterward
scope	Cleanup functions that run in reverse order
evidence	Extra failure output, and control over what counts as secret

Test what happens when things break

scaleTemporarily takes a workload down and puts it back when the block ends, even if the test throws or times out.

const WORKER = { namespace: "default", name: "worker" };

test("the app survives losing its worker", async ({ k8s }) => {
  await using worker = await k8s.scaleTemporarily(WORKER, 0);

  // The worker is down here. Check how the rest of the system behaves.
});

Call worker.restore() to bring it back sooner. It waits for the rollout, and it's safe to call twice.

Scaling down returns before the pods have gone, and a pod that is still terminating can pick up work. If your test needs the workload truly gone, wait for its pods to exit first.

If putting shared state back fails, the cluster is flagged as unusable. Later tests stop and tell you why, rather than failing in confusing ways.

Commands

Command	What it does
npx vitest run	Run everything, reusing the cluster
npx vitest run web	Run only files matching web
npx vitest run -t "answers"	Run only tests matching a name
VITEKUBE_REBUILD=1 npx vitest run	Redo every image and stage
VITEKUBE_CLUSTER=other npx vitest run	Use another cluster, such as one per worktree
VITEKUBE_KEEP_ON_FAILURE=1 npx vitest run	Keep a failed test's namespace to inspect

Cluster options

Option	Meaning
name	The k3d cluster's name
reuse	Keep the cluster between runs. Otherwise each run gets a new one and deletes it
agents	Number of worker nodes, on top of the server
k3sArgs	Extra k3s flags, such as ["--disable=traefik@server:0"]

Good to know

• Only k3d is supported for managed clusters today.
• Run test files one at a time. Keep fileParallelism: false if your tests share cluster-wide state.
• One run per cluster. A second run fails straight away. Use lockWaitMs to wait instead, or VITEKUBE_CLUSTER to use another cluster.
• Add readiness probes to what you wait for. waitForRollout follows Kubernetes, and without a probe a container that crashes moments after starting can still count as rolled out.

The README has the full list.