Skip to main content
The kyverno test command helps policy authors build automated, repeatable test suites for Kyverno policies. While kyverno apply is great for ad-hoc, developer-focused validation, kyverno test lets you assert expected behavior across many resources and detect regressions when policies change.
The image illustrates a role titled "Policy Author" and highlights the importance of ensuring policies are correct and avoiding breaks when making changes.
Why unit tests for policies?
  • Policy authors need confidence that policies:
    • Pass for valid resources.
    • Fail for invalid resources.
    • Are skipped for excluded resources.
  • Manually running kyverno apply for many scenarios is error-prone and doesn’t scale.
  • kyverno test provides a declarative test runner to automate these checks in CI/CD pipelines.
The image shows a gear surrounded by circular arrows with a check mark and an X mark, labeled "Testing."
Key difference: kyverno apply vs kyverno test
  • kyverno apply: Imperative, ad-hoc. Use when you want to quickly check how a policy affects a resource during development.
  • kyverno test: Declarative test framework. Use to assert expected outcomes (pass/fail/skip/warn or expected mutated/generated resources) and run those assertions automatically.
Use kyverno apply for interactive debugging; use kyverno test to create reproducible assertions suitable for CI/CD and regression detection.
The image is a table comparing "kyverno apply" and "kyverno test" in terms of use case, question it answers, and workflow. It outlines differences between ad-hoc checks and structured test suites.
Overview: kyverno-test.yaml (manifest) The test runner looks for a manifest, conventionally named kyverno-test.yaml or kyverno-test.yml. This file declares inputs (policies, resources, optional exceptions and variables) and expected outputs (results). Place the manifest and related fixtures in a directory and run the CLI against that directory.
The image explains the "kyverno test" command, which uses a file named "kyverno-test.yaml" for execution.
File structure at a glance
  • Inputs
    • policies: list of policy file paths
    • resources: list of resource fixtures
    • exceptions: optional exception policies
    • variables: optional values file for substitutions
  • Results
    • Declarative assertions tying a policy, rule, and resource to an expected result (pass/fail/skip/warn)
    • For mutate/generate rules, include patchedResource or generatedResource to compare the actual output to a file
Minimal example test manifest
Concrete example with results
Notes on fields
  • policies and resources are file paths (relative or absolute) the runner reads.
  • variables points to a values file if your policies use substitutions.
  • The results list is the core: each entry maps a policy, rule, and resource to an expected result.
Testing validate rules
  • For validation-style rules, asserting the evaluation outcome (pass, fail, skip, or warn) is usually sufficient:
Testing mutate and generate rules
  • For mutate rules, you must verify the actual mutation. Use patchedResource with the expected post-mutation YAML.
  • For generate rules, use generatedResource to assert the exact generated resource content.
  • The test runner performs a deep comparison between actual and expected files, making assertions precise for complex transformations.
Examples:
When asserting mutated/generated resources, ensure your expected YAML files account for defaulted fields and ordering differences. Use exact, deterministic fixtures to avoid false negatives.
Running the test suite
  1. Place:
    • kyverno-test.yaml (or .yml)
    • policy files
    • resource fixtures
    • expected patchedResource/generatedResource files
  2. Run the CLI from the directory (use . for current directory):
Sample CLI output
Why integrate kyverno test in CI/CD?
  • Detect regressions when policies change.
  • Provide deterministic, automated verification for policy libraries.
  • Improve confidence for policy maintainers and reduce manual verification effort.
The image contains a summary of three key points related to formal test suites for policies: the goal of creating a suite, the significance of the kyverno-test.yaml file, and the concept of declarative testing.
Recap
  • kyverno test is a declarative framework to assert policy behavior across resources and scenarios.
  • The kyverno-test.yaml file defines inputs (policies, resources, exceptions, variables) and expected outputs (results).
  • Use simple result assertions for validate rules; use patchedResource/generatedResource to verify mutate and generate rules.
  • Add kyverno test into CI/CD pipelines to automatically catch regressions and give policy authors confidence when changing policies.
Links and references

Watch Video

Practice Lab