`maqpna policy test`

Test a tool call, or a suite of cases, against policies offline or on the live gateway

Govern-o json | yaml

Synopsis#

maqpna policy test --policy FILE|DIR --ns NS --agent A --server S --tool T [--args JSON] [--session S] [--user U] [--expect ACTION]
                   [--group G]... [--scope S]... [--taint LABEL]... [--sink LABEL]... [--at RFC3339] [--explain]
maqpna policy test --gateway URL --tool T ...      (evaluate with the gateway's live policies and session taints)
maqpna policy test DIR|FILE... [-f maqpna-test.yaml] [--require-tests] [-o table|json|junit]   (test suites)

Description#

From the help of maqpna policy:

Policy files: ToolPolicy custom resources (YAML or JSON, several per file, or a List) and the operator-rendered policies.json bundle are both accepted. ToolPolicies are rendered with the operator's own renderer (pkg/policyload), so a test evaluates exactly what the gateway would load. A ToolPolicy that the operator would refuse to publish (bad regex, timezone, Cedar, ...) is an error.

Suite mode: policy test DIR runs every maqpna-test.yaml under DIR (FILE runs that suite). A suite is:

  apiVersion: maqpna.com/v1alpha1
  kind: PolicyTest
  name: coder                      # optional
  policies: [../policies/]         # files or dirs, relative to the suite
  defaults: {namespace: team-a, agent: coder, user: alice@acme.eu}
  cases:                           # one tool call each
    - name: prod writes blocked
      server: kubernetes
      tool: delete
      args: {namespace: prod-eu}
      expect: deny
      expectRule: k8s-no-prod-mutations
  tasks: []                        # optional multi-step tasks (maqpna eval format)

Exit status 3 when a case fails (or, with --require-tests, a policy file is not covered by any suite).

Flags#

Flag	Type	Description	Default
`--agent`	string	agent name	none
`--args`	string	tool arguments as a JSON object	none
`--at`	string	evaluation time for schedules (RFC 3339, e.g. 2026-10-02T17:00:00+02:00)	none
`--expect`	string	expected action (allow\|deny\|require_approval); exit 3 on mismatch	none
`--explain`	switch	print the decision trace (why each policy and rule matched or not)	none
`-f`	string	suite mode: test file name looked up under DIR	`maqpna-test.yaml`
`--gateway`	string	gateway base URL (env MAQPNA_GATEWAY_URL; default: the context's gateway)	none
`--group`	string	principal group (repeatable, comma-separated)	none
`--ns`	string	namespace	none
`--oidc-token-file`	string	file holding an OIDC access token for the admin API (env MAQPNA_OIDC_TOKEN_FILE); wins over `--token`	none
`--policy`	string	policy file or directory: ToolPolicy YAML/JSON or bundle JSON; wins over `--gateway`	none
`--require-tests`	switch	suite mode: fail when DIR has no test file or a policy file no suite uses	none
`--scope`	string	token scope (repeatable, comma-separated)	none
`--server`	string	MCP server	none
`--session`	string	session ID	`dry-run`
`--sink`	string	extra sink label of the tool (repeatable, comma-separated)	none
`--taint`	string	session taint label (repeatable, comma-separated)	none
`--token`	string	static admin token (env MAQPNA_ADMIN_TOKEN; dev/break-glass)	none
`--tool`	string	tool name	none
`--user`	string	user (act.sub)	none

The global flags (--context, -o, --no-color, ...) work with every command.

Examples#

# Would coder be allowed to call github.create_issue?
$ maqpna policy test --policy policies/ --ns team-a --agent coder --server github --tool create_issue
$ maqpna policy test policies/ --require-tests -o junit > policy-tests.xml

What happens when you run it#

Talks to the gateway: --gateway, else MAQPNA_GATEWAY_URL, else the current context's gateway (maqpna context).
Authenticates to the admin API with the token stored by maqpna login, --oidc-token-file, or a static --token (MAQPNA_ADMIN_TOKEN).
Prints a table by default; -o json or -o yaml print the data, and --jq EXPR filters the JSON.

Exit codes#

Code	Meaning
`0`	success
`1`	error (the message says what failed, with a hint when there is one)
`2`	usage error: unknown flag, missing argument or bad value; the synopsis is printed
`3`	a check failed, a change is blocked, or a result did not match (tamper, policy mismatch) (not used by this command)

Terminal demo#

maqpna policy test.cast

maqpna policy test