{"id":18471320,"url":"https://github.com/blueshoe/pytest-kubernetes","last_synced_at":"2025-08-22T02:06:46.062Z","repository":{"id":105012765,"uuid":"602134499","full_name":"Blueshoe/pytest-kubernetes","owner":"Blueshoe","description":"A :arrow_right: pytest plugin to make the management of (local) Kubernetes clusters a breeze. :rocket:","archived":false,"fork":false,"pushed_at":"2025-08-21T22:08:10.000Z","size":199,"stargazers_count":28,"open_issues_count":13,"forks_count":3,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-08-22T00:25:22.022Z","etag":null,"topics":["cicd","k3d","kind","kubernetes","minikube","pytest","pytest-plugin","python","testing"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Blueshoe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":"FUNDING.yml","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,"zenodo":null},"funding":{"custom":["https://blueshoe.io"]}},"created_at":"2023-02-15T15:11:46.000Z","updated_at":"2025-08-20T05:25:29.000Z","dependencies_parsed_at":"2023-10-03T00:03:26.253Z","dependency_job_id":"34c2a5d2-33bc-471d-a9b4-0e03b9647285","html_url":"https://github.com/Blueshoe/pytest-kubernetes","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/Blueshoe/pytest-kubernetes","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Blueshoe%2Fpytest-kubernetes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Blueshoe%2Fpytest-kubernetes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Blueshoe%2Fpytest-kubernetes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Blueshoe%2Fpytest-kubernetes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Blueshoe","download_url":"https://codeload.github.com/Blueshoe/pytest-kubernetes/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Blueshoe%2Fpytest-kubernetes/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271570721,"owners_count":24782720,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-21T02:00:08.990Z","response_time":74,"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":["cicd","k3d","kind","kubernetes","minikube","pytest","pytest-plugin","python","testing"],"created_at":"2024-11-06T10:16:35.882Z","updated_at":"2025-08-22T02:06:46.036Z","avatar_url":"https://github.com/Blueshoe.png","language":"Python","funding_links":["https://blueshoe.io"],"categories":[],"sub_categories":[],"readme":"# pytest-kubernetes\npytest-kubernetes is a lightweight pytest plugin that makes managing (local) Kubernetes clusters a breeze. You can easily spin up a Kubernetes cluster with one [pytest fixure](https://docs.pytest.org/en/latest/explanation/fixtures.html) and remove them again.\nThe fixture comes with some simple functions to interact with the cluster, for example `kubectl(...)` that allows you to run typical *kubectl* commands against this cluster without worring \nabout the *kubeconfig* on the test machine.\n\n**Features:**\n- Set up and tear down (local) Kubernetes clusters with *minikube*, *k3d* and *kind*\n- Configure the cluster to recreate for each test case (default), or keep it across multiple test cases\n- Automatic management of the *kubeconfig*\n- Simple functions to run kubectl commands (with *dict* output), reading logs and load custom container images\n- Wait for certain conditions in the cluster\n- Port forward Kubernetes-based services (using kubectl port-forward) easily during a test case\n- Management utils for custom pytest-fixtures (for example pre-provisioned clusters)\n \n## Installation\nThis plugin can be installed from PyPI:\n- `pip install pytest-kubernetes`\n- `poetry add -D pytest-kubernetes`\n\nNote that this package provides entrypoint hooks to be automatically loaded with pytest.\n\n## Requirements\npytest-kubernetes expects the following components to be available on the test machine:\n- [`kubectl`](https://kubernetes.io/docs/reference/kubectl/)\n- [`minikube`](https://minikube.sigs.k8s.io/docs/start/) (optional for minikube-based clusters)\n- [`k3d`](https://k3d.io/) (optional for k3d-based clusters)\n- [`kind`](https://kind.sigs.k8s.io/) (optional for kind-based clusters)\n- [Docker](https://docs.docker.com/get-docker/) (optional for Docker-based Kubernetes clusters)\n\nPlease make sure they are installed to run pytest-kubernetes properly.\n\n## Reference\n\n### Fixture\n\n#### k8s\nThe _k8s_ fixture provides access to an automatically selected Kubernetes provider (depending on the availability on the host). The priority is: k3d, kind, minikube-docker and minikube-kvm2.\n\nThe fixture passes a manager object of type *AClusterManager*.\n\nIt provides the following interface:\n- `kubectl(...)`: Execute kubectl command against this cluster (defaults to `dict` as returning format)\n- `apply(...)`: Apply resources to this cluster, either from YAML file, or Python dict\n- `load_image(...)`: Load a container image into this cluster\n- `wait(...)`: Wait for a target and a condition\n- `port_forwarding(...)`: Port forward a target\n- `logs(...)`: Get the logs of a pod\n- `version()`: Get the Kubernetes version of this cluster\n- `create(...)`: Create this cluster (pass special cluster arguments with `options: List[str]` to the CLI command)\n- `delete()`: Delete this cluster\n- `reset()`: Delete this cluster (if it exists) and create it again\n\nThe interface provides proper typing and should be easy to work with.\n\n**Example**\n\n```python\ndef test_a_feature_with_k3d(k8s: AClusterManager):\n    k8s.create()\n    k8s.apply(\n        {\n            \"apiVersion\": \"v1\",\n            \"kind\": \"ConfigMap\",\n            \"data\": {\"key\": \"value\"},\n            \"metadata\": {\"name\": \"myconfigmap\"},\n        },\n    )\n    k8s.apply(\"./dependencies.yaml\")\n    k8s.load_image(\"my-container-image:latest\")\n    k8s.kubectl(\n        [\n            \"run\",\n            \"test\",\n            \"--image\",\n            \"my-container-image:latest\",\n            \"--restart=Never\",\n            \"--image-pull-policy=Never\",\n        ]\n    )\n```\nThis cluster will be deleted once the test case is over.\n\n\u003e Please note that you need to set *\"--image-pull-policy=Never\"* for images that you loaded into the cluster via the `k8s.load(name: str)` function (see example above).\n\n### Marks\npytest-kubernetes uses [*pytest marks*](https://docs.pytest.org/en/7.1.x/how-to/mark.html) for specifying the cluster configuration for a test case\n\nCurrently the following settings are supported:\n\n- *provider* (str): request a specific Kubernetes provider for the test case \n- *cluster_name* (str): request a specific cluster name\n- *keep* (bool): keep the cluster across multiple test cases\n\n\n**Example**\n```python\n@pytest.mark.k8s(provider=\"minikube\", cluster_name=\"test1\", keep=True)\ndef test_a_feature_in_minikube(k8s: AClusterManager):\n    ...\n```\n\n### Utils\nTo write custom Kubernetes-based fixtures in your project you can make use of the following util functions.\n\n\n#### `select_provider_manager`\nThis function returns a deriving class of *AClusterManager* that is not created and wrapped in a fixture yet.\n\n`select_provider_manager(name: Optional[str] = None) -\u003e Type[AClusterManager]`\n\nThe returning object gets called with the init parameters of *AClusterManager*, the `cluster_name: str`.\n\n**Example**\n```python\n@pytest.fixture(scope=\"session\")\ndef k8s_with_workload(request):\n    cluster = select_provider_manager(\"k3d\")(\"my-cluster\")\n    # if minikube should be used\n    # cluster = select_provider_manager(\"minikube\")(\"my-cluster\")\n    cluster.create()\n    # init the cluster with a workload\n    cluster.apply(\"./fixtures/hello.yaml\")\n    cluster.wait(\"deployments/hello-nginxdemo\", \"condition=Available=True\")\n    yield cluster\n    cluster.delete()\n```\nIn this example, the cluster remains active for the entire session and is only deleted once pytest is done.\n\n\u003e Note that `yield` notation that is prefered by pytest to express clean up tasks for this fixture.\n\n#### Special cluster options\nYou can pass more options using `kwargs['options']: List[str]` to the `create(options=...)` function when creating the cluster like so:\n```python\n    cluster = select_provider_manager(\"k3d\")(\"my-cluster\")\n    # bind ports of this k3d cluster\n    cluster.create(options=[\"--agents\", \"1\", \"-p\", \"8080:80@agent:0\", \"-p\", \"31820:31820/UDP@agent:0\"])\n```\n\n## Examples\nPlease find more examples in *tests/vendor.py* in this repository. These test cases are written as users of pytest-kubernetes would write test cases in their projects.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblueshoe%2Fpytest-kubernetes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblueshoe%2Fpytest-kubernetes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblueshoe%2Fpytest-kubernetes/lists"}