// Generated by conforma CLI documentation tooling. DO NOT EDIT.
= ec opa test

Execute Rego test cases

== Synopsis

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.

[source,shell]
----
ec opa test <path> [path [...]] [flags]
----
== Options

--bench:: benchmark the unit tests (Default: false)
--benchmem:: report memory allocations with benchmark results (Default: true)
-b, --bundle:: load paths as bundle files or root directories (Default: false)
--capabilities:: set capabilities version or capabilities.json file path
--count:: number of times to repeat each test (Default: 1)
-c, --coverage:: report coverage (overrides debug tracing) (Default: false)
-z, --exit-zero-on-skipped:: skipped tests return status 0 (Default: false)
--explain:: enable query explanations (Default: fails)
--fail-on-empty:: Whether to fail the test when no test was run (Default: false)
-f, --format:: set output format (Default: pretty)
-h, --help:: help for test (Default: false)
--ignore:: set file and directory names to ignore during loading (e.g., '.*' excludes hidden files) (Default: [])
-m, --max-errors:: set the number of errors to allow before compilation fails early (Default: 10)
-p, --parallel:: 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:: sort the JSON formatted test output (Default: none)
-t, --target:: set the runtime to exercise (Default: rego)
--threshold:: set coverage threshold and exit with non-zero status if coverage is less than threshold % (Default: 0)
--timeout:: set test timeout (default 5s, 30s when benchmarking) (Default: 0s)
--v0-compatible:: opt-in to OPA features and behaviors prior to the OPA v1.0 release (Default: false)
--v1-compatible:: opt-in to OPA features and behaviors that are enabled by default in OPA v1.0 (Default: false)
--var-values:: show local variable values in test output (Default: false)
-v, --verbose:: set verbose reporting mode (Default: false)
-w, --watch:: watch command line files for changes (Default: false)

== Options inherited from parent commands

--debug:: same as verbose but also show function names and line numbers (Default: false)
--kubeconfig:: path to the Kubernetes config file to use
--logfile:: file to write the logging output. If not specified logging output will be written to stderr
--quiet:: less verbose output (Default: false)
--retry-duration:: base duration for exponential backoff calculation (Default: 1s)
--retry-factor:: exponential backoff multiplier (Default: 2)
--retry-jitter:: randomness factor for backoff calculation (0.0-1.0) (Default: 0.1)
--retry-max-retry:: maximum number of retry attempts (Default: 3)
--retry-max-wait:: maximum wait time between retries (Default: 3s)
--trace:: enable trace logging, set one or more comma separated values: none,all,perf,cpu,mem,opa,log (Default: none)

== See also

 * xref:ec_opa.adoc[ec opa - Open Policy Agent (OPA) (embedded)]
