Fixtures & CLI¶
The pytest fixtures¶
hokea.pytest_plugin
¶
hokea's pytest integration.
Your conftest.py defines ONE fixture describing how to build your cluster:
import pytest
from hokea import Cluster
@pytest.fixture
def hokea_cluster(tmp_path):
return Cluster(image="python:3.12-slim", src="./server",
cmd="python server.py", nodes=3, name="myproj",
port=8000, workdir=tmp_path / "cluster")
and your tests then use:
cluster — the cluster, up and healthy (torn down after the test)
net — a Net bound to it (network faults)
chaos — apply your own Chaos Mesh YAML in the fault schedule
(Kubernetes backend only)
run — run_workload bound to the cluster, with each run's directory
created automatically under runs/, named after the test
pytest --repeat 3 runs every selected test 3 times, to expose flakiness.
The plugin is installed with hokea (a pytest11 entry point) — there is
nothing to enable. You define hokea_cluster in your conftest.py; the
fixtures below are provided:
cluster- Your
hokea_cluster, entered andwait_healthy()-ed before the test body runs, torn down after it — every test starts from a fresh, healthy fleet. Works with either backend (ClusterorKubeCluster). net- The network fault injector matching the backend:
Net(iptables/netem) on Docker,KubeNet(Chaos Mesh) on Kubernetes. Same API either way:partition,isolate,slow,heal. chaos- A
KubeChaos: apply your own Chaos Mesh YAML inside the fault schedule. Kubernetes backend only — on the Docker backend using it raises, naming the local alternatives. runrun_workloadwith the cluster already bound and the run directory created automatically underruns/, named after the test:h = run(ops, adapter, duration=30, faults=[...])returns aRunHandle.recordrecord_runbound the same way — a context manager for runs with no client workload (batch jobs, training): faults and events are recorded, no history.
The plugin also adds one pytest option:
pytest --repeat N # run each selected test N times (expose flaky tests)
The hokea command line¶
hokea has three jobs: running your pytest suite on the class cluster
(hokea test), converting a run's history for an external checker
(hokea export), and deploying your system on the class Kubernetes
cluster and leaving it running for you
to look at by hand with kubectl (hokea k8s). Local recorded runs stay plain
pytest: the fixtures above bring a fresh Docker cluster up and tear it
down per test.
hokea test¶
Run this project's pytest suite on the class cluster. The directory's
top-level files ship to the cluster, a runner in your team's client
namespace runs pytest there (so the servers, faults, and load all stay
inside the cluster), the live pytest output streams to your terminal,
the recorded runs/ are copied back into ./runs/, and the exit code
is pytest's own. The introductory lab's Act 3 walks through it.
hokea test --namespace NS [pytest args...]
| Flag | Meaning |
|---|---|
--namespace NS |
your team's SERVER namespace, where the system under test runs (default: $HOKEA_NAMESPACE) |
--client-namespace NS |
where the runner itself runs (default: <namespace>-clients) |
--runner-cpus N |
CPUs for the runner — the load generator, not your servers (default: 2, max 4) |
--keep |
leave the runner Job and ConfigMap on the cluster afterwards, for debugging |
| anything else | passed to pytest verbatim (-q, -k partition, -x, -s, file names; put -- first if an argument collides with hokea's own flags) |
HOKEA_NODES and HOKEA_TAKEOVER set in your shell are forwarded into
the cluster-side run. Ctrl-C detaches (the run continues; hokea prints
how to re-attach and clean up) — but a detached run's runs/ are not
copied back automatically.
hokea export¶
Convert a run's history for an external checker, printed to stdout.
hokea export --format {porcupine,jepsen} RUN_DIR
| Argument | Meaning |
|---|---|
--format {porcupine,jepsen} |
output format (required) |
RUN_DIR |
a runs/<timestamp>-<name> directory |
hokea ships no linearizability checker; if you claim linearizability, export to Porcupine (see the checks guide).
hokea k8s up¶
Deploy N nodes and leave them running. The source directory ships to the
pods as a ConfigMap — no image build, no registry. State is remembered in
.hokea/k8s-<name>.json relative to the current directory, so run
up/status/down from the same place.
hokea k8s up --namespace NS --src DIR --cmd "python server.py"
| Flag | Meaning |
|---|---|
--namespace NS |
an existing namespace you may create pods in (required) |
--src DIR |
directory with your server code (ships to the pods as a ConfigMap — no image build, no registry) (required) |
--cmd CMD |
start command, e.g. "python server.py" (required) |
--image IMAGE |
base image to run --cmd on (default: python:3.12-slim) |
--nodes N |
how many nodes (default: 3) |
--port PORT |
the port your server listens on (default: 8000) |
--name NAME |
cluster name, if you want more than one (default: default) |
--env KEY=VAL |
extra environment for every node (repeatable) |
--data NAME=REF |
dataset image mounted read-only in every node at /dataset/NAME (repeatable; one bare REF mounts at /dataset) |
--takeover |
replace a still-running cluster with this name instead of refusing |
hokea k8s status¶
Show a deployed cluster's pods and how to reach them (one
kubectl port-forward line per node).
hokea k8s status [--name NAME]
| Flag | Meaning |
|---|---|
--name NAME |
cluster name (default: default) |
hokea k8s down¶
Delete a deployed cluster — everything it created (pods, services, configmaps, chaos rules), found by label, never by sweeping the namespace.
hokea k8s down [--name NAME] [--namespace NS]
| Flag | Meaning |
|---|---|
--name NAME |
cluster name (default: default) |
--namespace NS |
only needed if the state file from up is gone |