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 output 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/component-helper

  This package is designed to be used to test components (root modules) that follow the Cloud Posse convention for
  terraform root modules.

  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/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
    github: mcalhoun