setuptest

Documentation

Overview

Package setuptest is used to setup a test environment for testing Terraform code. It will copy the supplied directories to a temporary location before running Terraform commands like init, plan, apply, destroy and output.

Index

• Variables
• func CopyTerraformFolderToTempAndCleanUp(t *testing.T, moduleDir string, testDir string) (string, func() error, error)
• type DirType
  • func Dirs(rootdir, testdir string) DirType
  • func (d DirType) WithVarFiles(varfiles []string) DirTypeWithVarFiles
  • func (d DirType) WithVars(vars map[string]any) DirTypeWithVars
• type DirTypeWithVarFiles
  • func (dtvf DirTypeWithVarFiles) Init(t *testing.T) (Response, error)
  • func (dtvf DirTypeWithVarFiles) InitPlanShow(t *testing.T) (Response, error)
  • func (dtvf DirTypeWithVarFiles) InitPlanShowWithPrepFunc(t *testing.T, f PrepFunc) (Response, error)
• type DirTypeWithVars
  • func (dtv DirTypeWithVars) Init(t *testing.T) (Response, error)
  • func (dtv DirTypeWithVars) InitPlanShow(t *testing.T) (Response, error)
  • func (dtv DirTypeWithVars) InitPlanShowWithPrepFunc(t *testing.T, f PrepFunc) (Response, error)
• type PrepFunc
• type Response
  • func (resp Response) Apply() *testerror.Error
  • func (resp Response) ApplyIdempotent() *testerror.Error
  • func (resp Response) ApplyIdempotentRetry(r Retry) *testerror.Error
  • func (resp Response) Destroy() *testerror.Error
  • func (resp Response) DestroyRetry(r Retry) *testerror.Error
  • func (resp Response) Output(name string) ops.Operative
• type Retry
• type StreamLogger
  • func NewMemoryLogger() *StreamLogger
  • func NewStreamLogger(stream io.ReadWriter) *StreamLogger
  • func (s *StreamLogger) Close() error
  • func (s *StreamLogger) Logf(t testing.TestingT, format string, args ...interface{})
  • func (s *StreamLogger) PipeFrom(srcLogger *StreamLogger) error

Variables

var DefaultRetry = Retry{
	Max:  5,
	Wait: time.Minute,
}

DefaultRetry is the default retry configuration. It will retry up to 5 times with a 1 minute wait between each attempt.

var FastRetry = Retry{
	Max:  6,
	Wait: 20 * time.Second,
}

DefaultRetry is the faster retry configuration. It will retry up to 6 times with a 20 second wait between each attempt.

var SlowRetry = Retry{
	Max:  15,
	Wait: 2 * time.Minute,
}

SlowRetry is the slower retry configuration. It will retry up to 15 times with a 2 minute wait between each attempt.

Functions

func CopyTerraformFolderToTempAndCleanUp

func CopyTerraformFolderToTempAndCleanUp(t *testing.T, moduleDir string, testDir string) (string, func() error, error)

CopyTerraformFolderToTempAndCleanUp sets up a temporary copy of the supplied module folder It will return a three values which contains the temporary directory, a cleanup function and an error.

The testdir input is the relative path to the test directory, it can be blank if testing the module directly with variables or it can be a relative path to the module directory if testing the module using a subdirectory.

Note: This function will only work if the test directory is in a child subdirectory of the test directory. e.g. you cannot use parent paths of the moduleDir.

The depth input is used to determine how many directories to go up to make sure we fully clean up.

Types

type DirType

type DirType struct {
	RootDir string
	TestDir string
}

DirType is a type which can be used for more fluent setup of a test. It contains the two directories required. The root, and the subdirectory of the root containing the test. If the test directory is blank, the test will be run in the root directory.

func Dirs

func Dirs(rootdir, testdir string) DirType

Dirs func begins the fluent test setup process. It takes a root directory and a test directory as parameters.

The root directory is the directory containing the terraform code to be tested. The test directory is the directory containing the test code, it should either be blank to test the code in the root, or a relative path beneath the root directory.

Before a Terraform command is run, the code in the root directory will be copied to a temporary directory.

func (DirType) WithVarFiles

func (d DirType) WithVarFiles(varfiles []string) DirTypeWithVarFiles

WithVarFiles is an method of DirType and allows you to add variable files in the form of []string. It returns a type which can be used for more fluent setup of a test with variable files.

func (DirType) WithVars

func (d DirType) WithVars(vars map[string]any) DirTypeWithVars

WithVars is an method of DirType and allows you to add variables in the form of `map[string]any`. It returns a type which can be used for more fluent setup of a test with variables.

type DirTypeWithVarFiles

type DirTypeWithVarFiles struct {
	RootDir  string
	TestDir  string
	VarFiles []string
}

DirTypeWithVarFiles is a type which can be used for more fluent setup of a test with variable files. It is used by the Init* methods to setup the test.

func (DirTypeWithVarFiles) Init

func (dtvf DirTypeWithVarFiles) Init(t *testing.T) (Response, error)

Init is a wrapper around terraform.InitE It takes a test object as a parameter and returns a setuptest.Response.

The response contains the temporary directory, the plan, the Terraform options and a cleanup function. The temporary directory is the directory containing a copy of the code specified by the Dirs func. The plan is the plan struct generated by terraform, which can be used by the check package - will be empty, as no plan is generated. If you want a plan struct use the InitPlanShow method. The cleanup function provides coherent logging and also will clean up the temporary directory - use with defer.

func (DirTypeWithVarFiles) InitPlanShow

func (dtvf DirTypeWithVarFiles) InitPlanShow(t *testing.T) (Response, error)

InitPlanShow is a wrapper around terraform.InitAndPlanAndShowWithStructE It takes a test object as a parameter and returns a setuptest.Response.

The response contains the temporary directory, the plan, the Terraform options and a cleanup function. The temporary directory is the directory containing a copy of the code specified by the Dirs func. The plan is the plan struct generated by terraform, which can be used by the check package. The cleanup function is a provides coherent logging and also will clean up the temporary directory - use with defer.

func (DirTypeWithVarFiles) InitPlanShowWithPrepFunc

func (dtvf DirTypeWithVarFiles) InitPlanShowWithPrepFunc(t *testing.T, f PrepFunc) (Response, error)

InitPlanShow is a wrapper around terraform.InitAndPlanAndShowWithStructE It takes a test object and a SetupTestPrepFunc as a parameter and returns a setuptest.Response. The PrepFunc is executed after the test has been coped to a tmp directory, allowing file modifications to be made before running terraform.

The response contains the temporary directory, the plan, the Terraform options and a cleanup function. The temporary directory is the directory containing a copy of the code specified by the Dirs func. The terraform options are the options used to run terraform and can be used by the apply functions. The plan is the plan struct generated by terraform, which can be used by the check package. The cleanup function is a function which should be used with defer to clean up the temporary directory.

type DirTypeWithVars

type DirTypeWithVars struct {
	RootDir string
	TestDir string
	Vars    map[string]any
}

DirTypeWithVars is a type which can be used for more fluent setup of a test with variables. It is used by the Init* methods to setup the test.

func (DirTypeWithVars) Init

func (dtv DirTypeWithVars) Init(t *testing.T) (Response, error)

Init is a wrapper around terraform.InitE It takes a test object as a parameter and returns a setuptest.Response.

The response contains the temporary directory, the plan, the Terraform options and a cleanup function. The temporary directory is the directory containing a copy of the code specified by the Dirs func. The plan is the plan struct generated by terraform, which can be used by the check package - will be empty, as no plan is generated. If you want a plan struct use the InitPlanShow method. The cleanup function provides coherent logging and also will clean up the temporary directory - use with defer.

func (DirTypeWithVars) InitPlanShow

func (dtv DirTypeWithVars) InitPlanShow(t *testing.T) (Response, error)

InitPlanShow is a wrapper around terraform.InitAndPlanAndShowWithStructE It takes a test object as a parameter and returns a setuptest.Response.

The response contains the temporary directory, the plan, the Terraform options and a cleanup function. The temporary directory is the directory containing a copy of the code specified by the Dirs func. The plan is the plan struct generated by terraform, which can be used by the check package. The cleanup function provides coherent logging and also will clean up the temporary directory - use with defer.

func (DirTypeWithVars) InitPlanShowWithPrepFunc

func (dtv DirTypeWithVars) InitPlanShowWithPrepFunc(t *testing.T, f PrepFunc) (Response, error)

InitPlanShowWithPrepFunc is a wrapper around terraform.InitAndPlanAndShowWithStructE It takes a test object and a SetupTestPrepFunc as a parameter and returns a setuptest.Response. The PrepFunc is executed after the test has been copied to a tmp directory, allowing file modifications to be made before running Terraform.

The response contains the temporary directory, the plan, the Terraform options and a cleanup function. The temporary directory is the directory containing a copy of the code specified by the Dirs func. The terraform options are the options used to run terraform and can be used by the apply functions. The plan is the plan struct generated by terraform, which can be used by the check package. The cleanup function provides coherent logging and also will clean up the temporary directory - use with defer.

type PrepFunc

type PrepFunc func(Response) error

PrepFunc is a function that is used to prepare the test directory before running Terraform. It takes a SetupTestResponse struct as a parameter and returns an error.

Example usage is to create a files in the test directory when testing submodules, e.g. AzureRM provider blocks.

type Response

type Response struct {
	TmpDir     string                // The temporary directory containing the copied code.
	PlanStruct *terraform.PlanStruct // The plan struct generated by terraform.
	Options    *terraform.Options    // The options used to run terraform.
	Cleanup    func()                // A function that should be used with defer. It provides coherent logging output and cleans up the temporary directory.
	// contains filtered or unexported fields
}

A Response is a struct which allows us to orchestrate the running of a terraform test.

func (Response) Apply

func (resp Response) Apply() *testerror.Error

Apply runs terraform apply for the given Response and returns the error. If the plan file does not exist, it will run terraform apply without a plan file.

func (Response) ApplyIdempotent

func (resp Response) ApplyIdempotent() *testerror.Error

Apply runs terraform apply, then plan for the given Response and checks for any changes, it then returns the error. If the plan file does not exist, it will run terraform apply without a plan file.

func (Response) ApplyIdempotentRetry

func (resp Response) ApplyIdempotentRetry(r Retry) *testerror.Error

Apply runs terraform apply, then performs a retry loop with a plan. If the configuration is not idempotent, it will retry up to the specified number of times. It then returns the error. If the plan file does not exist, it will run terraform apply without a plan file.

func (Response) Destroy

func (resp Response) Destroy() *testerror.Error

Destroy runs terraform destroy for the given Response and returns the error.

func (Response) DestroyRetry

func (resp Response) DestroyRetry(r Retry) *testerror.Error

DestroyWithRetry will retry the terraform destroy command up to the specified number of times.

func (Response) Output

func (resp Response) Output(name string) ops.Operative

Output returns an Operative for the given output name. This allows us to perform assertions on the output value, e.g. ...Output("foo").HasValue("bar")

This function works best with strongly typed values, e.g. `bool`, `number`, `string`, `list`, `map`, etc. If you use this with type `any`, then you will be dealing with strings and you assertion options will be limited.

type Retry

type Retry struct {
	Max  int
	Wait time.Duration
}

Retry is a configuration for retrying a terraform command. Max is the number of times to retry. Wait is the amount of time to wait between each retry.

type StreamLogger

type StreamLogger struct {
	// contains filtered or unexported fields
}

A StreamLogger is a logger that writes to a stream, such as stdout, a file or a memory buffer. It also keeps track of the number of log lines written, and can output a progress message every 50 lines.

func NewMemoryLogger

func NewMemoryLogger() *StreamLogger

NewMemoryLogger creates a new StreamLogger that writes to an in-memory buffer. This is useful for capturing logs in tests.

func NewStreamLogger

func NewStreamLogger(stream io.ReadWriter) *StreamLogger

NewStreamLogger creates a new StreamLogger that writes to the given stream.

func (*StreamLogger) Close

func (s *StreamLogger) Close() error

func (*StreamLogger) Logf

func (s *StreamLogger) Logf(t testing.TestingT, format string, args ...interface{})

Logf logs the given arguments to the given writer, along with a prefix of the test name.

func (*StreamLogger) PipeFrom

func (s *StreamLogger) PipeFrom(srcLogger *StreamLogger) error

The PipeFrom function is a method of the StreamLogger struct. It takes a pointer to another StreamLogger object as its input parameter and returns an error. Inside the function, a mutex lock is acquired to ensure that the function is thread-safe. The PipeFrom function is useful when you want to redirect the output of one logger to another logger. For example, if you have a logger that writes to the console and another logger that writes to a file, you can use PipeFrom to redirect the console logger's output to the file logger: