You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Terratest uses the Go testing framework. To use Terratest, you need to install:
17
+
Terratest uses the Go testing framework, and the examples below drive [OpenTofu](https://opentofu.org/). To follow
18
+
along, you need:
18
19
19
20
-[Go](https://golang.org/) (requires version >=1.26)
21
+
-[OpenTofu](https://opentofu.org/docs/intro/install/) (or [Terraform](https://www.terraform.io/), if you prefer)
20
22
21
-
## Setting up your project
23
+
Terratest's `terraform` module runs whichever binary you point it at. By default it uses `terraform` when that binary
24
+
is on your `PATH` and otherwise falls back to `tofu`, so installing only OpenTofu is enough to get going. To pin a test
25
+
to OpenTofu regardless of what else is installed, set `TerraformBinary: "tofu"` in the `terraform.Options` you pass to
26
+
the helpers (more on this [below](#preferring-opentofu)).
22
27
23
-
The easiest way to get started with Terratest is to copy one of the examples and its corresponding tests from this
24
-
repo. This quick start section uses a Terraform example, but check out the [Examples]({{site.baseurl}}/examples/) section for other
25
-
types of infrastructure code you can test (e.g., Packer, Kubernetes, etc).
28
+
The rest of this guide uses [mise](https://mise.jdx.dev/) to manage tool versions. It isn't required (install Go and
29
+
OpenTofu however you like), but it keeps everyone on the same versions.
26
30
27
-
1. Create an `examples` and `test` folder.
31
+
## Starting a new project
28
32
29
-
1. Copy the folder including all the files from the [basic terraform example](https://github.com/gruntwork-io/terratest/tree/{{ site.stable_ref }}/examples/terraform-basic-example/) into the `examples` folder.
33
+
If you're adding tests to an existing module, skip to [Setting up your tests](#setting-up-your-tests). Otherwise, here
34
+
is how to stand up a fresh Go project from scratch.
30
35
31
-
1.Copy the [basic terraform example test](https://github.com/gruntwork-io/terratest/blob/{{ site.stable_ref }}/test/terraform_basic_example_test.go) into the `test` folder.
36
+
1.Create the project and initialize Git:
32
37
33
-
1. To configure dependencies, run:
38
+
```bash
39
+
mkdir my-infra &&cd my-infra
40
+
git init
41
+
```
42
+
43
+
1. Pin your tools with mise. This writes a `mise.toml` that anyone cloning the repo can use to install the exact same
44
+
versions:
45
+
46
+
```bash
47
+
mise use go@1.26
48
+
mise use opentofu@1.12.3
49
+
```
50
+
51
+
Run `mise install` to fetch the tools, and prefix commands with `mise x -- <command>` (or run `mise activate`in
52
+
your shell) so they resolve to the pinned versions.
53
+
54
+
1. Lay out the standard Terratest folders. Infrastructure code lives in`examples`, and the Go tests that exercise it
55
+
live in`test`:
56
+
57
+
```bash
58
+
mkdir examples test
59
+
```
60
+
61
+
1. Initialize the Go module. Terratest tests live in their own module under `test`:
34
62
35
63
```bash
36
64
cdtest
37
65
go mod init "<MODULE_NAME>"
38
-
go mod tidy
39
66
```
40
67
41
68
Where `<MODULE_NAME>` is the name of your module, typically in the format
1. Add a `.gitignore` so you don't commit local state, provider plugins, or build artifacts:
72
+
73
+
```bash
74
+
cat > ../.gitignore <<'EOF'
75
+
.terraform/
76
+
*.tfstate
77
+
*.tfstate.backup
78
+
.terraform.lock.hcl
79
+
EOF
80
+
```
81
+
82
+
Now add some infrastructure and a test, as described next.
83
+
84
+
## Setting up your tests
85
+
86
+
The easiest way to get started with Terratest is to copy one of the examples and its corresponding tests from this
87
+
repo. This quick start section uses an OpenTofu/Terraform example, but check out the
88
+
[Examples]({{site.baseurl}}/examples/) section for other types of infrastructure code you can test (e.g., Packer,
89
+
Kubernetes, etc).
90
+
91
+
1. Copy the folder including all the files from the [basic example](https://github.com/gruntwork-io/terratest/tree/{{ site.stable_ref }}/examples/terraform-basic-example/) into the `examples` folder.
92
+
93
+
1. Copy the [basic example test](https://github.com/gruntwork-io/terratest/blob/{{ site.stable_ref }}/test/terraform_basic_example_test.go) into the `test` folder.
94
+
95
+
1. To configure dependencies, run:
96
+
97
+
```bash
98
+
cd test
99
+
go mod tidy
100
+
```
101
+
102
+
(If you skipped the previous section, run `go mod init "<MODULE_NAME>"` first.)
103
+
44
104
To lock your tests to a specific Terratest release, see [Pinning a Terratest version]({{ site.baseurl }}/docs/getting-started/version-pinning/).
45
105
46
106
1. To run the tests:
@@ -52,66 +112,82 @@ types of infrastructure code you can test (e.g., Packer, Kubernetes, etc).
52
112
53
113
*(See [Timeouts and logging]({{ site.baseurl }}/docs/testing-best-practices/timeouts-and-logging/) for why the `-timeout` parameter is used.)*
54
114
115
+
### Preferring OpenTofu
116
+
117
+
By default the `terraform` helpers use the `terraform` binary if it's installed and fall back to `tofu` otherwise. To
118
+
run OpenTofu explicitly, even on a machine that also has Terraform, set`TerraformBinary` on the options you pass in:
The helper functionnames (`terraform.InitAndApply`, `terraform.Output`, and so on) don't change; only the underlying
128
+
executable does.
129
+
55
130
56
131
## Terratest intro
57
132
58
133
The basic usage pattern for writing automated tests with Terratest is to:
59
134
60
135
1. Write tests using Go’s built-in [package testing](https://golang.org/pkg/testing/): you create a file ending in `_test.go` and run tests with the `go test` command. E.g., `go test my_test.go`.
61
-
1. 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).
136
+
1. Use Terratest to execute your _real_ IaC tools (e.g., OpenTofu, Packer, etc.) to deploy _real_ infrastructure (e.g., servers) in a _real_ environment (e.g., AWS).
62
137
1. Use the tools built into Terratest to validate that the infrastructure works correctly in that environment by making HTTP requests, API calls, SSH connections, etc.
63
138
1. Undeploy everything at the end of the test.
64
139
65
-
To make this sort of testing easier, Terratest provides a variety of helper functions and patterns for common infrastructure testing tasks, such as testing Terraform code, testing Packer templates, testing Docker images, executing commands on servers over SSH, making HTTP requests, working with AWS APIs, and so on.
140
+
To make this sort of testing easier, Terratest provides a variety of helper functions and patterns for common infrastructure testing tasks, such as testing OpenTofu and Terraform code, testing Packer templates, testing Docker images, executing commands on servers over SSH, making HTTP requests, working with AWS APIs, and so on.
66
141
67
142
68
-
## Example #1: Terraform "Hello, World"
143
+
## Example #1: OpenTofu "Hello, World"
144
+
145
+
Let's start with the simplest possible [OpenTofu](https://opentofu.org/) code, which just outputs the text,
146
+
"Hello, World" (if you’re new to OpenTofu or Terraform, check out our [Comprehensive Guide to
147
+
Terraform](https://blog.gruntwork.io/a-comprehensive-guide-to-terraform-b3d32832baca), which applies equally to
148
+
OpenTofu):
69
149
70
-
Let's start with the simplest possible [Terraform](https://www.terraform.io/) code, which just outputs the text,
71
-
"Hello, World" (if you’re new to Terraform, check out our [Comprehensive Guide to
0 commit comments