README.yaml

name: test-helpers
license: APACHE2
github_repo: cloudposse/test-helpers
badges:
  - name: Latest Release
    image: https://img.shields.io/github/release/cloudposse/test-helpers.svg
    url: https://github.com/cloudposse/test-helpers/releases/latest
  - name: Slack Community
    image: https://slack.cloudposse.com/badge.svg
    url: https://slack.cloudposse.com

categories:
  - cli
  - automation
  - cloud
  - devops
  - workflow
  - terraform
  - terratest

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

introduction: |-

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

  `test-helpers` includes functionality for:

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


  ## Install

  Install the latest version in your go tests

  ```console
  go get github.com/cloudposse/test-helpers
  ```

  Get a specific version

  ```console
  go get github.com/cloudposse/test-helpers@v0.0.1
  ```

  ## Usage

  You can use `test-helpers` as a library in your own Go test code along with the `terratest` library.

  ## Packages

  ### pkg/atmos

  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.

  ```go
  func TestApplyNoError(t *testing.T) {
    t.Parallel()

    testFolder, err := files.CopyTerraformFolderToTemp("../../test/fixtures/atmos", t.Name())
    require.NoError(t, err)
    defer os.RemoveAll(testFolder)

    fmt.Printf("running in %s\n", testFolder)

    options := WithDefaultRetryableErrors(t, &Options{
      AtmosBasePath: testFolder,
      Component:     "terraform-no-error",
      Stack:         "test-test-test",
      NoColor:       true,
    })

    out := Apply(t, options)

    require.Contains(t, out, "Hello, World")
  }
  ```

  ### pkg/aws-nuke

  This package is designed to be used to destroy all resources created by a test in an AWS account after a test run
  using [aws-nuke](https://github.com/ekristen/aws-nuke).

  ```go
  func TestAwsNuke(t *testing.T) {
    t.Parallel()
    randID := strings.ToLower(random.UniqueId())

    rootFolder := "../../"
    terraformFolderRelativeToRoot := "examples/awsnuke-example"
    tempTestFolder := testStructure.CopyTerraformFolderToTemp(t, rootFolder, terraformFolderRelativeToRoot)
    defer os.RemoveAll(tempTestFolder)

    terraformOptions := &terraform.Options{
        TerraformDir: tempTestFolder,
        Upgrade:      true,
        VarFiles:     []string{fmt.Sprintf("fixtures.%s.tfvars", testRegion)},
        Vars: map[string]interface{}{
          "attributes": []string{randID},
          "default_tags": map[string]string{
          terratestTagName: randID,
        },
     },
  }
  ```

  ### pkg/atmos/aws-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.

  ```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` |

  ## 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.

contributors:
  - name: Matt Calhoun
    github: mcalhoun