Conftest

To run unit tests for your policies, follow the convention of naming your test files <policy_name>_test.rego. Use the conftest verify command to execute them.

conftest verify --policy <path_to_policy_dir>

conftest verify --policy ./policy

When working with complex Rego queries, you can use the --trace flag to see exactly how a policy is applied. This outputs a detailed execution trace from Open Policy Agent, showing rule evaluations, indexing, and failures.

$ conftest test --trace deployment.yaml

If you have a working Go environment, you can install Conftest from source. The binary will be installed to your configured $GOPATH/bin folder.

CGO_ENABLED=0 go install github.com/open-policy-agent/conftest@latest

The --trace flag can be combined with any output format (e.g., --output=table or --output=json). When used this way, the trace information is written to stderr, while the formatted policy results are written to stdout.

# Output trace to stderr and table format to stdout
$ conftest test --trace --output=table deployment.yaml

You can pull policies from Git repositories using the git:: protocol prefix. You can specify a subfolder within the repository using the // delimiter after the .git suffix.

Format: git::https://<host>/<Organization>/<Repository>.git//<sub/folder>

conftest pull git::https://github.com/<Organization>/<Repository>.git//sub/folder

To test a configuration file, write your assertions in Rego files (e.g., policy/deployment.rego) and then use the conftest test command followed by the path to your configuration file. Conftest will evaluate the configuration against your policies and report failures.

package main

deny contains msg if {
  input.kind == "Deployment"
  not input.spec.template.spec.securityContext.runAsNonRoot

  msg := "Containers must not run as root"
}

deny contains msg if {
  input.kind == "Deployment"
  not input.spec.selector.matchLabels.app

  msg := "Containers must provide app label for pod selectors"
}

$ conftest test deployment.yaml
FAIL - deployment.yaml - Containers must not run as root
FAIL - deployment.yaml - Containers must provide app label for pod selectors

2 tests, 0 passed, 0 warnings, 2 failures, 0 exceptions

You can use Conftest as a pre-commit hook to validate configuration files and run policy unit tests before committing.

Add the following configuration to your .pre-commit-config.yaml file. Use conftest-test to validate configurations and conftest-verify to run unit tests for your policies.

repos:
  - repo: https://github.com/open-policy-agent/conftest
    rev: v0.64.0  # Use a specific tag or 'HEAD' for the latest commit
    hooks:
      - id: conftest-test
        args: [--policy, path/to/your/policies]  # Specify your policy directory
      # Optional: Add the verify hook to run policy unit tests
      - id: conftest-verify
        args: [--policy, path/to/your/policies]

Once a plugin is installed, Conftest automatically loads all available plugins from the cache during the next execution. The plugin becomes available as a subcommand in the Conftest CLI based on the name defined in the plugin's plugin.yaml.

For example, if a plugin is named kubectl, you can invoke it using conftest kubectl followed by the plugin's specific arguments and policies.

conftest kubectl deployment <deployment-id> --policy examples/kubernetes/policy

On macOS or Linux, you can install Conftest using the Homebrew package manager.

brew install conftest

You can provide structured documentation for your OPA policies by using METADATA annotations directly in your policy files. To ensure meaningful generated documentation, packages should include at least a title field, and rules should include both title and description fields.

# METADATA
# title: My rule
# description: A rule that determines if x is allowed.
# authors:
# - John Doe <john@example.com>
# entrypoint: true
allow if {
  ...
}