OPA gives you a high-level declarative language (Rego) to author fine-grained policies that codify important requirements in your system.

To help you verify the correctness of your policies, OPA also gives you a framework that you can use to write tests for your policies. By writing tests for your policies you can speed up the development process of new rules and reduce the amount of time it takes to modify rules as requirements evolve.

Getting Started

Let’s use an example to get started. The file below implements a simple policy that allows new users to be created and users to access their own profile.

example.rego:

  1. package authz
  3. allow {
  4.     input.path == ["users"]
  5.     input.method == "POST"
  6. }
  8. allow {
  9.     input.path == ["users", input.user_id]
  10.     input.method == "GET"
  11. }

To test this policy, we will create a separate Rego file that contains test cases.

example_test.rego:

  1. package authz
  3. test_post_allowed {
  4.     allow with input as {"path": ["users"], "method": "POST"}
  5. }
  7. test_get_anonymous_denied {
  8.     not allow with input as {"path": ["users"], "method": "GET"}
  9. }
  11. test_get_user_allowed {
  12.     allow with input as {"path": ["users", "bob"], "method": "GET", "user_id": "bob"}
  13. }
  15. test_get_another_user_denied {
  16.     not allow with input as {"path": ["users", "bob"], "method": "GET", "user_id": "alice"}
  17. }

Both of these files are saved in the same directory.

  1. $ ls
  2. example.rego      example_test.rego

To exercise the policy, run the opa test command in the directory containing the files.

  1. $ opa test . -v
  2. data.authz.test_post_allowed: PASS (1.417µs)
  3. data.authz.test_get_anonymous_denied: PASS (426ns)
  4. data.authz.test_get_user_allowed: PASS (367ns)
  5. data.authz.test_get_another_user_denied: PASS (320ns)
  6. --------------------------------------------------------------------------------
  7. PASS: 4/4

The opa test output indicates that all of the tests passed.

Try exercising the tests a bit more by removing the first rule in example.rego.

  1. $ opa test . -v
  2. FAILURES
  3. --------------------------------------------------------------------------------
  4. data.authz.test_post_allowed: FAIL (277.306µs)
  6.   query:1                 Enter data.authz.test_post_allowed = _
  7.   example_test.rego:3     | Enter data.authz.test_post_allowed
  8.   example_test.rego:4     | | Fail data.authz.allow with input as {"method": "POST", "path": ["users"]}
  9.   query:1                 | Fail data.authz.test_post_allowed = _
  11. SUMMARY
  12. --------------------------------------------------------------------------------
  13. data.authz.test_post_allowed: FAIL (277.306µs)
  14. data.authz.test_get_anonymous_denied: PASS (124.287µs)
  15. data.authz.test_get_user_allowed: PASS (242.2µs)
  16. data.authz.test_get_another_user_denied: PASS (131.964µs)
  17. --------------------------------------------------------------------------------
  18. PASS: 3/4
  19. FAIL: 1/4

Test Format

Tests are expressed as standard Rego rules with a convention that the rule name is prefixed with test_.

  1. package mypackage
  3. test_some_descriptive_name {
  4.     # test logic
  5. }

Test Discovery

The opa test subcommand runs all of the tests (i.e., rules prefixed with test_) found in Rego files passed on the command line. If directories are passed as command line arguments, opa test will load their file contents recursively.

Specifying Tests to Run

The opa test subcommand supports a --run/-r regex option to further specify which of the discovered tests should be evaluated. The option supports re2 syntax

Test Results

If the test rule is undefined or generates a non-true value the test result is reported as FAIL. If the test encounters a runtime error (e.g., a divide by zero condition) the test result is marked as an ERROR. Tests prefixed with todo_ will be reported as SKIPPED. Otherwise, the test result is marked as PASS.

pass_fail_error_test.rego:

  1. package example
  3. # This test will pass.
  4. test_ok {
  5.     true
  6. }
  8. # This test will fail.
  9. test_failure {
  10.     1 == 2
  11. }
  13. # This test will error.
  14. test_error {
  15.     1 / 0
  16. }
  18. # This test will be skipped.
  19. todo_test_missing_implementation {
  20.     allow with data.roles as ["not", "implemented"]
  21. }

By default, opa test reports the number of tests executed and displays all of the tests that failed or errored.

  1. $ opa test pass_fail_error_test.rego
  2. data.example.test_failure: FAIL (253ns)
  3. data.example.test_error: ERROR (289ns)
  4.   pass_fail_error_test.rego:15: eval_builtin_error: div: divide by zero
  5. --------------------------------------------------------------------------------
  6. PASS: 1/3
  7. FAIL: 1/3
  8. ERROR: 1/3

By default, OPA prints the test results in a human-readable format. If you need to consume the test results programmatically, use the JSON output format.

  1. opa test --format=json pass_fail_error_test.rego
  1. [
  2.   {
  3.     "location": {
  4.       "file": "pass_fail_error_test.rego",
  5.       "row": 4,
  6.       "col": 1
  7.     },
  8.     "package": "data.example",
  9.     "name": "test_ok",
  10.     "duration": 618515
  11.   },
  12.   {
  13.     "location": {
  14.       "file": "pass_fail_error_test.rego",
  15.       "row": 9,
  16.       "col": 1
  17.     },
  18.     "package": "data.example",
  19.     "name": "test_failure",
  20.     "fail": true,
  21.     "duration": 322177
  22.   },
  23.   {
  24.     "location": {
  25.       "file": "pass_fail_error_test.rego",
  26.       "row": 14,
  27.       "col": 1
  28.     },
  29.     "package": "data.example",
  30.     "name": "test_error",
  31.     "error": {
  32.       "code": "eval_internal_error",
  33.       "message": "div: divide by zero",
  34.       "location": {
  35.         "file": "pass_fail_error_test.rego",
  36.         "row": 15,
  37.         "col": 5
  38.       }
  39.     },
  40.     "duration": 345148
  41.   }
  42. ]

Data and Function Mocking

OPA’s with keyword can be used to replace the data document or called functions with mocks. Both base and virtual documents can be replaced.

When replacing functions, built-in or otherwise, the following constraints are in place:

  1. Replacing internal.* functions, or rego.metadata.*, or eq; or relations (walk) is not allowed.
  2. Replacement and replaced function need to have the same arity.
  3. Replaced functions can call the functions they’re replacing, and those calls will call out to the original function, and not cause recursion.

Below is a simple policy that depends on the data document.

authz.rego:

  1. package authz
  2. import future.keywords.in
  4. allow {
  5.     some x in data.policies
  6.     x.name == "test_policy"
  7.     matches_role(input.role)
  8. }
  10. matches_role(my_role) {
  11.     input.user in data.roles[my_role]
  12. }

Below is the Rego file to test the above policy.

authz_test.rego:

  1. package authz
  3. policies := [{"name": "test_policy"}]
  4. roles := {"admin": ["alice"]}
  6. test_allow_with_data {
  7.     allow with input as {"user": "alice", "role": "admin"}
  8.       with data.policies as policies
  9.       with data.roles as roles
  10. }

To exercise the policy, run the opa test command.

  1. $ opa test -v authz.rego authz_test.rego
  2. data.authz.test_allow_with_data: PASS (697ns)
  3. --------------------------------------------------------------------------------
  4. PASS: 1/1

Below is an example to replace a rule without arguments.

authz.rego:

  1. package authz
  3. allow1 {
  4.     allow2
  5. }
  7. allow2 {
  8.     2 == 1
  9. }

authz_test.rego:

  1. package authz
  3. test_replace_rule {
  4.     allow1 with allow2 as true
  5. }
  1. $  opa test -v authz.rego authz_test.rego
  2. data.authz.test_replace_rule: PASS (328ns)
  3. --------------------------------------------------------------------------------
  4. PASS: 1/1

Here is an example to replace a rule’s built-in function with a user-defined function.

authz.rego:

  1. package authz
  3. import data.jwks.cert
  5. allow {
  6.     [true, _, _] = io.jwt.decode_verify(input.headers["x-token"], {"cert": cert, "iss": "corp.issuer.com"})
  7. }

authz_test.rego:

  1. package authz
  3. mock_decode_verify("my-jwt", _) := [true, {}, {}]
  4. mock_decode_verify(x, _) := [false, {}, {}] {
  5.     x != "my-jwt"
  6. }
  8. test_allow {
  9.     allow
  10.       with input.headers["x-token"] as "my-jwt"
  11.       with data.jwks.cert as "mock-cert"
  12.       with io.jwt.decode_verify as mock_decode_verify
  13. }
  1. $  opa test -v authz.rego authz_test.rego
  2. data.authz.test_allow: PASS (458.752µs)
  3. --------------------------------------------------------------------------------
  4. PASS: 1/1

In simple cases, a function can also be replaced with a value, as in

  1. test_allow_value {
  2.     allow
  3.       with input.headers["x-token"] as "my-jwt"
  4.       with data.jwks.cert as "mock-cert"
  5.       with io.jwt.decode_verify as [true, {}, {}]
  6. }

Every invocation of the function will then return the replacement value, regardless of the function’s arguments.

Note that it’s also possible to replace one built-in function by another; or a non-built-in function by a built-in function.

authz.rego:

  1. package authz
  3. replace_rule {
  4.     replace(input.label)
  5. }
  7. replace(label) {
  8.     label == "test_label"
  9. }

authz_test.rego:

  1. package authz
  3. test_replace_rule {
  4.     replace_rule with input.label as "does-not-matter" with replace as true
  5. }
  1. $ opa test -v authz.rego authz_test.rego
  2. data.authz.test_replace_rule: PASS (648.314µs)
  3. --------------------------------------------------------------------------------
  4. PASS: 1/1

Coverage

In addition to reporting pass, fail, and error results for tests, opa test can also report coverage for the policies under test.

The coverage report includes all of the lines evaluated and not evaluated in the Rego files provided on the command line. When a line is not covered it indicates one of two things:

  • If the line refers to the head of a rule, the body of the rule was never true.
  • If the line refers to an expression in a rule, the expression was never evaluated.

It is also possible that rule indexing has determined some path unnecessary for evaluation, thereby affecting the lines reported as covered.

If we run the coverage report on the original example.rego file without test_get_user_allowed from example_test.rego the report will indicate that line 8 is not covered.

  1. opa test --coverage --format=json example.rego example_test.rego
  1. {
  2.   "files": {
  3.     "example.rego": {
  4.       "covered": [
  5.         {
  6.           "start": {
  7.             "row": 3
  8.           },
  9.           "end": {
  10.             "row": 5
  11.           }
  12.         },
  13.         {
  14.           "start": {
  15.             "row": 9
  16.           },
  17.           "end": {
  18.             "row": 11
  19.           }
  20.         }
  21.       ],
  22.       "not_covered": [
  23.         {
  24.           "start": {
  25.             "row": 8
  26.           },
  27.           "end": {
  28.             "row": 8
  29.           }
  30.         }
  31.       ]
  32.     },
  33.     "example_test.rego": {
  34.       "covered": [
  35.         {
  36.           "start": {
  37.             "row": 3
  38.           },
  39.           "end": {
  40.             "row": 4
  41.           }
  42.         },
  43.         {
  44.           "start": {
  45.             "row": 7
  46.           },
  47.           "end": {
  48.             "row": 8
  49.           }
  50.         },
  51.         {
  52.           "start": {
  53.             "row": 11
  54.           },
  55.           "end": {
  56.             "row": 12
  57.           }
  58.         }
  59.       ]
  60.     }
  61.   }
  62. }