Skip to content

Commit

Permalink
refactor test helpers
Browse files Browse the repository at this point in the history
  • Loading branch information
@mcalhoun
mcalhoun committed Jan 28, 2025
1 parent c751907 commit 6ba16a1
Show file tree
Hide file tree
Showing 35 changed files with 1,303 additions and 1,476 deletions.
4 changes: 4 additions & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,3 +15,7 @@

bin/
unit-tests.xml

# atmos cache
.atmos/
test_suite.yaml
100 changes: 10 additions & 90 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ You can use `test-helpers` as a library in your own Go test code along with the

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

```go
func TestApplyNoError(t *testing.T) {
Expand Down Expand Up @@ -120,101 +120,21 @@ func TestAwsNuke(t *testing.T) {
}
```
### pkg/atmos/aws-component-helper
### pkg/atmos/component-helper
This package is designed to be used to test components that follow the Cloud Posse convention for AWS Components
(terraform root modules). The code below demonstrates how to standup a test suite, deploy dependencies, deploy the
component under test, run assertions, and then destroy the component under test and its dependencies.
This package is designed to be used to test components (root modules) that follow the Cloud Posse convention for
terraform root modules.
```go
package test

import (
"fmt"
"testing"

"github.com/cloudposse/test-helpers/pkg/atmos"
helper "github.com/cloudposse/test-helpers/pkg/atmos/aws-component-helper"
"github.com/stretchr/testify/require"
)

var suite *helper.TestSuite

// TestMain is the entry point for the test suite. It initializes the test
// suite and runs the tests, then tears the test suite down.
func TestMain(m *testing.M) {
var err error

// Configure the test suite. The component under test is `bastion` and the
// stack is `test` in the `us-east-2` region.
suite, err = helper.NewTestSuite("us-east-2", "bastion", "test")
if err != nil {
panic(err)
}

// Add dependencies for the component under test in the same stack. If you
// want to add dependencies in different stacks, use AddCrossStackDependencies.
//
// Dependencies are deployed in serial in the order they are added.
suite.AddDependencies([]string{"vpc"})

// Create a new testing object since TestMain doesn't have one and we need
// one to call the Setup and Teardown functions
t := &testing.T{}

defer suite.TearDown(t)
suite.Setup(t)

if !suite.SkipTests {
m.Run()
}
}

func TestBastion(t *testing.T) {
additionalVars := map[string]interface{}{}
defer suite.DestroyComponentUnderTest(t, additionalVars)

_, err := suite.DeployComponentUnderTest(t, additionalVars)
require.NoError(t, err)

instanceProfile := atmos.Output(t, suite.AtmosOptions, "iam_instance_profile")
require.Equal(t, instanceProfile, fmt.Sprintf("eg-cptest-ue2-test-bastion-%s", suite.RandomSeed))
}
```
```bash
$ go test -v -run TestBastion -skip-aws-nuke
```
#### Test Phases
The `aws-component-helper` test suite is designed to be used with the `atmos` tool to allow you to test components
that follow the Cloud Posse standards for implementation. The test suite runs several test "phases", which can be
individually skipped as needed. By default, all phases are run. The following phases are run by default:
| Phase | Description |Flag|
| ----- | ----------- |----|
| Force New Test Suite | Creates a new test suite in a new temp dir when another test suite is present | force-new-suite |
| Select Test Suite | Selects a test suite from `test-suite.json`. Required when multiple test suites are present | suite-index |
| 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 |
| 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 |
| Setup Component Under Test | Copies the component from `src/` to the temp dir `components/terraform` | `-skip-setup-cut` |
| Vendor Dependencies | Runs the `atmos vendor pull` command to pull in dependency components | `-skip-vendor` |
| Deploy Dependencies | Runs the `atmos terraform apply` command to deploy the dependency stacks | `-skip-deploy-deps` |
| Verify Enabled Flag | Runs a test to ensure the `enabled` flag results in no resources being created | `-skip-verify-enabled-flag` |
| Deploy Component Under Test | Runs the `atmos terraform apply` command to deploy the component we are testing | `-skip-deploy-cut` |
| Destroy Component Under Test | Runs the `atmos terraform destroy` command to destroy the component we are testing | `-skip-destroy-cut` |
| Destroy Dependencies | Runs the `atmos destroy` command to destroy the dependencies | `-skip-destroy-deps` |
| Tear Down Test Suite | Cleans up the temp directory | `-skip-teardown` |
| 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` |
For more information on using the `component-helper`, see the [component-helper README](pkg/atmos/component-helper/README.md).
## Examples
The [example](examples/) folder contains a full set examples that demonstrate the use of `test-helpers`:
- [example](examples/awsnuke-example) folder contains a terraform module that can be used to test the `awsnuke` functionality.
The test for this module is in [pkg/awsnuke/awsnuke_test.go](pkg/awsnuke/awsnuke_test.go).
- [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.
- [example](examples/awsnuke-example) folder contains a terraform module that can be used to test the `awsnuke`
functionality. The test for this module is in [pkg/awsnuke/awsnuke_test.go](pkg/awsnuke/awsnuke_test.go). -
[test/component-helper-integration](test/component-helper-integration) folder contains a terraform module and test
that can be used to demonstrate the `component-helper` functionality.
Expand Down Expand Up @@ -302,7 +222,7 @@ All other trademarks referenced herein are the property of their respective owne
---
Copyright © 2017-2024 [Cloud Posse, LLC](https://cpco.io/copyright)
Copyright © 2017-2025 [Cloud Posse, LLC](https://cpco.io/copyright)
<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>
Expand Down
98 changes: 9 additions & 89 deletions README.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ introduction: |-
This library is designed to be used with [atmos](https://github.com/cloudposse/atmos) to allow you to run tests with
different stack configurations. For example, imagine you have a component that you want to test to make sure it applies
properly and that the coput contains "Hello, World". Below shows how you could run a test from an atmos stack.
properly and that the output contains "Hello, World". Below shows how you could run a test from an atmos stack.
```go
func TestApplyNoError(t *testing.T) {
Expand Down Expand Up @@ -109,101 +109,21 @@ introduction: |-
}
```
### pkg/atmos/aws-component-helper
### pkg/atmos/component-helper
This package is designed to be used to test components that follow the Cloud Posse convention for AWS Components
(terraform root modules). The code below demonstrates how to standup a test suite, deploy dependencies, deploy the
component under test, run assertions, and then destroy the component under test and its dependencies.
This package is designed to be used to test components (root modules) that follow the Cloud Posse convention for
terraform root modules.
```go
package test
import (
"fmt"
"testing"
"github.com/cloudposse/test-helpers/pkg/atmos"
helper "github.com/cloudposse/test-helpers/pkg/atmos/aws-component-helper"
"github.com/stretchr/testify/require"
)
var suite *helper.TestSuite
// TestMain is the entry point for the test suite. It initializes the test
// suite and runs the tests, then tears the test suite down.
func TestMain(m *testing.M) {
var err error
// Configure the test suite. The component under test is `bastion` and the
// stack is `test` in the `us-east-2` region.
suite, err = helper.NewTestSuite("us-east-2", "bastion", "test")
if err != nil {
panic(err)
}
// Add dependencies for the component under test in the same stack. If you
// want to add dependencies in different stacks, use AddCrossStackDependencies.
//
// Dependencies are deployed in serial in the order they are added.
suite.AddDependencies([]string{"vpc"})
// Create a new testing object since TestMain doesn't have one and we need
// one to call the Setup and Teardown functions
t := &testing.T{}
defer suite.TearDown(t)
suite.Setup(t)
if !suite.SkipTests {
m.Run()
}
}
func TestBastion(t *testing.T) {
additionalVars := map[string]interface{}{}
defer suite.DestroyComponentUnderTest(t, additionalVars)
_, err := suite.DeployComponentUnderTest(t, additionalVars)
require.NoError(t, err)
instanceProfile := atmos.Output(t, suite.AtmosOptions, "iam_instance_profile")
require.Equal(t, instanceProfile, fmt.Sprintf("eg-cptest-ue2-test-bastion-%s", suite.RandomSeed))
}
```
```bash
$ go test -v -run TestBastion -skip-aws-nuke
```
#### Test Phases
The `aws-component-helper` test suite is designed to be used with the `atmos` tool to allow you to test components
that follow the Cloud Posse standards for implementation. The test suite runs several test "phases", which can be
individually skipped as needed. By default, all phases are run. The following phases are run by default:
| Phase | Description |Flag|
| ----- | ----------- |----|
| Force New Test Suite | Creates a new test suite in a new temp dir when another test suite is present | force-new-suite |
| Select Test Suite | Selects a test suite from `test-suite.json`. Required when multiple test suites are present | suite-index |
| 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 |
| 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 |
| Setup Component Under Test | Copies the component from `src/` to the temp dir `components/terraform` | `-skip-setup-cut` |
| Vendor Dependencies | Runs the `atmos vendor pull` command to pull in dependency components | `-skip-vendor` |
| Deploy Dependencies | Runs the `atmos terraform apply` command to deploy the dependency stacks | `-skip-deploy-deps` |
| Verify Enabled Flag | Runs a test to ensure the `enabled` flag results in no resources being created | `-skip-verify-enabled-flag` |
| Deploy Component Under Test | Runs the `atmos terraform apply` command to deploy the component we are testing | `-skip-deploy-cut` |
| Destroy Component Under Test | Runs the `atmos terraform destroy` command to destroy the component we are testing | `-skip-destroy-cut` |
| Destroy Dependencies | Runs the `atmos destroy` command to destroy the dependencies | `-skip-destroy-deps` |
| Tear Down Test Suite | Cleans up the temp directory | `-skip-teardown` |
| 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` |
For more information on using the `component-helper`, see the [component-helper README](pkg/atmos/component-helper/README.md).
## Examples
The [example](examples/) folder contains a full set examples that demonstrate the use of `test-helpers`:
- [example](examples/awsnuke-example) folder contains a terraform module that can be used to test the `awsnuke` functionality.
The test for this module is in [pkg/awsnuke/awsnuke_test.go](pkg/awsnuke/awsnuke_test.go).
- [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.
- [example](examples/awsnuke-example) folder contains a terraform module that can be used to test the `awsnuke`
functionality. The test for this module is in [pkg/awsnuke/awsnuke_test.go](pkg/awsnuke/awsnuke_test.go). -
[test/component-helper-integration](test/component-helper-integration) folder contains a terraform module and test
that can be used to demonstrate the `component-helper` functionality.
contributors:
- name: Matt Calhoun
Expand Down
Loading

0 comments on commit 6ba16a1

Please sign in to comment.