Skip to main content

Tests

Topaz makes it easy to define and run a set of test cases known as assertions, to help test the model and prove that it authorizes correctly.

Defining assertions​

Assertions are managed in a JSON file, by default named assertions.json.

topaz test template emits a skeleton assertions file to stdout.

Example:

topaz test template
{
  "assertions": [
    {"check": {"object_type": "", "object_id": "", "relation": "", "subject_type": "", "subject_id": ""}, "expected": true},
    {"check_relation": {"object_type": "", "object_id": "", "relation": "", "subject_type": "", "subject_id": ""}, "expected": true},
    {"check_permission": {"object_type": "", "object_id": "", "permission": "", "subject_type": "", "subject_id": ""}, "expected": true},
    {"check_decision": {"identity_context": {"identity": "", "type": ""}, "resource_context": {}, "policy_context": {"path": "", "decisions": [""]}}, "expected":true},
  ]
}

There are two types of assertions:

  • check: define a test case that checks whether a relation (or permission) exists between an object (identified by object_type and object_id) and a subject (identified by subject_type, subject_id, and optionally subject_relation).
  • check_decision: define a test case that executes the authorizer is API over the given identity_context, resource_context, and policy_context

Both types of assertions also include an expected key, which can be either true or false depending on whether the check is supposed to succeed or fail.

note

The check_relation and check_permission are shown for backward-compatibility but are no longer used.

Running assertions​

topaz test exec executes the assertions in a JSON file of the proper format, defaulting to ./assertions.json. To specify a different file name, use the filename argument.

Example:

  1. Create the following assertions.json file, which defines a set of test cases for the data in the todo template:
{
    "assertions": [
        {"check":{"subject_type":"user","subject_id":"rick@the-citadel.com","relation":"member","object_type":"group","object_id":"admin"},"expected":true},
        {"check":{"subject_type":"user","subject_id":"rick@the-citadel.com","relation":"member","object_type":"group","object_id":"evil_genius"},"expected":true},
        {"check":{"subject_type":"user","subject_id":"rick@the-citadel.com","relation":"member","object_type":"group","object_id":"editor"},"expected":false},
        {"check":{"subject_type":"user","subject_id":"rick@the-citadel.com","relation":"member","object_type":"group","object_id":"viewer"},"expected":false},

        {"check":{"subject_type":"user","subject_id":"morty@the-citadel.com","relation":"member","object_type":"group","object_id":"admin"},"expected":false},
        {"check":{"subject_type":"user","subject_id":"morty@the-citadel.com","relation":"member","object_type":"group","object_id":"evil_genius"},"expected":false},
        {"check":{"subject_type":"user","subject_id":"morty@the-citadel.com","relation":"member","object_type":"group","object_id":"editor"},"expected":true},
        {"check":{"subject_type":"user","subject_id":"morty@the-citadel.com","relation":"member","object_type":"group","object_id":"viewer"},"expected":false},
        
        {"check":{"subject_type":"user","subject_id":"summer@the-smiths.com","relation":"member","object_type":"group","object_id":"admin"},"expected":false},
        {"check":{"subject_type":"user","subject_id":"summer@the-smiths.com","relation":"member","object_type":"group","object_id":"evil_genius"},"expected":false},
        {"check":{"subject_type":"user","subject_id":"summer@the-smiths.com","relation":"member","object_type":"group","object_id":"editor"},"expected":true},
        {"check":{"subject_type":"user","subject_id":"summer@the-smiths.com","relation":"member","object_type":"group","object_id":"viewer"},"expected":false},

        {"check":{"subject_type":"user","subject_id":"beth@the-smiths.com","relation":"member","object_type":"group","object_id":"admin"},"expected":false},
        {"check":{"subject_type":"user","subject_id":"beth@the-smiths.com","relation":"member","object_type":"group","object_id":"evil_genius"},"expected":false},
        {"check":{"subject_type":"user","subject_id":"beth@the-smiths.com","relation":"member","object_type":"group","object_id":"editor"},"expected":false},
        {"check":{"subject_type":"user","subject_id":"beth@the-smiths.com","relation":"member","object_type":"group","object_id":"viewer"},"expected":true},

        {"check":{"subject_type":"user","subject_id":"jerry@the-smiths.com","relation":"member","object_type":"group","object_id":"admin"},"expected":false},
        {"check":{"subject_type":"user","subject_id":"jerry@the-smiths.com","relation":"member","object_type":"group","object_id":"evil_genius"},"expected":false},
        {"check":{"subject_type":"user","subject_id":"jerry@the-smiths.com","relation":"member","object_type":"group","object_id":"editor"},"expected":false},
        {"check":{"subject_type":"user","subject_id":"jerry@the-smiths.com","relation":"member","object_type":"group","object_id":"viewer"},"expected":true},
    ]
}
  1. Run the test suite:
topaz test exec -i
0001 check            PASS  group:admin#member@user:rick@the-citadel.com [true] (2.764667ms)
0002 check            PASS  group:evil_genius#member@user:rick@the-citadel.com [true] (1.545541ms)
0003 check            PASS  group:editor#member@user:rick@the-citadel.com [false] (1.665166ms)
0004 check            PASS  group:viewer#member@user:rick@the-citadel.com [false] (1.583125ms)
0005 check            PASS  group:admin#member@user:morty@the-citadel.com [false] (1.369542ms)
0006 check            PASS  group:evil_genius#member@user:morty@the-citadel.com [false] (1.399875ms)
0007 check            PASS  group:editor#member@user:morty@the-citadel.com [true] (1.297292ms)
0008 check            PASS  group:viewer#member@user:morty@the-citadel.com [false] (1.375917ms)
0009 check            PASS  group:admin#member@user:summer@the-smiths.com [false] (1.498042ms)
0010 check            PASS  group:evil_genius#member@user:summer@the-smiths.com [false] (1.34ms)
0011 check            PASS  group:editor#member@user:summer@the-smiths.com [true] (1.349875ms)
0012 check            PASS  group:viewer#member@user:summer@the-smiths.com [false] (1.328584ms)
0013 check            PASS  group:admin#member@user:beth@the-smiths.com [false] (1.364667ms)
0014 check            PASS  group:evil_genius#member@user:beth@the-smiths.com [false] (1.412834ms)
0015 check            PASS  group:editor#member@user:beth@the-smiths.com [false] (1.781375ms)
0016 check            PASS  group:viewer#member@user:beth@the-smiths.com [true] (1.782375ms)
0017 check            PASS  group:admin#member@user:jerry@the-smiths.com [false] (1.790791ms)
0018 check            PASS  group:evil_genius#member@user:jerry@the-smiths.com [false] (1.44825ms)
0019 check            PASS  group:editor#member@user:jerry@the-smiths.com [false] (1.366709ms)
0020 check            PASS  group:viewer#member@user:jerry@the-smiths.com [true] (1.349167ms)