NAME

opa-test - Execute Rego test cases

SYNOPSIS

opa test [path [...]] [flags]

DESCRIPTION

Execute Rego test cases.

The 'test' command takes a file or directory path as input and executes all test cases discovered in matching files. Test cases are rules whose names have the prefix "test_".

If the '--bundle' option is specified the paths will be treated as policy bundles and loaded following standard bundle conventions. The path can be a compressed archive file or a directory which will be treated as a bundle. Without the '--bundle' flag OPA will recursively load ALL *.rego, *.json, and *.yaml files for evaluating the test cases.

Test cases under development may be prefixed "todo_" in order to skip their execution, while still getting marked as skipped in the test results.

Example policy (example/authz.rego):

package authz
allow if {
	input.path == ["users"]
	input.method == "POST"
}
allow if {
	input.path == ["users", input.user_id]
	input.method == "GET"
}

Example test (example/authz_test.rego):

package authz_test
import data.authz.allow
test_post_allowed if {
	allow with input as {"path": ["users"], "method": "POST"}
}
test_get_denied if {
	not allow with input as {"path": ["users"], "method": "GET"}
}
test_get_user_allowed if {
	allow with input as {"path": ["users", "bob"], "method": "GET", "user_id": "bob"}
}
test_get_another_user_denied if {
	not allow with input as {"path": ["users", "bob"], "method": "GET", "user_id": "alice"}
}
todo_test_user_allowed_http_client_data if {
	false # Remember to test this later!
}

Example test run:

$ opa test ./example/

If used with the '--bench' option then tests will be benchmarked.

Example benchmark run:

$  opa test --bench ./example/

The optional "gobench" output format conforms to the Go Benchmark Data Format.

The --watch flag can be used to monitor policy and data file-system changes. When a change is detected, OPA reloads the policy and data and then re-runs the tests. Watching individual files (rather than directories) is generally not recommended as some updates might cause them to be dropped by OPA.

OPTIONS

--bench[=false] benchmark the unit tests

--benchmem[=true] report memory allocations with benchmark results

-b, --bundle[=false] load paths as bundle files or root directories

--capabilities="" set capabilities version or capabilities.json file path

--count=1 number of times to repeat each test

-c, --coverage[=false] report coverage (overrides debug tracing)

--coverage-runs=[index_excluded,early_exit] supplementary coverage passes that annotate not-covered ranges with a kind (requires --coverage); pass an empty list to disable

-z, --exit-zero-on-skipped[=false] skipped tests return status 0

--explain=fails enable query explanations

--fail-on-empty[=false] Whether to fail the test when no test was run

-f, --format=pretty set output format

-h, --help[=false] help for test

--ignore=[] set file and directory names to ignore during loading (e.g., '.*' excludes hidden files)

-m, --max-errors=10 set the number of errors to allow before compilation fails early

-p, --parallel=32 the number of tests that can run in parallel, defaulting to the number of CPUs (explicitly set with 0). Benchmarks are always run sequentially.

-r, --run="" run only test cases matching the regular expression

-s, --schema="" set schema file path or directory path

--sort=none sort the JSON formatted test output

-t, --target=rego set the runtime to exercise

--threshold=0 set coverage threshold and exit with non-zero status if coverage is less than threshold %

--timeout=0s set test timeout (default 5s, 30s when benchmarking)

--v0-compatible[=false] opt-in to OPA features and behaviors prior to the OPA v1.0 release

--var-values[=false] show local variable values in test output

-v, --verbose[=false] set verbose reporting mode

-w, --watch[=false] watch command line files for changes

SEE ALSO

opa(1)