A node.js based helper for unit testing (AWS) Terraform.
What is Terraunit?
The goal of Terraunit it so enable a really fast, totally local unit testing feedback loop while developing Terraform modules. It is intended to complement integration tests, rather than replace them.
At its core, it is just a simple local mock AWS API and a set of scripts for getting your module to talk to them. You can instantiate your module, run a plan, and then look for expected resources in that plan. With this approach, you can run through many configurations in a few seconds and catch many classes of errors faster than going through a full test cycle.
It is currently written in node.js with the intention of integrating with Jest. This is mostly of out convenience and might change in future versions.
$ npm install terraunit --save-dev
You can write a basic test that invokes a module you've been developing:
//importconst Terraunit = ;const terraunit = ;//plans can take time when fetching resourcesjest;//start and stop the mock aws service;;//write a test;
Typical project folder structure:
. |-- __tests__ | |-- main.test.js |-- main.tf |-- outputs.tf |-- variables.tf |-- package.json
The constructor takes an (optional) object with the following structure:
const options =//the port to run on, defaults to 9999port: 9999//additional AWS API mock responsesmockAwsResponses:id: 'sts:AssumeRole'statusCode: 200body: '<...>'//debug mode to start with (see Debugging section), defaults to LOCAL modedebugMode: 'LOCAL'
The plan method takes an object with the following structure:
const options =//the root workspace directory, defaults to cwdworkingDirectory: process//an array of terraform configuration objectsconfigurations://raw terraform configuration datacontent: `...`//the filename to store the config in// defaults to main.tffileName: 'main.tf'//this configuration is a mock provider// will override content with a mock provider of the given type (only aws at this point)mockProviderType: 'aws'//add an alias to this mock provider// defaults to no aliasmockProviderAlias: ''
I can override the providers in my module:
You can configure the debug mode by passing the debugMode argument into the Terraform constructor options. You can also override this by setting the
TERRAUNIT_DEBUG environment variable.
It supports the following options:
- ALL - Will run in all environments
- LOCAL - Will only run locally
- CI - Will run only during CI
- OFF - Will not run
Debugging will print all terraform command output and API call information to the console.
- Add mock API responses as needed.
- Add additional methods for searching and filtering through the plan.
- Possibly switch to Go to fit better with the Terraform ecosystem.
Clone the repo:
$ git clone firstname.lastname@example.org:jdhornsby/terraunit.git$ cd terraunit$ npm install$ npm run test
Add your features. Add you test. Send a PR!