|
| 1 | +# Using the Terratest Docker Container |
| 2 | + |
| 3 | +Use the Terratest Docker container to run the suite of Terratest Go tests. For more information on Terratest, follow the [Documentation](https://terratest.gruntwork.io/docs/) page. The Terratest Docker image is used by the [Github Workflow](../../.github/workflows/default_plan_unit_tests.yml) as a required check before merging changes. |
| 4 | + |
| 5 | +## Prereqs |
| 6 | + |
| 7 | +- Docker [installed on your workstation](../../README.md#docker). |
| 8 | + |
| 9 | +## Preparation |
| 10 | + |
| 11 | +### Docker image |
| 12 | + |
| 13 | +Run the following command to create the `viya4-iac-azure-terratest` Docker image using the provided [Dockerfile.terratest](../../Dockerfile.terratest) |
| 14 | + |
| 15 | +```bash |
| 16 | +docker build -t viya4-iac-azure-terratest -f Dockerfile.terratest . |
| 17 | +``` |
| 18 | + |
| 19 | +The Docker image `viya4-iac-azure-terratest` will contain Terraform and Go executables, as well as the required Go modules. The Docker entrypoint for the image is `go test`, and it accepts several optional command-line arguments. For more information about command-line arguments, see [Command-Line Arguments](#command-line-arguments). |
| 20 | + |
| 21 | +### Docker Environment File for Azure Authentication |
| 22 | + |
| 23 | +Follow either one of the authentication methods that are described in [Authenticating Terraform to access Azure](./TerraformAzureAuthentication.md), and create a file with the authentication variable values to use with container invocation. Store these values outside of this repository in a secure file, such as |
| 24 | +`$HOME/.azure_docker_creds.env`. Protect that file with Azure credentials so that only you have Read access to it. **NOTE**: Do not use quotation marks around the values in the file, and be sure to avoid any trailing blank spaces. |
| 25 | + |
| 26 | +Now each time you invoke the container, specify the file with the [`--env-file`](https://docs.docker.com/engine/reference/commandline/run/#set-environment-variables--e---env---env-file) option to pass Azure credentials to the container. |
| 27 | + |
| 28 | +### Docker Volume Mounts |
| 29 | + |
| 30 | +Run the following command: |
| 31 | +`--volume="$(pwd)":/viya4-iac-azure` |
| 32 | +Note that the project must be mounted to the `/viya4-iac-azure` directory. |
| 33 | + |
| 34 | +## Command-Line Arguments |
| 35 | + |
| 36 | +The `terratest_docker_entrypoint.sh` script supports several command-line arguments to customize the test execution. Here are the available options: |
| 37 | + |
| 38 | +* `-p, --package=PACKAGE`: The package to test. Default is './...' |
| 39 | +* `-r, --run=TEST`: The name of the test to run. Default is '.\*Plan.\*'. |
| 40 | +* `-v, --verbose`: Run the tests in verbose mode. |
| 41 | +* `-h, --help`: Display the help message. |
| 42 | + |
| 43 | +## Running Terratest Commands |
| 44 | + |
| 45 | +### Running the Default Tests |
| 46 | + |
| 47 | +To run the default suite of unit tests (only `terraform plan`), run the following Docker command: |
| 48 | + |
| 49 | +```bash |
| 50 | +# Run from the ./viya4-iac-azure directory |
| 51 | +docker run --rm \ |
| 52 | + --env-file=$HOME/.azure_docker_creds.env \ |
| 53 | + --volume "$(pwd)":/viya4-iac-azure \ |
| 54 | + viya4-iac-azure-terratest |
| 55 | +``` |
| 56 | + |
| 57 | +### Running a Specific Go Test |
| 58 | + |
| 59 | +To run a specific test, run the following Docker command with the `-r` option: |
| 60 | + |
| 61 | +```bash |
| 62 | +# Run from the ./viya4-iac-azure directory |
| 63 | +docker run --rm \ |
| 64 | + --env-file=$HOME/.azure_docker_creds.env \ |
| 65 | + --volume "$(pwd)":/viya4-iac-azure \ |
| 66 | + viya4-iac-azure-terratest \ |
| 67 | + -r="YourTest" |
| 68 | +``` |
| 69 | +To run multiple tests, pass in a regex to the `-r` option - "TestName1|TestName2|TestName3" |
| 70 | + |
| 71 | +### Running a Specific Go Package and Test |
| 72 | + |
| 73 | +If you want to specify the Go package and test name, run the following Docker command with the following options: |
| 74 | + |
| 75 | +```bash |
| 76 | +# Run from the ./viya4-iac-azure directory |
| 77 | +docker run --rm \ |
| 78 | + --env-file=$HOME/.azure_docker_creds.env \ |
| 79 | + --volume "$(pwd)":/viya4-iac-azure \ |
| 80 | + viya4-iac-azure-terratest \ |
| 81 | + -r="YourTest" \ |
| 82 | + -p="YourPackage" |
| 83 | +``` |
| 84 | + |
| 85 | +### Running the Go Tests with verbose mode |
| 86 | + |
| 87 | +If you want to run the tests in verbose mode, run the Docker command with the `-v` option: |
| 88 | + |
| 89 | +```bash |
| 90 | +# Run from the ./viya4-iac-azure directory |
| 91 | +docker run --rm \ |
| 92 | + --env-file=$HOME/.azure_docker_creds.env \ |
| 93 | + --volume "$(pwd)":/viya4-iac-azure \ |
| 94 | + viya4-iac-azure-terratest -v |
| 95 | +``` |
| 96 | + |
| 97 | +### Accessing test run logs |
| 98 | + |
| 99 | +After you have started the Docker container, log files are created in the `./viya4-iac-azure/test/test_output` directory. These files enable you to view the test results in XML format, as well as test logs that are generated by the terrratest_log_parser. |
0 commit comments