Skip to main content
Glama
OrygnsCode

opa-mcp-server

by OrygnsCode
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript
Local

Run Rego tests

rego_test

Run Rego unit tests and get pass/fail/skip/error counts, per-test records, coverage thresholds, and detailed traces to debug policy failures.

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

TableJSON Schema
NameRequiredDescriptionDefault
countNoNumber 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.
pathsYesTest directories or files. `opa test` looks for `*_test.rego` siblings of source files.
bundleNoLoad 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.
explainNoAdd 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.
timeoutNoPer-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.
verboseNoEmit per-test pass/fail details.
coverageNoInclude per-line coverage data. Switches output to coverage-report mode: test record counts are not available, but `coverage` and `coveragePct` fields are populated.
thresholdNoMinimum coverage percentage required (0–100). Returns COVERAGE_BELOW_THRESHOLD when actual coverage falls below this value. Implicitly enables coverage-report output mode.
varValuesNoInclude 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).
runPatternNoRun only tests whose names match this regular expression (passed as `--run`).
v1CompatibleNoOpt in to OPA v1.0-compatible behaviors (`--v1-compatible`).
ignorePatternsNoGlob 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/**"]`).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.5.0
    • changedInput schema / properties / count / description
      Previous value: -"Number of times to repeat each test (`--count N`). Default is 1. Useful for measuring repeatability or catching flaky tests under load."New value: +"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."
  2. Changed2 schema fields changedv0.1.20
    • addedInput schema / properties / explain
      Added value: +{
+  "description": "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.",
+  "enum": [
+    "fails",
+    "full",
+    "notes",
+    "debug"
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / v1Compatible
      Added value: +{
+  "description": "Opt in to OPA v1.0-compatible behaviors (`--v1-compatible`).",
+  "type": "boolean"
+}
  3. Changed4 schema fields changedv0.1.17
    • addedInput schema / properties / bundle
      Added value: +{
+  "description": "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.",
+  "type": "boolean"
+}
    • addedInput schema / properties / count
      Added value: +{
+  "description": "Number of times to repeat each test (`--count N`). Default is 1. Useful for measuring repeatability or catching flaky tests under load.",
+  "minimum": 1,
+  "type": "integer"
+}
    • addedInput schema / properties / ignorePatterns
      Added value: +{
+  "description": "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/**\"]`).",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • addedInput schema / properties / timeout
      Added value: +{
+  "description": "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.",
+  "type": "string"
+}
  4. Addedv0.1.13
  5. Removedv0.1.5
  6. Addedv0.1.2
  7. Removedv0.1.1
  8. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes far beyond the sparse annotations (readOnlyHint: false, openWorldHint: true). It discloses subtle OPA behaviors: `errored` tests are neither passes nor failures and any one fails the suite; `test_`-prefixed rules and `*_test.rego` files are auto-discovered; the `test_x[case]` parameterized form collapses to one reported test unless `parameterizedGroups`/`caseCounts` are inspected; and enabling `coverage`/`threshold` switches output mode, disabling per-test counts. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

At roughly 230 words for a 12-parameter tool with no output schema, the length is justified and the core purpose is front-loaded. The downside is a single dense paragraph with no bullet or section structure, making the parameter guidance harder to scan, though every sentence carries real information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Because there is no output schema, the description carries the full burden of explaining return behavior, and it delivers: aggregate counts, errored semantics, COVERAGE_BELOW_THRESHOLD, coverage/coveragePct fields, trace population, parameterizedGroups/caseCounts, and the no-match error hint. Combined with 100% schema coverage on the input side, an agent has everything needed to invoke and interpret this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3; the description earns extra credit by adding cross-parameter and output-mode knowledge beyond the schema: `varValues` only matters with `verbose: true`, `threshold` implicitly enables coverage-report mode, and coverage mode disables per-test counts. It does not restate every parameter (count, explain, v1Compatible are left to the schema), which is acceptable given the schema's thoroughness.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a precise verb+resource pair ('Run Rego unit tests') and names the underlying implementation (`opa test`), plus the return shape (aggregate pass/fail/skip/error counts and per-test records). This distinguishes it from sibling tools like rego_bench (benchmarking), rego_check (static analysis), and conftest_test (Conftest tests).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides rich contextual guidance for when to use its options: `bundle: true` for bundle-structured directories, `threshold` for coverage gating, `timeout` for tests exceeding OPA's 5s default, and `ignorePatterns` for generated/fixture files. However, it never explicitly routes to or excludes sibling alternatives (e.g., rego_test_multiroot for multiple roots, rego_bench for performance runs), so tool selection must be inferred from the purpose statement.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Other Tools