# vitekube

> Vitest on real Kubernetes clusters. Write a normal Vitest test, run it on a real k3d cluster, and rerun it with only what changed rebuilt.

vitekube is an npm package, not a hosted service. It is MIT licensed, an early community project, and not affiliated with Vitest, Vite or the Kubernetes project.

What it can do:

- Give each test its own namespace, and delete it afterward.
- Apply YAML, wait, exec, read logs and port-forward on the real cluster.
- Declare a whole system once in TypeScript: images, manifests, Helm charts and custom stages. Only what changed runs again.
- Take a workload down during a test, and put it back afterward.
- Print events, pods and logs next to a failure, before cleanup deletes them.

To add it to a project:

1. Check for Docker, k3d, kubectl, Vitest 5 and Node `^22.18`, `^24.11` or `>=26`. Helm is needed only for charts.
2. Run `npm install --save-dev vitest vitekube`.
3. Follow the quick start in the README.

In a project that already uses it:

- Run one test: `npx vitest run <file> -t "<exact test name>"`
- Run everything: `npx vitest run`
- In a worktree, use your own cluster: `VITEKUBE_CLUSTER=<worktree-name> npx vitest run`
- After a failure, read the events, pods and logs printed above the error first.
- To inspect a failed test's namespace: add `VITEKUBE_KEEP_ON_FAILURE=1` and use the command it prints.
- To redo every image and stage: add `VITEKUBE_REBUILD=1`.

Its commands only reach the cluster you named, never the one your kubectl points at. Your own shell access is still up to you.

## Docs

- [README](https://raw.githubusercontent.com/vitekube/vitekube/main/README.md): The full guide: quick start, fixtures, the `k8s` client, whole-system stages, failure evidence, commands and cluster options.

## Examples

- [One Job](https://raw.githubusercontent.com/vitekube/vitekube/main/examples/hello/hello.test.ts): The smallest possible test.
- [Web server](https://raw.githubusercontent.com/vitekube/vitekube/main/examples/quick-start/web.test.ts): The test from the quick start.
- [Whole environment](https://raw.githubusercontent.com/vitekube/vitekube/main/examples/environment/k8s.setup.ts): An image, a manifest, a chart, a custom stage and a private value.

## Optional

- [Website](https://vitekube.com/): The same story, written for people.
- [Source](https://github.com/vitekube/vitekube): The repository, with every example.
- [npm package](https://www.npmjs.com/package/vitekube): Published versions.