tftest

package module
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 13, 2020 License: MPL-2.0 Imports: 12 Imported by: 0

README

Terraform Plugin Test Helper Library

This is an experimental library for testing Terraform plugins in their natural habitat as child processes of a real terraform executable.

This is not a HashiCorp project.

Documentation

Overview

Package tftest 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

This section is empty.

Variables

This section is empty.

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 FindTerraform 

func FindTerraform() string

FindTerraform attempts to find a Terraform CLI executable for plugin testing.

As a first preference it will look for the environment variable TF_ACC_TERRAFORM_PATH and return its value. If that variable is not set, it will look in PATH for a program named "terraform" and, if one is found, return its absolute path.

If no Terraform executable can be found, the result is the empty string. In that case, the test program will usually fail outright.

func InstallTerraform 

func InstallTerraform(tfVersion string) (string, error)

InstallTerraform downloads and decompresses a Terraform CLI executable with the specified version, downloaded from the HashiCorp releases page over HTTP.

The version string must match an existing Terraform release semver version, e.g. 0.12.5.

The terraform executable is installed to a temporary folder.

FIXME: Temporary folder should be cleaned up after tests have finished.

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.

func RunningAsPlugin 

func RunningAsPlugin() bool

RunningAsPlugin returns true if it detects the usual Terraform plugin detection environment variables, suggesting that the current process is being launched as a plugin server.

Types

type Config 

type Config struct {
	PluginName         string
	SourceDir          string
	TerraformExec      string
	CurrentPluginExec  string
	PreviousPluginExec string
}

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(pluginName string, 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(pluginName string, 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(name string, 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) HasPreviousVersion 

func (h *Helper) HasPreviousVersion() bool

HasPreviousVersion returns true if and only if the receiving helper has a previous plugin version available for use in tests.

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) PluginDir 

func (h *Helper) PluginDir() string

PluginDir returns the directory that should be used as the -plugin-dir when running "terraform init" in order to make Terraform detect the current version of the plugin.

func (*Helper) PreviousPluginDir 

func (h *Helper) PreviousPluginDir() string

PreviousPluginDir returns the directory that should be used as the -plugin-dir when running "terraform init" in order to make Terraform detect the previous version of the plugin, if available.

If no previous version is available, this method will panic. Use RequirePreviousVersion or HasPreviousVersion to ensure a previous version is available before calling this.

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) RequirePreviousVersion 

func (h *Helper) RequirePreviousVersion(t TestControl)

RequirePreviousVersion is a test guard that will produce a log and call SkipNow on the given TestControl if the receiving Helper does not have a previous plugin version to test against.

Call this immediately at the start of any "upgrade test" that expects to be able to run some operations with a previous version of the plugin before "upgrading" to the current version under test to continue with other operations.

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 tftest.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) 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) 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) InitPrevious 

func (wd *WorkingDir) InitPrevious() error

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

This method will panic if no previous plugin version is available. Use HasPreviousVersion or RequirePreviousVersion on the test helper singleton to check this first.

func (*WorkingDir) Refresh 

func (wd *WorkingDir) Refresh() error

Refresh runs terraform refresh

func (*WorkingDir) RequireApply 

func (wd *WorkingDir) RequireApply(t TestControl)

RequireApply is a variant of Apply that will fail the test via the given TestControl if the apply operation fails.

func (*WorkingDir) RequireClearPlan 

func (wd *WorkingDir) RequireClearPlan(t TestControl)

RequireClearPlan is a variant of ClearPlan that will fail the test via the given TestControl if the plan cannot be cleared.

func (*WorkingDir) RequireClearState 

func (wd *WorkingDir) RequireClearState(t TestControl)

RequireClearState is a variant of ClearState that will fail the test via the given TestControl if the state cannot be cleared.

func (*WorkingDir) RequireCreatePlan 

func (wd *WorkingDir) RequireCreatePlan(t TestControl)

RequireCreatePlan is a variant of CreatePlan that will fail the test via the given TestControl if plan creation fails.

func (*WorkingDir) RequireDestroy 

func (wd *WorkingDir) RequireDestroy(t TestControl)

RequireDestroy is a variant of Destroy that will fail the test via the given TestControl if the destroy operation fails.

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

func (*WorkingDir) RequireImport 

func (wd *WorkingDir) RequireImport(t TestControl, resource, id string)

RequireImport is a variant of Import that will fail the test via the given TestControl if the import is non successful.

func (*WorkingDir) RequireInit 

func (wd *WorkingDir) RequireInit(t TestControl)

RequireInit is a variant of Init that will fail the test via the given TestControl if init fails.

func (*WorkingDir) RequireInitPrevious 

func (wd *WorkingDir) RequireInitPrevious(t TestControl)

RequireInitPrevious is a variant of InitPrevious that will fail the test via the given TestControl if init fails.

func (*WorkingDir) RequireRefresh 

func (wd *WorkingDir) RequireRefresh(t TestControl)

RequireRefresh is a variant of Refresh that will fail the test via the given TestControl if the refresh is non successful.

func (*WorkingDir) RequireSavedPlan 

func (wd *WorkingDir) RequireSavedPlan(t TestControl) *tfjson.Plan

RequireSavedPlan is a variant of SavedPlan that will fail the test via the given TestControl if the plan cannot be read.

func (*WorkingDir) RequireSetConfig 

func (wd *WorkingDir) RequireSetConfig(t TestControl, cfg string)

RequireSetConfig is a variant of SetConfig that will fail the test via the given TestControl if the configuration cannot be set.

func (*WorkingDir) RequireState 

func (wd *WorkingDir) RequireState(t TestControl) *tfjson.State

RequireState is a variant of State that will fail the test via the given TestControl if the state cannot be read.

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) 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) State 

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

State returns an object describing the current state.

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.