opa-test - Man Page

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 {
	input.path = ["users"]
	input.method = "POST"
}

allow {
	input.path = ["users", profile_id]
	input.method = "GET"
	profile_id = input.user_id
}

Example test (example/authz_test.rego):

package authz

test_post_allowed {
	allow with input as {"path": ["users"], "method": "POST"}
}

test_get_denied {
	not allow with input as {"path": ["users"], "method": "GET"}
}

test_get_user_allowed {
	allow with input as {"path": ["users", "bob"], "method": "GET", "user_id": "bob"}
}

test_get_another_user_denied {
	not allow with input as {"path": ["users", "bob"], "method": "GET", "user_id": "alice"}
}

todo_test_user_allowed_http_client_data {
	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.

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

--count=1 number of times to repeat each test (default 1)

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

--explain=fails enable query explanations

-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

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

-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=5s set test timeout

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

See Also

opa(1)

Referenced By

opa(1).

May 2021