Run Rego tests
rego_testRun Rego unit tests with opa test to validate policy logic. Get aggregate pass/fail counts, filter by test name regex, and enforce minimum coverage thresholds.
Instructions
Run Rego unit tests with opa test. Returns aggregate pass/fail counts plus per-test records. Tests live in *_test.rego files; rule names beginning with test_ are picked up automatically. Use runPattern to filter by name regex; when no tests match, the error hint includes the pattern you supplied. Use threshold to gate on minimum coverage (returns COVERAGE_BELOW_THRESHOLD on failure). Use varValues: true with verbose: true to include local variable bindings in the trace -- essential for debugging table-driven tests written with every tc in cases { ... } to identify which case caused a failure. When tests use the test_X[case] parametrized form, the output includes parameterizedGroups mapping each base test name to its case records. Use ignorePatterns to exclude generated or fixture files. Use bundle: true when testing bundle-structured policy directories. Use timeout to raise the per-test limit beyond OPA's default 5s. Note: enabling coverage or threshold switches OPA to coverage-report output mode -- per-test counts are unavailable but coverage and coveragePct fields are populated.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| paths | Yes | Test directories or files. `opa test` looks for `*_test.rego` siblings of source files. | |
| verbose | No | Emit per-test pass/fail details. | |
| coverage | No | Include per-line coverage data. Switches output to coverage-report mode: test record counts are not available, but `coverage` and `coveragePct` fields are populated. | |
| runPattern | No | Run only tests whose names match this regular expression (passed as `--run`). | |
| threshold | No | Minimum coverage percentage required (0–100). Returns COVERAGE_BELOW_THRESHOLD when actual coverage falls below this value. Implicitly enables coverage-report output mode. | |
| varValues | No | Include local variable bindings in trace output (`--var-values`). When a table-driven test using `every tc in cases { ... }` fails, the trace shows which `tc` triggered the failure. Has no effect unless `verbose: true` is also set (OPA only emits trace entries in verbose mode). | |
| ignorePatterns | No | Glob patterns for files to exclude from the test run (`--ignore <pattern>`). Pass one pattern per array element. Useful for excluding generated or fixture files that contain no tests (e.g. `["*_generated.rego", "fixtures/**"]`). | |
| bundle | No | Load paths as OPA bundle roots (`--bundle`). Required when testing policies structured as bundles with a `manifest.json` at the root. Not needed for plain policy directories. | |
| count | No | Number of times to repeat each test (`--count N`). Default is 1. Useful for measuring repeatability or catching flaky tests under load. | |
| timeout | No | Per-test timeout as a Go duration string, e.g. `"30s"` or `"2m"` (`--timeout`). OPA's default is 5s. Increase for tests that load large policy sets or call slow built-ins. | |
| explain | No | Add a query-explanation trace to test records (`--explain`). `fails` traces only failing tests, `full` traces everything, `notes` surfaces `trace()` notes, `debug` is most verbose. Populates each record's `trace` field; pair with `verbose: true` for the human-readable trace output too. | |
| v1Compatible | No | Opt in to OPA v1.0-compatible behaviors (`--v1-compatible`). |