Test Sentinel Policies

Testing Sentinel policies with the built-in testing suite ensures that you account for all possible behaviors in your policy, and that Sentinel operates as expected when Terraform Cloud applies these policies within your organization.

Writing tests gives you confidence in your policy because you accounted for failures in your development process.

»Create passing mock data

Although your policy passes in the Sentinel CLI, you need to also write an explicit passing test. Copy your known passing mock data to a new file with "pass" in the filename.

$ cp mock-tfplan-v2.sentinel mock-tfplan-pass-v2.sentinel

»Write a passing test case

In the passing case file, supply Sentinel the path to the passing mock data you created, which ensures the main rule will evaluate it as true.

Create a new folder called test and a subfolder for the policy name restrict-s3-buckets. Sentinel requires your folder structure match test/<policy>/*.json where <policy> is the name of your policy file without the file extension.

$ mkdir -p ~/learn-sentinel-policies/test/restrict-s3-buckets && cd $_

Create a new file at ./test/restrict-s3-buckets/pass.json. Copy and paste the contents below and save the file.

{
  "mock": {
    "tfplan/v2": "../../mock-tfplan-pass-v2.sentinel"
  },
  "test": {
    "main": true
  }
}

»Create failing mock data

To write a failing test case, you need to create a mock import data file with values outside of your criteria, to simulate infrastructure that doesn’t comply with the policy. Copy the mock-tfplan-v2.sentinel file to a new file with "fail" in the filename.

$ cp mock-tfplan-v2.sentinel mock-tfplan-fail-v2.sentinel

Open the failing mock data file in your text editor and look for the resource_changes collection.

Edit the value for resource_changes.aws_s3_bucket.demo.change.after.acl to public-read-write.

resource_changes = {
    "aws_s3_bucket.demo": {
        "address":  "aws_s3_bucket.demo",
        "change": {
            "actions": [
                "create",
            ],
            "after": {
-               "acl":  "public-read",
+               "acl":  "public-read-write",

Remove the identifiers for resource_changes.aws_s3_bucket.demo.change.after.tags, Name & Environment and replace the value of the "Name" and "Environment" tags with "NotName" and "NotEnvironment" and save your changes in your `learn-sentinel-policies' directory.

resource_changes = {
    "aws_s3_bucket.demo": {
        "address": "aws_s3_bucket.demo",
        "change": {
            "actions": [
                "create",
            ],
            "after": {
##...
-               "tags": {
-                   "Name": "HashiCorp",
-                   "Environment: "Learn"
-               },
+               "tags": {
+                   "NotName": "HashiCorp",
+                   "NotEnvironment: "Learn"
+               },

»Write a failing test case

Sentinel requires passing and failing test files in a test directory, under a subdirectory for the policy file name. In the failing case file, supply Sentinel the path to the failing mock data you created.

Create a new file called fail.json in the test/restrict-s3-buckets directory. Copy and paste the contents below and save the file.

{
  "mock": {
    "tfplan/v2": "../../mock-tfplan-fail-v2.sentinel"
  },
  "test": {
    "main": false
  }
}

»Test your policy in the Sentinel CLI

You created passing and failing mock import data to mimic scenarios in which your policy should pass or fail. Sentinel validates these with the test command. Change into your root policy directory.

$ cd ~/learn-sentinel-policies

Test the sentinel policy providing the policy file. Sentinel will automatically find the test cases in the /test directory and the subdirectory that matches the policy name.

$ sentinel test restrict-s3-buckets.sentinel

Both your passing and failing tests will return PASS because the scenario for success validated to true and the scenario for failure validated to false - the expected values from the test cases.

To see more information about the test data, add the -verbose flag in your command.

$ sentinel test -verbose restrict-s3-buckets.sentinel

The -verbose flag returns the steps at which each test passes or fails your criteria.

»Check your policy and tests into source control

Create a new repository on GitHub called learn-sentinel-policies. To avoid errors, do not initialize the new repository with README, license, or gitignore files. You can add these files after you push your project to GitHub.

Remove your mock data files from your local repository.

$ rm mock-tfconfig.sentinel mock-tfplan-pass-v2.sentinel mock-tfrun.sentinel mock-tfconfig-v2.sentinel mock-tfplan.sentinel mock-tfstate.sentinel mock-tfplan-fail-v2.sentinel mock-tfplan-v2.sentinel mock-tfstate-v2.sentinel sentinel.json

Initialize your local directory as a git repo.

$ git init

Add the tests and policy to your new repository.

$ git add .

Commit with an initial upload message.

$ git commit -m "Initial upload"

Add your new repository to your local repository and validate your new remote repository link.

$ git remote add origin https://github.com/<YOUR-GITHUB-USERNAME>/learn-sentinel-policies && git remote -v

Push your policy and tests to your remote repository.

$ git push -u origin master

»Next steps

You created test policies and ran test cases with the Sentinel CLI. In the following guide, you will upload your tested policies to your Terraform Cloud organization.