Policy testing commands in the Permit CLI

Test your policy from the terminal with the permit test commands. This reference is for developers who change a policy or deploy a new policy decision point (PDP) and want to confirm that permission decisions stay correct.

Before you use these commands, install the Permit CLI and sign in with permit login. See Install and use the Permit CLI. Each command also accepts --api-key instead of the stored credentials.

permit test run audit

permit test run audit reads recent decisions from your environment's audit logs, sends the same permission checks to a PDP, and compares the results. Use it to confirm that a policy change or a new PDP makes the same decisions as the PDP that wrote the audit logs.

Flag	Alias	Default	Description
--pdp-url <string>	-p	http://localhost:7766	The URL of the PDP to run the checks against.
--time-frame <number>	-t	24	The number of hours of audit logs to read, from 6 to 72.
--source-pdp <string>	-s	All PDPs	The ID of the PDP whose audit logs to read.
--users <string...>	-u	All users	The user keys to read audit logs for. Accepts several values.
--resources <string...>	-r	All resources	The resources to read audit logs for. Accepts several values.
--tenant <string>		All tenants	The tenant to read audit logs for.
--action <string>	-a	All actions	The action to read audit logs for.
--decision <allow | deny>	-d	Both	The decision to read audit logs for.
--max-logs <number>	-m	1000	The maximum number of audit log entries to process.
--api-key <string>		Stored credentials	The API key of the environment.

The command prints the number of matches and differences. For each difference, the command lists the check and both decisions. When every decision matches, the command prints All decisions match!.

Compare the last 24 hours of decisions with a PDP on your machine:

$ permit test run audit --pdp-url http://localhost:7766

Compare 48 hours of allowed read decisions with a PDP at a custom URL:

$ permit test run audit --pdp-url http://my-pdp.example.com:7766 --time-frame 48 --action read --decision allow

Compare the decisions of two users on two resources:

$ permit test run audit --users john@example.com alice@example.com --resources document:123 folder:456

Compare at most 500 decisions:

$ permit test run audit --max-logs 500

To load test a PDP with the traffic from your audit logs instead of comparing decisions, use the Audit Log Replay API.

Generate end-to-end tests

The permit test generate commands create test cases from your policy, and a test file that runs them in your test framework.

permit test generate e2e

permit test generate e2e generates end-to-end test cases for your policy. The test cases are permission checks with the decision the policy should return. Without --dry-run, the command also creates the test users and data in your Permit environment.

Use --dry-run outside a test environment

Without --dry-run, permit test generate e2e creates users and data in the environment you signed in to. Run the command without --dry-run only in an environment that holds test data.

Flag	Default	Description
--models <string...>	RBAC	The policy models to generate test cases for.
--path <string>	None	The path of the JSON file to save the test configuration to. Saving the file is recommended.
--dry-run	false	Generates the test cases without creating data in Permit.
--snippet <jest | pytest | vitest>	None	Also generates a test file for this framework that runs the test cases.
--api-key <string>	Stored credentials	The API key of the environment.

Generate test cases for the role-based access control (RBAC) model, create the test data, and save the configuration to logb.json:

  $ permit test generate e2e --models=RBAC --path=logb.json

Generate the same test cases and configuration file without creating data in Permit:

  $ permit test generate e2e --models=RBAC --path=logb.json --dry-run

Generate test cases without creating data or saving a file. The command prints the test cases to the terminal:

  $ permit test generate e2e --models=RBAC --dry-run

Generate test cases and create the test data without saving a file:

  $ permit test generate e2e --models=RBAC

permit test generate code-sample

permit test generate code-sample generates a test file that reads a saved test configuration, runs each check against a PDP, and asserts the expected decision.

Flag	Required	Default	Description
--framework <jest | pytest | vitest>	Yes		The test framework of the generated file.
--config-path <string>	No	authz-test.json	The path of the test configuration that permit test generate e2e --path saved.
--path <string>	No	None	The path to save the generated test file to.
--pdp-url <string>	No	http://localhost:7766	The PDP that the tests send checks to.
--api-key <string>	No	Stored credentials	The API key of the environment.

Without --path, the command prints the test file to the terminal.

The generated test file contains your API key

The command writes the environment API key into the test file as a string. Anyone who reads the file can change that environment's policy through the Permit API. Replace the key with an environment variable before you commit the file.

Related pages

• Replay audit logs against a PDP
• Run a PDP container with the Permit CLI
• View and filter audit logs
• Permit CLI command index