Tests

This directory contains a number of automated tests that cover the functionality of the modules that ship with this repository.

Introduction

We are using Terratest for automated tests that are located in the test/ directory. Terratest deploys real infrastructure (e.g., servers) in a real environment (e.g., AWS).

The basic usage pattern for writing automated tests with Terratest is to:

Write tests using Go's built-in package testing: you create a file ending in _test.go and run tests with the go test command.
Use Terratest to execute your real IaC tools (e.g., Terraform, Packer, etc.) to deploy real infrastructure (e.g., servers) in a real environment (e.g., AWS).
Validate that the infrastructure works correctly in that environment by making HTTP requests, API calls, SSH connections, etc.
Undeploy everything at the end of the test.

Note #1: Many of these tests create real resources in an AWS account. That means they cost money to run, especially if you don't clean up after yourself. Please be considerate of the resources you create and take extra care to clean everything up when you're done!

Note #2: Never hit CTRL + C or cancel a build once tests are running or the cleanup tasks won't run!

Note #3: We set -timeout 45m on all tests not because they necessarily take 45 minutes, but because Go has a default test timeout of 10 minutes, after which it does a SIGQUIT, preventing the tests from properly cleaning up after themselves. Therefore, we set a timeout of 45 minutes to make sure all tests have enough time to finish and cleanup.

How to run the tests

This repository comes with a Makefile, that helps you to run the tests in a convenient way. Alternatively, you can also run the tests without Docker.

Run the tests with Docker

Install Docker
Set your AWS credentials as environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
Run make docker-run-tests

Run the tests without Docker

Install the latest version of Go.
Install Terraform.
Set your AWS credentials as environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
Install go dependencies: go mod download
Run all tests: go test -v -count 1 -timeout 45m -parallel 128 ./test/... or use the convenient make test/unit-tests Makefile target.
Run a specific test: go test -count 1 -v -timeout 45m -parallel 128 test/example_test.go