Skip to main content

No project description provided

Project description


pytest-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 and remove them again. The 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 about the kubeconfig on the test machine.


  • Set up and tear down (local) Kubernetes clusters with minikube, k3d and kind
  • Configure the cluster to recreate for each test case (default), or keep it across multiple test cases
  • Automatic management of the kubeconfig
  • Simple functions to run kubectl commands (with dict output), reading logs and load custom container images
  • Wait for certain conditions in the cluster
  • Port forward Kubernetes-based services (using kubectl port-forward) easily during a test case
  • Management utils for custom pytest-fixtures (for example pre-provisioned clusters)


This plugin can be installed from PyPI:

  • pip install pytest-kubernetes
  • poetry add -D pytest-kubernetes

Note that this package provides entrypoint hooks to be automatically loaded with pytest.


pytest-kubernetes expects the following components to be available on the test machine:

  • kubectl
  • minikube (optional for minikube-based clusters)
  • k3d (optional for k3d-based clusters)
  • kind (optional for kind-based clusters)
  • Docker (optional for Docker-based Kubernetes clusters)

Please make sure they are installed to run pytest-kubernetes properly.




The 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.

The fixture passes a manager object of type AClusterManager.

It provides the following interface:

  • kubectl(...): Execute kubectl command against this cluster (defaults to dict as returning format)
  • apply(...): Apply resources to this cluster, either from YAML file, or Python dict
  • load_image(...): Load a container image into this cluster
  • wait(...): Wait for a target and a condition
  • port_forwarding(...): Port forward a target
  • logs(...): Get the logs of a pod
  • version(): Get the Kubernetes version of this cluster
  • create(...): Create this cluster (pass special cluster arguments with options: List[str] to the CLI command)
  • delete(): Delete this cluster
  • reset(): Delete this cluster (if it exists) and create it again

The interface provides proper typing and should be easy to work with.


def test_a_feature_with_k3d(k8s: AClusterManager):
            "apiVersion": "v1",
            "kind": "ConfigMap",
            "data": {"key": "value"},
            "metadata": {"name": "myconfigmap"},

This cluster will be deleted once the test case is over.

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).


pytest-kubernetes uses pytest marks for specifying the cluster configuration for a test case

Currently the following settings are supported:

  • provider (str): request a specific Kubernetes provider for the test case
  • cluster_name (str): request a specific cluster name
  • keep (bool): keep the cluster across multiple test cases


@pytest.mark.k8s(provider="minikube", cluster_name="test1", keep=True)
def test_a_feature_in_minikube(k8s: AClusterManager):


To write custom Kubernetes-based fixtures in your project you can make use of the following util functions.


This function returns a deriving class of AClusterManager that is not created and wrapped in a fixture yet.

select_provider_manager(name: Optional[str] = None) -> Type[AClusterManager]

The returning object gets called with the init parameters of AClusterManager, the cluster_name: str.


def k8s_with_workload(request):
    cluster = select_provider_manager("k3d")("my-cluster")
    # if minikube should be used
    # cluster = select_provider_manager("minikube")("my-cluster")
    # init the cluster with a workload
    cluster.wait("deployments/hello-nginxdemo", "condition=Available=True")
    yield cluster

In this example, the cluster remains active for the entire session and is only deleted once pytest is done.

Note that yield notation that is prefered by pytest to express clean up tasks for this fixture.

Special cluster options

You can pass more options using kwargs['options']: List[str] to the create(options=...) function when creating the cluster like so:

    cluster = select_provider_manager("k3d")("my-cluster")
    # bind ports of this k3d cluster
    cluster.create(options=["--agents", "1", "-p", "8080:80@agent:0", "-p", "31820:31820/UDP@agent:0"])


Please find more examples in tests/ in this repository. These test cases are written as users of pytest-kubernetes would write test cases in their projects.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pytest_kubernetes-0.3.1.tar.gz (14.4 kB view hashes)

Uploaded Source

Built Distribution

pytest_kubernetes-0.3.1-py3-none-any.whl (16.5 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page