Testing policies

This documentation is for an as-yet unreleased version of Cerbos. Choose 0.40.0 from the version picker at the top right or navigate to https://docs.cerbos.dev for the latest version.

The policies for this section can be found on GitHub.

Cerbos allows you to write tests for policies and run them as part of the compilation stage to make sure that the policies do exactly what you expect. This saves the manual effort of running example requests over and over to ensure the policy logic is as you expect.

A test suite defines a number of resources and principals and the expected result of actions for any combination of them.

To define a test suite, create a tests folder alongside your policy folder. In this folder, any number of tests can be defined as YAML but the file must end with _test.

As an example, the contact policy states that a user can create, read and update a contact, but only an admin can delete them - therefore you can create a test suite for this like the below:

---
name: ContactTestSuite
description: Tests for verifying the contact resource policy

principals:
  admin:
    id: admin
    roles:
      - admin

  user:
    id: user
    roles:
      - user

resources:
  contact:
    kind: contact
    id: contact

tests:
  - name: Contact CRUD Actions
    input:
      principals:
        - admin
        - user

      resources:
        - contact

      actions:
        - create
        - read
        - update
        - delete

    expected:
      - principal: admin
        resource: contact
        actions:
          create: EFFECT_ALLOW
          read: EFFECT_ALLOW
          update: EFFECT_ALLOW
          delete: EFFECT_ALLOW

      - principal: user
        resource: contact
        actions:
          create: EFFECT_ALLOW
          read: EFFECT_ALLOW
          update: EFFECT_ALLOW
          delete: EFFECT_DENY

With this defined, you can now extend the compile command to also run the tests for example:

# Using Container
docker run --rm --name cerbos -t \
  -v /tutorial:/tutorial \
  -p 3592:3592 \
  ghcr.io/cerbos/cerbos:latest compile --tests=/tutorial/tests /tutorial/policies

# Using Binary
./cerbos compile --tests=/tutorial/tests /tutorial/policies

If everything is as expected the output of the tests should be green:

Test results
= ContactTestSuite (contact_test.yaml)
== 'Contact CRUD Actions' for resource 'contact_test' by principal 'user' [OK]
== 'Contact CRUD Actions' for resource 'contact_test' by principal 'admin' [OK]

Full testing documentation can be found here.