Run Rego tests
rego_testRun Rego unit tests with opa test to return pass/fail/skip/error counts and per-test records, filter tests by regex, gate coverage thresholds, and add verbose traces for debugging.
Instructions
Run Rego unit tests with opa test. Returns aggregate pass/fail/skip/error counts plus per-test records. errored counts tests OPA could not evaluate (a rule conflict, a raising built-in); such a test is neither a pass nor a failure, and a suite with any is not passing. 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] parameterized form, OPA reports the rule as a single test whatever the number of cases; parameterizedGroups maps the rule name to a record per case and caseCounts totals them, so a failing rule says which case failed. 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. With coverage or threshold the suite runs a second time for the coverage report, which is added to the results; it is left out when a test fails or errors, since opa reports no coverage for such a run.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"paths": "<paths>"
},
"name": "rego_test"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | Number of times to repeat the suite (`--count N`). Default is 1. Useful for catching flaky tests. OPA stops at the first repetition that fails, so `repetitions` in the output reports how many actually ran, and each test is listed once carrying its worst outcome across them. | |
| paths | Yes | Test directories or files. `opa test` looks for `*_test.rego` siblings of source files. | |
| 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. | |
| 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. | |
| 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. | |
| verbose | No | Emit per-test pass/fail details. | |
| coverage | No | Add per-line coverage (`coverage`, `coveragePct`) to the test results. The suite runs twice, once for the results and once for coverage. Coverage is left out, with a warning, when a test fails or errors: opa reports none for such a run. | |
| threshold | No | Minimum coverage percentage required (0–100). Returns COVERAGE_BELOW_THRESHOLD when the tests pass but coverage falls below this value. Implies `coverage`. | |
| 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). | |
| runPattern | No | Run only tests whose names match this regular expression (passed as `--run`). | |
| v0Compatible | No | Read the policy as Rego v0 (`--v0-compatible`), the syntax OPA used before 1.0: rules without `if`, partial sets as `deny[msg] { ... }`. Needed for a policy that has not been migrated, which OPA 1.x otherwise refuses to load. Where the tool also takes a query, the query is read as v0 too, with the future keywords imported so `in`, `every` and `some x in` still work in it. | |
| v1Compatible | No | Opt in to OPA v1.0-compatible behaviors (`--v1-compatible`). | |
| 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/**"]`). |