plugintest

Documentation

Overview

Package plugintest contains utilities to help with writing tests for Terraform plugins.

This is not a package for testing configurations or modules written in the Terraform language. It is for testing the plugins that allow Terraform to manage various cloud services and other APIs.

Index

• Constants
• func AcceptanceTest(t TestControl)
• func LongTest(t TestControl)
• type Config
  • func DiscoverConfig(sourceDir string) (*Config, error)
• type Helper
  • func AutoInitHelper(sourceDir string) (*Helper, error)
  • func AutoInitProviderHelper(sourceDir string) *Helper
  • func InitHelper(config *Config) (*Helper, error)
  • func (h *Helper) Close() error
  • func (h *Helper) NewWorkingDir() (*WorkingDir, error)
  • func (h *Helper) RequireNewWorkingDir(t TestControl) *WorkingDir
  • func (h *Helper) TerraformExecPath() string
• type TestControl
• type WorkingDir
  • func (wd *WorkingDir) Apply() error
  • func (wd *WorkingDir) ClearPlan() error
  • func (wd *WorkingDir) ClearState() error
  • func (wd *WorkingDir) Close() error
  • func (wd *WorkingDir) CreateDestroyPlan() error
  • func (wd *WorkingDir) CreatePlan() error
  • func (wd *WorkingDir) Destroy() error
  • func (wd *WorkingDir) GetHelper() *Helper
  • func (wd *WorkingDir) HasSavedPlan() bool
  • func (wd *WorkingDir) Import(resource, id string) error
  • func (wd *WorkingDir) Init() error
  • func (wd *WorkingDir) Refresh() error
  • func (wd *WorkingDir) SavedPlan() (*tfjson.Plan, error)
  • func (wd *WorkingDir) SavedPlanRawStdout() (string, error)
  • func (wd *WorkingDir) Schemas() (*tfjson.ProviderSchemas, error)
  • func (wd *WorkingDir) SetConfig(cfg string) error
  • func (wd *WorkingDir) SetReattachInfo(reattachInfo tfexec.ReattachInfo)
  • func (wd *WorkingDir) Setenv(envVar, val string)
  • func (wd *WorkingDir) State() (*tfjson.State, error)
  • func (wd *WorkingDir) UnsetReattachInfo()
  • func (wd *WorkingDir) Unsetenv(envVar string)

Constants

const (
	ConfigFileName = "terraform_plugin_test.tf"
	PlanFileName   = "tfplan"
)

Functions

func AcceptanceTest

func AcceptanceTest(t TestControl)

AcceptanceTest is a test guard that will produce a log and call SkipNow on the given TestControl if the environment variable TF_ACC isn't set to indicate that the caller wants to run acceptance tests.

Call this immediately at the start of each acceptance test function to signal that it may cost money and thus requires this opt-in enviromment variable.

For the purpose of this function, an "acceptance test" is any est that reaches out to services that are not directly controlled by the test program itself, particularly if those requests may lead to service charges. For any system where it is possible and realistic to run a local instance of the service for testing (e.g. in a daemon launched by the test program itself), prefer to do this and _don't_ call AcceptanceTest, thus allowing tests to be run more easily and without external cost by contributors.

func LongTest

func LongTest(t TestControl)

LongTest is a test guard that will produce a log and call SkipNow on the given TestControl if the test harness is currently running in "short mode".

What is considered a "long test" will always be pretty subjective, but test implementers should think of this in terms of what seems like it'd be inconvenient to run repeatedly for quick feedback while testing a new feature under development.

When testing resource types that always take several minutes to complete operations, consider having a single general test that covers the basic functionality and then mark any other more specific tests as long tests so that developers can quickly smoke-test a particular feature when needed but can still run the full set of tests for a feature when needed.

Types

type Config

type Config struct {
	SourceDir     string
	TerraformExec string

	PreviousPluginExec string
	// contains filtered or unexported fields
}

Config is used to configure the test helper. In most normal test programs the configuration is discovered automatically by an Init* function using DiscoverConfig, but this is exposed so that more complex scenarios can be implemented by direct configuration.

func DiscoverConfig

func DiscoverConfig(sourceDir string) (*Config, error)

DiscoverConfig uses environment variables and other means to automatically discover a reasonable test helper configuration.

type Helper

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

Helper is intended as a per-package singleton created in TestMain which other tests in a package can use to create Terraform execution contexts

func AutoInitHelper

func AutoInitHelper(sourceDir string) (*Helper, error)

AutoInitHelper uses the auto-discovery behavior of DiscoverConfig to prepare a configuration and then calls InitHelper with it. This is a convenient way to get the standard init behavior based on environment variables, and callers should use this unless they have an unusual requirement that calls for constructing a config in a different way.

func AutoInitProviderHelper

func AutoInitProviderHelper(sourceDir string) *Helper

AutoInitProviderHelper is the main entrypoint for testing provider plugins using this package. It is intended to be called during TestMain to prepare for provider testing.

AutoInitProviderHelper will discover the location of a current Terraform CLI executable to test against, detect whether a prior version of the plugin is available for upgrade tests, and then will return an object containing the results of that initialization which can then be stored in a global variable for use in other tests.

func InitHelper

func InitHelper(config *Config) (*Helper, error)

InitHelper prepares a testing helper with the given configuration.

For most callers it is sufficient to call AutoInitHelper instead, which will construct a configuration automatically based on certain environment variables.

If this function returns an error then it may have left some temporary files behind in the system's temporary directory. There is currently no way to automatically clean those up.

func (*Helper) Close

func (h *Helper) Close() error

Close cleans up temporary files and directories created to support this helper, returning an error if any of the cleanup fails.

Call this before returning from TestMain to minimize the amount of detritus left behind in the filesystem after the tests complete.

func (*Helper) NewWorkingDir

func (h *Helper) NewWorkingDir() (*WorkingDir, error)

NewWorkingDir creates a new working directory for use in the implementation of a single test, returning a WorkingDir object representing that directory.

If the working directory object is not itself closed by the time the test program exits, the Close method on the helper itself will attempt to delete it.

func (*Helper) RequireNewWorkingDir

func (h *Helper) RequireNewWorkingDir(t TestControl) *WorkingDir

RequireNewWorkingDir is a variant of NewWorkingDir that takes a TestControl object and will immediately fail the running test if the creation of the working directory fails.

func (*Helper) TerraformExecPath

func (h *Helper) TerraformExecPath() string

TerraformExecPath returns the location of the Terraform CLI executable that should be used when running tests.

type TestControl

type TestControl interface {
	Helper()
	Log(args ...interface{})
	FailNow()
	SkipNow()
}

TestControl is an interface requiring a subset of *testing.T which is used by the test guards and helpers in this package. Most callers can simply pass their *testing.T value here, but the interface allows other implementations to potentially be provided instead, for example to allow meta-testing (testing of the test utilities themselves).

This interface also describes the subset of normal test functionality the guards and helpers can perform: they can only create log lines, fail tests, and skip tests. All other test control is the responsibility of the main test code.

type WorkingDir

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

WorkingDir represents a distinct working directory that can be used for running tests. Each test should construct its own WorkingDir by calling NewWorkingDir or RequireNewWorkingDir on its package's singleton plugintest.Helper.

func (*WorkingDir) Apply

func (wd *WorkingDir) Apply() error

Apply runs "terraform apply". If CreatePlan has previously completed successfully and the saved plan has not been cleared in the meantime then this will apply the saved plan. Otherwise, it will implicitly create a new plan and apply it.

func (*WorkingDir) ClearPlan

func (wd *WorkingDir) ClearPlan() error

ClearPlan deletes any saved plan present in the working directory.

func (*WorkingDir) ClearState

func (wd *WorkingDir) ClearState() error

ClearState deletes any Terraform state present in the working directory.

Any remote objects tracked by the state are not destroyed first, so this will leave them dangling in the remote system.

func (*WorkingDir) Close

func (wd *WorkingDir) Close() error

Close deletes the directories and files created to represent the receiving working directory. After this method is called, the working directory object is invalid and may no longer be used.

func (*WorkingDir) CreateDestroyPlan

func (wd *WorkingDir) CreateDestroyPlan() error

CreateDestroyPlan runs "terraform plan -destroy" to create a saved plan file, which if successful will then be used for the next call to Apply.

func (*WorkingDir) CreatePlan

func (wd *WorkingDir) CreatePlan() error

CreatePlan runs "terraform plan" to create a saved plan file, which if successful will then be used for the next call to Apply.

func (*WorkingDir) Destroy

func (wd *WorkingDir) Destroy() error

Destroy runs "terraform destroy". It does not consider or modify any saved plan, and is primarily for cleaning up at the end of a test run.

If destroy fails then remote objects might still exist, and continue to exist after a particular test is concluded.

func (*WorkingDir) GetHelper

func (wd *WorkingDir) GetHelper() *Helper

GetHelper returns the Helper set on the WorkingDir.

func (*WorkingDir) HasSavedPlan

func (wd *WorkingDir) HasSavedPlan() bool

HasSavedPlan returns true if there is a saved plan in the working directory. If so, a subsequent call to Apply will apply that saved plan.

func (*WorkingDir) Import

func (wd *WorkingDir) Import(resource, id string) error

Import runs terraform import

func (*WorkingDir) Init

func (wd *WorkingDir) Init() error

Init runs "terraform init" for the given working directory, forcing Terraform to use the current version of the plugin under test.

func (*WorkingDir) Refresh

func (wd *WorkingDir) Refresh() error

Refresh runs terraform refresh

func (*WorkingDir) SavedPlan

func (wd *WorkingDir) SavedPlan() (*tfjson.Plan, error)

SavedPlan returns an object describing the current saved plan file, if any.

If no plan is saved or if the plan file cannot be read, SavedPlan returns an error.

func (*WorkingDir) SavedPlanRawStdout

func (wd *WorkingDir) SavedPlanRawStdout() (string, error)

SavedPlanRawStdout returns a human readable stdout capture of the current saved plan file, if any.

If no plan is saved or if the plan file cannot be read, SavedPlanRawStdout returns an error.

func (*WorkingDir) Schemas

func (wd *WorkingDir) Schemas() (*tfjson.ProviderSchemas, error)

Schemas returns an object describing the provider schemas.

If the schemas cannot be read, Schemas returns an error.

func (*WorkingDir) SetConfig

func (wd *WorkingDir) SetConfig(cfg string) error

SetConfig sets a new configuration for the working directory.

This must be called at least once before any call to Init, Plan, Apply, or Destroy to establish the configuration. Any previously-set configuration is discarded and any saved plan is cleared.

func (*WorkingDir) SetReattachInfo

func (wd *WorkingDir) SetReattachInfo(reattachInfo tfexec.ReattachInfo)

func (*WorkingDir) Setenv

func (wd *WorkingDir) Setenv(envVar, val string)

Setenv sets an environment variable on the WorkingDir.

func (*WorkingDir) State

func (wd *WorkingDir) State() (*tfjson.State, error)

If the state cannot be read, State returns an error.

func (*WorkingDir) UnsetReattachInfo

func (wd *WorkingDir) UnsetReattachInfo()

func (*WorkingDir) Unsetenv

func (wd *WorkingDir) Unsetenv(envVar string)

Unsetenv removes an environment variable from the WorkingDir.