# Validating and testing policies

|     |     |
| --- | --- |
|  | This documentation is for<br>a previous<br>version of Cerbos. Choose 0.53.0 from the version picker at the top right or navigate to [https://docs.cerbos.dev](https://docs.cerbos.dev/) for the latest version. |

## Validating policies

You can use the Cerbos compiler to make sure that your policies are valid before pushing them to a production Cerbos instance. We recommend setting up a git hook or a CI step to run the Cerbos compiler before you push any policy changes to production.

```sh
docker run -i -t -v /path/to/policy/dir:/policies ghcr.io/cerbos/cerbos:0.39.0 compile /policies
```

## Testing policies

You can write optional tests for policies and run them as part of the compilation stage to make sure that the policies do exactly what you expect.

Tests are defined using the familiar YAML format as well. A test file must have `_test` suffix in the name and one of the following file extensions: `yaml`, `yml`, or `json`. For example, `album_test.yml`, `album_test.yaml` or `album_test.json`.

Test suite definition

```yaml
---
name: AlbumObjectTestSuite (1)
description: Tests for verifying the album:object resource policy (2)
options:
  now: "2022-08-02T15:00:00Z" (3)
  lenientScopeSearch: true (4)
  globals: (5)
    my_global_var: foo
principals: (6)
  alicia:
    id: aliciaID
    roles:
      - user
  bradley:
    id: bradleyID
    roles:
      - user
resources: (7)
  alicia_album:
    id: XX125
    kind: album:object
    policyVersion: default
    attr:
      owner: aliciaID
      public: false
      flagged: false
  bradley_album:
    id: XX250
    kind: album:object
    policyVersion: staging
    attr:
      owner: bradleyID
      public: false
      flagged: false
auxData: (8)
  validJWT:
    jwt:
      iss: my.domain
      aud: ["x", "y"]
      myField: value
tests: (9)
  - name: Accessing an album (10)
    options:
      now: "2022-08-03T15:00:00Z" (11)
      lenientScopeSearch: false (12)
      globals: (13)
        my_global_var: bar
    input: (14)
      principals: (15)
        - alicia
        - bradley
      resources: (16)
        - alicia_album
        - bradley_album
      actions: (17)
        - view
        - delete
      auxData: validJWT (18)
    expected: (19)
      - principal: alicia (20)
        resource: alicia_album (21)
        actions: (22)
          view: EFFECT_ALLOW
          delete: EFFECT_ALLOW
        outputs: (23)
          - action: view (24)
            expected: (25)
              - src: resource.album.vdefault#view-rule
                val:
                  key1: value1
                  key2: ["value2", "value3"]
              - src: resource.album.vdefault#token-lifetime
                val: 1h
      - principal: bradley
        resource: bradley_album
        actions:
          view: EFFECT_ALLOW
          delete: EFFECT_ALLOW
```

### Sharing test fixtures

It is possible to share principals, resources and auxData blocks between test suites stored in the same directory. Create a `testdata` directory in the directory containing your test suite files, then define shared resources, principals and auxData in `testdata/resources.yml`, `testdata/principals.yml`, `testdata/auxdata.yml` respectively (`yaml` and `json` extensions are also supported).

```
tests
├── album_object_test.yaml
├── gallery_object_test.yaml
├── slideshow_object_test.yaml
└── testdata
   ├── auxdata.yaml
   ├── principals.yaml
   └── resources.yaml
```

An example of `testdata/principals.yml`

```yaml
---
principals:
  john:
    id: johnID
    roles:
      - user
      - moderator
```

An example of `testdata/resources.yml`

```yaml
---
resources:
  alicia_album:
    id: XX125
    kind: "album:object"
    attr:
      owner: aliciaID
      public: false
      flagged: false
```

An example of `testdata/auxdata.yml`

```yaml
---
auxData:
  validJWT:
    jwt:
      iss: my.domain
      aud: ["x", "y"]
      myField: value
```

|  | [YAML anchors and overrides](https://www.educative.io/blog/advanced-yaml-syntax-cheatsheet#anchors) are a great way to reduce repetition and reuse definitions in test cases.

## Running tests

The `compile` command automatically discovers test files in the policy repository.

```sh
docker run -i -t \
    -v /path/to/policy/dir:/policies \
    ghcr.io/cerbos/cerbos:0.39.0 compile /policies
```

The output format can be controlled using the `--output` flag, which accepts the values `tree` (default), `list` and `json`. The `--color` flag controls the coloring of the output. To produce machine readable output from the tests, pass `--output=json --color=never` to the command.

By default, all discovered tests are run. Use the `--skip-tests` flag to skip all tests or use the `--run` flag to run a set of tests that match a regular expression.

Example: Running only tests that contain 'Delete' in the name

```sh
docker run -i -t \
    -v /path/to/policy/dir:/policies \
    ghcr.io/cerbos/cerbos:0.39.0 compile --run=Delete /policies
```