Skip to content

Commit dfc34d9

Browse files
author
Matt Calhoun
authored
implement aws-component-helper (#30)
1 parent 7cf3356 commit dfc34d9

31 files changed

+1820
-737
lines changed

‎README.md‎

Lines changed: 129 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,8 @@
1-
<!-- markdownlint-disable -->
21

3-
# test-helpers <a href="https://cpco.io/homepage?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/test-helpers&utm_content="><img align="right" src="https://cloudposse.com/logo-300x69.svg" width="150" /></a>
42

3+
<!-- markdownlint-disable -->
4+
# test-helpers <a href="https://cpco.io/homepage?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/test-helpers&utm_content="><img align="right" src="https://cloudposse.com/logo-300x69.svg" width="150" /></a>
55
<a href="https://github.com/cloudposse/test-helpers/releases/latest"><img src="https://img.shields.io/github/release/cloudposse/test-helpers.svg" alt="Latest Release"/></a><a href="https://slack.cloudposse.com"><img src="https://slack.cloudposse.com/badge.svg" alt="Slack Community"/></a>
6-
76
<!-- markdownlint-restore -->
87

98
<!--
@@ -29,38 +28,46 @@
2928

3029
`test-helpers` is a library that adds some missing functionality to [terratest](https://terratest.gruntwork.io).
3130

31+
32+
33+
3234
## Introduction
3335

36+
3437
`test-helpers` is a library that adds some missing functionality to [terratest](https://terratest.gruntwork.io).
3538

3639
`test-helpers` includes functionality for:
3740

38-
- Destroying all resources in an AWS account after a test run using [aws-nuke](https://github.com/rebuy-de/aws-nuke)
39-
- Running tests with [atmos](https://github.com/cloudposse/atmos) stack configs
41+
- Destroying all resources in an AWS account after a test run using [aws-nuke](https://github.com/ekristen/aws-nuke)
42+
- Running tests with [atmos](https://github.com/cloudposse/atmos) stack configs
43+
- Running tests on components (Terraform root modules) that follow the Cloud Posse standards for implementation
44+
4045

4146
## Install
4247

4348
Install the latest version in your go tests
4449

4550
```console
46-
go install github.com/cloudposse/test-helpers
51+
go get github.com/cloudposse/test-helpers
4752
```
4853

4954
Get a specific version
5055

5156
```console
52-
go install github.com/cloudposse/test-helpers@v0.0.1
57+
go get github.com/cloudposse/test-helpers@v0.0.1
5358
```
5459

5560
## Usage
5661

57-
You can use `test-helpers` as a library in your own terratest code.
62+
You can use `test-helpers` as a library in your own Go test code along with the `terratest` library.
63+
64+
## Packages
5865

59-
### atmos
66+
### pkg/atmos
6067

6168
This library is designed to be used with [atmos](https://github.com/cloudposse/atmos) to allow you to run tests with
6269
different stack configurations. For example, imagine you have a component that you want to test to make sure it applies
63-
properly and that the coput contains "Hello, World". Below hows how you could run a test from an atmos stack.
70+
properly and that the coput contains "Hello, World". Below shows how you could run a test from an atmos stack.
6471

6572
```go
6673
func TestApplyNoError(t *testing.T) {
@@ -85,7 +92,10 @@ func TestApplyNoError(t *testing.T) {
8592
}
8693
```
8794

88-
### aws-nuke
95+
### pkg/aws-nuke
96+
97+
This package is designed to be used to destroy all resources created by a test in an AWS account after a test run
98+
using [aws-nuke](https://github.com/ekristen/aws-nuke).
8999

90100
```go
91101
func TestAwsNuke(t *testing.T) {
@@ -110,17 +120,115 @@ func TestAwsNuke(t *testing.T) {
110120
}
111121
```
112122
123+
### pkg/atmos/aws-component-helper
124+
125+
This package is designed to be used to test components that follow the Cloud Posse convention for AWS Components
126+
(terraform root modules). The code below demonstrates how to standup a test suite, deploy dependencies, deploy the
127+
component under test, run assertions, and then destroy the component under test and its dependencies.
128+
129+
```go
130+
package test
131+
132+
import (
133+
"fmt"
134+
"testing"
135+
136+
"github.com/cloudposse/test-helpers/pkg/atmos"
137+
helper "github.com/cloudposse/test-helpers/pkg/atmos/aws-component-helper"
138+
"github.com/stretchr/testify/require"
139+
)
140+
141+
var suite *helper.TestSuite
142+
143+
// TestMain is the entry point for the test suite. It initializes the test
144+
// suite and runs the tests, then tears the test suite down.
145+
func TestMain(m *testing.M) {
146+
var err error
147+
148+
// Configure the test suite. The component under test is `bastion` and the
149+
// stack is `test` in the `us-east-2` region.
150+
suite, err = helper.NewTestSuite("us-east-2", "bastion", "test")
151+
if err != nil {
152+
panic(err)
153+
}
154+
155+
// Add dependencies for the component under test in the same stack. If you
156+
// want to add dependencies in different stacks, use AddCrossStackDependencies.
157+
//
158+
// Dependencies are deployed in serial in the order they are added.
159+
suite.AddDependencies([]string{"vpc"})
160+
161+
// Create a new testing object since TestMain doesn't have one and we need
162+
// one to call the Setup and Teardown functions
163+
t := &testing.T{}
164+
165+
defer suite.TearDown(t)
166+
suite.Setup(t)
167+
168+
m.Run()
169+
}
170+
171+
func TestBastion(t *testing.T) {
172+
additionalVars := map[string]interface{}{}
173+
defer suite.DestroyComponentUnderTest(t, additionalVars)
174+
175+
_, err := suite.DeployComponentUnderTest(t, additionalVars)
176+
require.NoError(t, err)
177+
178+
instanceProfile := atmos.Output(t, suite.AtmosOptions, "iam_instance_profile")
179+
require.Equal(t, instanceProfile, fmt.Sprintf("eg-cptest-ue2-test-bastion-%s", suite.RandomSeed))
180+
}
181+
```
182+
183+
```bash
184+
$ go test -v -run TestBastion -skip-aws-nuke
185+
```
186+
187+
#### Test Phases
188+
189+
The `aws-component-helper` test suite is designed to be used with the `atmos` tool to allow you to test components
190+
that follow the Cloud Posse standards for implementation. The test suite runs several test "phases", which can be
191+
individually skipped as needed. By default, all phases are run. The following phases are run by default:
192+
193+
| Phase | Description |Flag|
194+
| ----- | ----------- |----|
195+
| Setup Test Suite | Bootstraps a temp directory and creates a new test suite or reads in a test suite from `test-suite.json` | N/A |
196+
| Setup Component Under Test | Copies the component from `src/` to the temp dir `components/terraform` | `-skip-setup-cut` |
197+
| Vendor Dependencies | Runs the `atmos vendor pull` command to pull in dependency components | `-skip-vendor` |
198+
| Deploy Dependencies | Runs the `atmos terraform apply` command to deploy the dependency stacks | `-skip-deploy-deps` |
199+
| Verify Enabled Flag | Runs a test to ensure the `enabled` flag results in no resources being created | `-skip-verify-enabled-flag` |
200+
| Deploy Component Under Test | Runs the `atmos terraform apply` command to deploy the component we are testing | `-skip-deploy-cut` |
201+
| Destroy Component Under Test | Runs the `atmos terraform destroy` command to destroy the component we are testing | `-skip-destroy-cut` |
202+
| Destroy Dependencies | Runs the `atmos destroy` command to destroy the dependencies | `-skip-destroy-deps` |
203+
| Tear Down Test Suite | Cleans up the temp directory | `-skip-teardown` |
204+
| Nuke Test Account | Uses [aws-nuke](https://github.com/ekristen/aws-nuke) to destroy all resources created during the test (by tag) | `-skip-aws-nuke` |
205+
113206
## Examples
114207
115208
The [example](examples/) folder contains a full set examples that demonstrate the use of `test-helpers`:
116209
117-
- [example](examples/awsnuke-example) folder contains a terraform module that can be used to test the `awsnuke` functionality.
210+
- [example](examples/awsnuke-example) folder contains a terraform module that can be used to test the `awsnuke` functionality.
118211
The test for this module is in [pkg/awsnuke/awsnuke_test.go](pkg/awsnuke/awsnuke_test.go).
212+
- [test/aws-component-helper](test/aws-component-helper) folder contains a terraform module and test that can be used to demonstrate the `aws-component-helper` functionality.
213+
214+
215+
216+
217+
218+
219+
220+
221+
222+
223+
224+
119225
120226
## ✨ Contributing
121227
122228
This project is under active development, and we encourage contributions from our community.
123229
230+
231+
124232
Many thanks to our outstanding contributors:
125233
126234
<a href="https://github.com/cloudposse/test-helpers/graphs/contributors">
@@ -130,19 +238,18 @@ Many thanks to our outstanding contributors:
130238
For 🐛 bug reports & feature requests, please use the [issue tracker](https://github.com/cloudposse/test-helpers/issues).
131239
132240
In general, PRs are welcome. We follow the typical "fork-and-pull" Git workflow.
133-
134-
1. Review our [Code of Conduct](https://github.com/cloudposse/test-helpers/?tab=coc-ov-file#code-of-conduct) and [Contributor Guidelines](https://github.com/cloudposse/.github/blob/main/CONTRIBUTING.md).
135-
2. **Fork** the repo on GitHub
136-
3. **Clone** the project to your own machine
137-
4. **Commit** changes to your own branch
138-
5. **Push** your work back up to your fork
139-
6. Submit a **Pull Request** so that we can review your changes
241+
1. Review our [Code of Conduct](https://github.com/cloudposse/test-helpers/?tab=coc-ov-file#code-of-conduct) and [Contributor Guidelines](https://github.com/cloudposse/.github/blob/main/CONTRIBUTING.md).
242+
2. **Fork** the repo on GitHub
243+
3. **Clone** the project to your own machine
244+
4. **Commit** changes to your own branch
245+
5. **Push** your work back up to your fork
246+
6. Submit a **Pull Request** so that we can review your changes
140247
141248
**NOTE:** Be sure to merge the latest changes from "upstream" before making a pull request!
142249
143250
### 🌎 Slack Community
144251
145-
Join our [Open Source Community](https://cpco.io/slack?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/test-helpers&utm_content=slack) on Slack. It's **FREE** for everyone! Our "SweetOps" community is where you get to talk with others who share a similar vision for how to rollout and manage infrastructure. This is the best place to talk shop, ask questions, solicit feedback, and work together as a community to build totally _sweet_ infrastructure.
252+
Join our [Open Source Community](https://cpco.io/slack?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/test-helpers&utm_content=slack) on Slack. It's **FREE** for everyone! Our "SweetOps" community is where you get to talk with others who share a similar vision for how to rollout and manage infrastructure. This is the best place to talk shop, ask questions, solicit feedback, and work together as a community to build totally *sweet* infrastructure.
146253
147254
### 📰 Newsletter
148255
@@ -153,7 +260,6 @@ Dropped straight into your Inbox every week — and usually a 5-minute read.
153260
154261
[Join us every Wednesday via Zoom](https://cloudposse.com/office-hours?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/test-helpers&utm_content=office_hours) for your weekly dose of insider DevOps trends, AWS news and Terraform insights, all sourced from our SweetOps community, plus a _live Q&A_ that you can’t find anywhere else.
155262
It's **FREE** for everyone!
156-
157263
## License
158264
159265
<a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=for-the-badge" alt="License"></a>
@@ -183,17 +289,17 @@ KIND, either express or implied. See the License for the
183289
specific language governing permissions and limitations
184290
under the License.
185291
```
186-
187292
</details>
188293
189294
## Trademarks
190295
191296
All other trademarks referenced herein are the property of their respective owners.
192297
193-
---
194298
299+
---
195300
Copyright © 2017-2024 [Cloud Posse, LLC](https://cpco.io/copyright)
196301
302+
197303
<a href="https://cloudposse.com/readme/footer/link?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/test-helpers&utm_content=readme_footer_link"><img alt="README footer" src="https://cloudposse.com/readme/footer/img"/></a>
198304
199305
<img alt="Beacon" width="0" src="https://ga-beacon.cloudposse.com/UA-76589703-4/cloudposse/test-helpers?pixel&cs=github&cm=readme&an=test-helpers"/>

0 commit comments

Comments
 (0)