Test authorization policies
Test an authorization policy change in a controlled environment before you merge the change into production. This page is for developers and platform engineers who add policy tests to a continuous integration and continuous deployment (CI/CD) pipeline. It describes three test layers and the Permit tools for each one.
| Test layer | What it tests | Tool |
|---|---|---|
| Unit tests | The logic of the policy code, without your application | opa test on the policy repository |
| Integration tests | Permission checks against a PDP that runs the policy of a test environment | permit test generate e2e, permit pdp check, your application tests |
| Regression tests | Whether a policy change or a new PDP changes past decisions | permit test run audit |
Unit tests for policy code
Unit tests check the logic of the policy on its own, without your application or a running PDP. Unit tests run fast, so run them on every policy change.
Permit stores the policy of each environment as Rego code in a policy repository. With GitOps, you connect that repository to your own Git provider, and each environment is a branch. Write Rego tests next to the policy code and run them with the Open Policy Agent (OPA) opa test command. The OPA engine loads the policy code directly and runs each test in isolation.
Integration tests against a PDP
Integration tests check that the policy returns the expected decisions when your application sends real permission checks. Run the tests against a policy decision point (PDP) that uses the API key of a test environment, so the PDP syncs the policy and data of that environment.
- Create or copy a test environment. See Copy and merge environments.
- Run a PDP with the API key of the test environment. Use
permit pdp runor see Run the PDP. - Generate test cases and test data with
permit test generate e2e, and generate a Jest, Vitest, or pytest file withpermit test generate code-sample. You can also write tests that callpermit.check()from your application code. - Run the tests against the PDP at
http://localhost:7766.
A passing run means every check returned the decision the test case expects. For a single check, permit pdp check --pdpurl http://localhost:7766 prints ALLOWED or DENIED.
Without --dry-run, permit test generate e2e creates users and data in the environment of your credentials. Run the command without --dry-run only in a test environment, or the test data mixes with production data.
Regression tests from audit logs
Before you move production traffic to a changed policy or a new PDP, run permit test run audit with --pdp-url set to the PDP that runs the changed policy. The command replays recent checks from the audit logs of your environment against that PDP, and lists every decision that differs. When every decision matches, the command prints All decisions match!.
Automate policy tests in CI
Run the tests in your CI/CD pipeline, so every policy change is tested before it reaches production. Combine these steps to fit your pipeline:
- The pipeline creates a test environment with the Create Environment or Copy Environment API, so the test environment matches the target environment. See Manage the policy life cycle with CI/CD.
- The pipeline starts a PDP for the test environment.
- A pull request to the policy branch triggers the unit tests and the integration tests.
- The pipeline merges the test environment into the target environment only when all tests pass. When a test fails, the pipeline stops before the merge.