# kyverno test: Declarative Policy Test Cases

> kyverno test runs declarative test cases (kyverno-test.yaml) asserting expected policy results. Reference for the results table, --remove-color, and Fail rows in CI.

Source: https://latchkey.dev/learn/command-reference/kyverno-test  
Updated: 2026-06-30

kyverno test discovers kyverno-test.yaml manifests and checks that each policy rule produces the expected result for each resource, failing on any mismatch.

kyverno test is the unit-test layer for Kyverno policies. You declare, in a kyverno-test.yaml, which rule should pass or fail on which resource, and the CLI verifies the policy still behaves that way.

## What it does

kyverno test recursively finds kyverno-test.yaml files under the given path. Each declares policies, resources, and a results list mapping (policy, rule, resource) to an expected result (pass, fail, skip). The CLI runs the policies and prints a table marking each expectation Pass or Fail, exiting non-zero on any Fail.

## Common usage

```Terminal
# run every kyverno-test.yaml under the current tree
kyverno test .
# run tests in a specific directory
kyverno test ./policies/require-labels
# plain output for CI logs (no ANSI colors)
kyverno test . --remove-color
```

## Options

| Flag | What it does |
| --- | --- |
| <path> | Directory to search recursively for kyverno-test.yaml |
| -f, --file-name <name> | Test file name to look for (default kyverno-test.yaml) |
| --remove-color | Disable ANSI colors for clean CI logs |
| --detailed-results | Show full results including passing rows |
| --fail-only | Only display failing rows in the table |

## In CI

Keep a kyverno-test.yaml next to each policy and run kyverno test . as a required check in the policy repo. Add --remove-color so the results table stays readable in the Actions log, and --fail-only to make failures easy to spot in large suites.

## Common errors in CI

A mismatch shows a table row with RESULT "Fail" and the process exits 1: the actual policy verdict differed from the results block you declared. "Error: test files not found" means no kyverno-test.yaml exists under the path. "failed to load test file" points at malformed test YAML. If a row shows "Skip" unexpectedly, the resource kind did not match the policy.

## Using this in CI

A runner has no kubeconfig, no cached context, and no interactive auth. Every kubectl invocation in CI needs the context supplied explicitly, and most confusing CI failures here are the command running against the wrong cluster or no cluster at all.

```Terminal
# never rely on the ambient context on a runner
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" get pods

# confirm what you are actually connected to before mutating anything
kubectl config current-context
kubectl cluster-info

# fail fast instead of hanging on an unreachable API server
kubectl --request-timeout=30s get nodes
```

> Always set `--request-timeout` in CI. Without it an unreachable API server hangs until the job times out, which turns a thirty-second failure into a twenty-minute one.

## FAQ

### kyverno test: Declarative Policy Test Cases?

kyverno test is the unit-test layer for Kyverno policies. You declare, in a kyverno-test.yaml, which rule should pass or fail on which resource, and the CLI verifies the policy still behaves that way.

### What it does?

kyverno test recursively finds kyverno-test.yaml files under the given path. Each declares policies, resources, and a results list mapping (policy, rule, resource) to an expected result (pass, fail, skip). The CLI runs the policies and prints a table marking each expectation Pass or Fail, exiting non-zero on any Fail.

### In CI?

Keep a kyverno-test.yaml next to each policy and run kyverno test . as a required check in the policy repo. Add --remove-color so the results table stays readable in the Actions log, and --fail-only to make failures easy to spot in large suites.

### Common errors in CI?

A mismatch shows a table row with RESULT "Fail" and the process exits 1: the actual policy verdict differed from the results block you declared. "Error: test files not found" means no kyverno-test.yaml exists under the path. "failed to load test file" points at malformed test YAML.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt