Test Sentinel policies

In the previous tutorials, you learned how to write Sentinel policies, use modules, and incorporate static imports.

In this final tutorial, you will learn how to write comprehensive tests for your Sentinel policies, ensuring they behave correctly under various scenarios.

Create test files

Sentinel has an opinionated folder structure to testing that provides a consistent way to validate and test policies.

Create the directory to test the validate_coffee_order policy. Sentinel expects this directory to be in the test directory and have the same name as the policy.

$ mkdir -p policies/test/validate_coffee_order

You will create three test cases for the validate_coffee_order policy. Notice how there is one passing test and two failing tests, one for each criteria the policy is testing. These test files thoroughly test all the scenarios the policy will enforce.

1. Create a file named pass.hcl in the policy's test directory with the following contents. This file imports the hashicups module and creates mock data that simulates a valid order to test the policy. Notice that test.rules.main is true, this is how Sentinel knows that this is a passing test case.

   policies/test/validate_coffee_order/pass.hcl

   import "module" "hashicups" {
     source = "../../../imports/modules/helper/hashicups.sentinel"
   }
   
   mock "order" {
     data = {
       "items" : [
         {
           "name" : "Vaulatte",
           "size" : "medium"
         },
       ],
     }
   }
   
   test {
     rules = {
       main = true
     }
   }
   

2. Create a file named fail_order_name.hcl in the policy's test directory with the following contents. Notice how the mock data simluates simulates an order with an invalid name. In this test, test.rules.main is set to false, so Sentinel will expect the test case to produce a failing result.

   policies/test/validate_coffee_order/fail_order_name.hcl

   import "module" "hashicups" {
     source = "../../../imports/modules/helper/hashicups.sentinel"
   }
   
   mock "order" {
     data = {
       "items" : [
         {
           "name" : "Cappuccino",
           "size" : "medium"
         },
       ],
     }
   }
   
   test {
     rules = {
       main = false
     }
   }
   

3. Create a file named fail_order_size.hcl in the policy's test directory with the following contents. Notice how the mock data simluates simulates an order with an invalid size. In this test, test.rules.main is set to false, so Sentinel will expect the test case to produce a failing result.

   policies/test/validate_coffee_order/fail_order_size.hcl

   import "module" "hashicups" {
     source = "../../../imports/modules/helper/hashicups.sentinel"
   }
   
   mock "order" {
     data = {
       "items" : [
         {
           "name" : "Vaulatte",
           "size" : "extra-large",
         },
       ],
     }
   }
   
   test {
     rules = {
       main = false
     }
   }
   

Test policy

The sentinel test command tests all cases defined for both policies and reports the results. Unlike the apply command which defaults to Sentinel configuration file, the test command tests against the .sentinel files.

Test the policy by specifying the policies directory.

$ sentinel test policies
PASS - policies/validate_coffee_order.sentinel
  PASS - policies/test/validate_coffee_order/fail_order_name.hcl
  PASS - policies/test/validate_coffee_order/fail_order_size.hcl
  PASS - policies/test/validate_coffee_order/pass.hcl
1 tests completed in 21.644041ms

If you have multiple policies, you can also test a specific policy.

$ sentinel test policies/validate_coffee_order.sentinel
PASS - policies/validate_coffee_order.sentinel
  PASS - policies/test/validate_coffee_order/fail_order_name.hcl
  PASS - policies/test/validate_coffee_order/fail_order_size.hcl
  PASS - policies/test/validate_coffee_order/pass.hcl
1 tests completed in 21.644041ms

Conclusion

In this tutorial, you learned how to write and run tests for your Sentinel policies. It is crucial to thoroughly test your policies to ensure they are robust and reliable. As you develop more complex policies, make sure to maintain and expand your test suite accordingly.

For more information on topics covered in this tutorial, refer to the following documentation:

• Testing Sentinel
• sentinel test command

Next steps

In this series of getting started tutorials, you learned how to write a Sentinel policy, simplify policy logic with functions, use Sentinel modules to share common logic, integrate external data, and test your policies.

Sentinel is designed to work seamlessly with other HashiCorp products. For example, you can use Sentinel to:

• Enforce infrastructure compliance policies with Terraform
• Implement advanced access control policies within Vault
• Create service mesh governance rules within Consul

To continue learning about Sentinel, refer to the following resources:

• Enforce Policy with Sentinel Terraform tutorials
• Sentinel policies Vault tutorials
• Consul and Sentinel documentation
• Sentinel policies Nomad tutorial and Sentinel policy reference for Nomad