{"id":39392992,"url":"https://github.com/lanvstn/kutest","last_synced_at":"2026-01-18T03:14:04.607Z","repository":{"id":177065045,"uuid":"657973728","full_name":"lanvstn/kutest","owner":"lanvstn","description":"Kutest helpers for Kubernetes testing","archived":false,"fork":false,"pushed_at":"2023-06-28T21:49:52.000Z","size":51,"stargazers_count":5,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-11-19T03:12:32.905Z","etag":null,"topics":["kubernetes","testing"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lanvstn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-24T11:25:08.000Z","updated_at":"2023-06-28T20:40:12.000Z","dependencies_parsed_at":"2023-07-10T07:00:49.020Z","dependency_job_id":null,"html_url":"https://github.com/lanvstn/kutest","commit_stats":null,"previous_names":["lanvstn/kutest"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/lanvstn/kutest","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanvstn%2Fkutest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanvstn%2Fkutest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanvstn%2Fkutest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanvstn%2Fkutest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lanvstn","download_url":"https://codeload.github.com/lanvstn/kutest/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanvstn%2Fkutest/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28528034,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["kubernetes","testing"],"created_at":"2026-01-18T03:14:04.053Z","updated_at":"2026-01-18T03:14:04.592Z","avatar_url":"https://github.com/lanvstn.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kutest\n\nKutest is a Ginkgo helper library to help you write tests for your Kubernetes clusters.\n\nIt aims to be easy to operate in the following ways:\n\n- Nothing is required to be deployed on the cluster to run tests.\n- Readable test code that cuts down on the noise and gets to the point of the test.\n- You can run the suite from your local machine or from the cluster depending on your use-case. It works the same. This brings you a nice local development loop to iterate on changes without the logic being too different in a continuous integration context.\n- Parallelism-friendly to speed up test suite performance.\n\nHere's how it looks:\n\n```go\nSpecify(\"hello world\", func() {\n    WithJob(JobOptions{Namespace: \"default\"}, func() {\n        fmt.Fprintln(GinkgoWriter, \"hello from pod!\")\n    })\n})\n```\n\nRead [kutest_test.go](./kutest_test.go) for examples, such as testing connectivity between two pods. \n\n## Usage\n\nInstall to your project: `go get github.com/lanvstn/kutest`\n\nYou'll want to package your test as a container image. Read [Dockerfile](./Dockerfile) for an example.\n\nHere's a quick example with Kind:\n\n```sh\n\u003e go install github.com/onsi/ginkgo/v2/ginkgo\n\n\u003e export KUTEST_IMAGE=\"localhost/kutest-example:latest\"\n\u003e export KUTEST_DEFAULTIMAGEPULLPOLICY=\"IfNotPresent\" # Only for Kind clusters.\n\n\u003e docker build . -t \"$KUTEST_IMAGE\" \u0026\u0026 \\\n    kind load docker-image \"$KUTEST_IMAGE\" \u0026\u0026 \\\n    ginkgo run --json-report=report.json -v\n\n\u003e go run ./cmd/kutesthtml \u003c report.json \u003e report.html\n```\n\n### Note on image settings\n\nIt's very important that whatever is running locally (on the _controller_) is the same \nas on the pods spawned by Kutest due to how Kutest identifies its pods (using `runtime.Callers`).\nKeep this in mind when building images. \n\n- If `KUTEST_IMAGE` is a tagged with \nsomething you're planning to overwrite, don't set `KUTEST_DEFAULTIMAGEPULLPOLICY`. \n- Make sure others are not pushing the same `KUTEST_IMAGE` during your testing.\n\n## Documentation\n\n### Pitfalls\n\nThis is a weekend project. I can fix some of these up. But for now these are easier to document. Watch out for:\n\n- Don't `WithJob` from inside a `WithJob`!\n  - I can prevent this from being possible but have not added this safeguard\n  - A `WithJob` should be able to `WithJob` in the future. One scenario is testing the running of jobs from a job (RBAC). However, currently this is not possible due to the single-controller design.\n\n### Using with different test frameworks\n\nYou may have an exisiting test suite. For example, let's say you're doing continuous load testing using K6.\n\nThis is do-able with Kutest as well: you don't have to implement everything in Go.\n\n1. Write a Go helper around your test tool\n2. Ensure the dependencies are packaged in your test container image\n3. Use your helper. E.g.:\n\n```golang\nIt(\"passes the K6 loadtest\", func() {\n    WithJob(JobOptions{\n        Namespace: \"default\",\n        // TODO: may want to override some resource limits here\n    }, func() {\n        // TODO: implement K6Helper, which runs a local k6 binary with the given file\n        K6Helper(\"my_loadtest.js\")\n    })\n})\n```\n\n### About reporting\n\nGinkgo has a built-in report generation system. You can use its output by passing `--json-report=report.json` to `gingko run`. \n\n`./cmd/kutesthtml` provides a basic `html/template` coverter for this JSON format that uses stdin and stdout. \n\nOn the resulting page you can view the result of the suite, every test, and the logs of the jobs that were started by Kutest.\n\n### WithJob\n\nWithJob makes your test suite replicate itself throughout your cluster. Based on the current pod name, the library is aware whether it is running inside the job where the passed function is desired to run. \n\nThe first instance of the running test suite is called the _controller_. This is determined by the `KUTEST_SESSID` environment variable: if it is set, the current instance is part of an existing session and cannot be the controller. The controller creates the session ID and adds it through the environment variable to each job it creates.\n\nThis gives the appearance of the test function being magically sent to a new job for execution, but without actually sending the code around and all complexity that comes with it.\n\nIt is not recommended to pass anything out of your WithJob call since the function you pass to it will not always run, but the other logic in your test will!\n\n## Project status\n\n- Weekend project.\n- Experimental library with unstable API.\n- Not known to be used in production.\n- Accepting contributions but make an issue before starting a PR.\n\n---\n\nMade with :3 by Lander","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flanvstn%2Fkutest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flanvstn%2Fkutest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flanvstn%2Fkutest/lists"}