moduletest

Documentation

Overview

Package moduletest contains the support code for some experimental features we're using to evaluate strategies for having an opinionated approach to testing of Terraform modules.

At the moment nothing in this module is considered stable, so any features that are usable by end-users ought to emit experiment warnings saying that everything is subject to change even in patch releases.

Index

• type Assertion
• type Component
• type Provider
  • func NewProvider() *Provider
  • func (p *Provider) ApplyResourceChange(req providers.ApplyResourceChangeRequest) providers.ApplyResourceChangeResponse
  • func (p *Provider) Close() error
  • func (p *Provider) ConfigureProvider(providers.ConfigureProviderRequest) providers.ConfigureProviderResponse
  • func (p *Provider) GetProviderSchema() providers.GetProviderSchemaResponse
  • func (p *Provider) ImportResourceState(req providers.ImportResourceStateRequest) providers.ImportResourceStateResponse
  • func (p *Provider) PlanResourceChange(req providers.PlanResourceChangeRequest) providers.PlanResourceChangeResponse
  • func (p *Provider) ReadDataSource(req providers.ReadDataSourceRequest) providers.ReadDataSourceResponse
  • func (p *Provider) ReadResource(req providers.ReadResourceRequest) providers.ReadResourceResponse
  • func (p *Provider) Reset() map[string]*Component
  • func (p *Provider) Stop() error
  • func (p *Provider) TestResults() map[string]*Component
  • func (p *Provider) UpgradeResourceState(req providers.UpgradeResourceStateRequest) providers.UpgradeResourceStateResponse
  • func (p *Provider) ValidateDataResourceConfig(req providers.ValidateDataResourceConfigRequest) providers.ValidateDataResourceConfigResponse
  • func (p *Provider) ValidateProviderConfig(req providers.ValidateProviderConfigRequest) providers.ValidateProviderConfigResponse
  • func (p *Provider) ValidateResourceConfig(req providers.ValidateResourceConfigRequest) providers.ValidateResourceConfigResponse
• type Status
  • func (i Status) String() string
  • func (s Status) SuiteCanPass() bool
• type Suite

Types

type Assertion

type Assertion struct {
	Outcome Status

	// Description is a user-provided, human-readable description of what
	// this assertion represents.
	Description string

	// Message is typically relevant only for TestFailed or TestError
	// assertions, giving a human-readable description of the problem,
	// formatted in the way our format package expects to receive paragraphs
	// for terminal word wrapping.
	Message string

	// Diagnostics includes diagnostics specific to the current test assertion,
	// if available.
	Diagnostics tfdiags.Diagnostics
}

Assertion is the description of a single test assertion, whether successful or unsuccessful.

type Component

type Component struct {
	Assertions map[string]*Assertion
}

Component represents a component being tested, each of which can have several associated test assertions.

type Provider

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

Provider is an implementation of providers.Interface which we're using as a likely-only-temporary vehicle for research on an opinionated module testing workflow in Terraform.

We expose this to configuration as "terraform.io/builtin/test", but any attempt to configure it will emit a warning that it is experimental and likely to change or be removed entirely in future Terraform CLI releases.

The testing provider exists to gather up test results during a Terraform apply operation. Its "test_results" managed resource type doesn't have any user-visible effect on its own, but when used in conjunction with the "terraform test" experimental command it is the intermediary that holds the test results while the test runs, so that the test command can then report them.

For correct behavior of the assertion tracking, the "terraform test" command must be sure to use the same instance of Provider for both the plan and apply steps, so that the assertions that were planned can still be tracked during apply. For other commands that don't explicitly support test assertions, the provider will still succeed but the assertions data may not be complete if the apply step fails.

func NewProvider

func NewProvider() *Provider

NewProvider returns a new instance of the test provider.

func (*Provider) ApplyResourceChange

func (p *Provider) ApplyResourceChange(req providers.ApplyResourceChangeRequest) providers.ApplyResourceChangeResponse

ApplyResourceChange takes the planned state for a resource, which may yet contain unknown computed values, and applies the changes returning the final state.

func (*Provider) Close

func (p *Provider) Close() error

Close is a noop for this provider, since it's run in-process.

func (*Provider) ConfigureProvider

func (p *Provider) ConfigureProvider(providers.ConfigureProviderRequest) providers.ConfigureProviderResponse

ConfigureProvider configures and initializes the provider.

func (*Provider) GetProviderSchema

func (p *Provider) GetProviderSchema() providers.GetProviderSchemaResponse

GetProviderSchema returns the complete schema for the provider.

func (*Provider) ImportResourceState

func (p *Provider) ImportResourceState(req providers.ImportResourceStateRequest) providers.ImportResourceStateResponse

ImportResourceState requests that the given resource be imported.

func (*Provider) PlanResourceChange

func (p *Provider) PlanResourceChange(req providers.PlanResourceChangeRequest) providers.PlanResourceChangeResponse

PlanResourceChange takes the current state and proposed state of a resource, and returns the planned final state.

func (*Provider) ReadDataSource

func (p *Provider) ReadDataSource(req providers.ReadDataSourceRequest) providers.ReadDataSourceResponse

ReadDataSource returns the data source's current state.

func (*Provider) ReadResource

func (p *Provider) ReadResource(req providers.ReadResourceRequest) providers.ReadResourceResponse

ReadResource refreshes a resource and returns its current state.

func (*Provider) Reset

func (p *Provider) Reset() map[string]*Component

Reset returns the recieving provider back to its original state, with no recorded test results.

It additionally detaches the instance from any data structure previously returned by method TestResults, freeing the caller from the constraints in its documentation about mutability and storage.

For convenience in the presumed common case of resetting as part of capturing the results for storage, this method also returns the result that method TestResults would've returned if called prior to the call to Reset.

func (*Provider) Stop

func (p *Provider) Stop() error

Stop is called when the provider should halt any in-flight actions.

func (*Provider) TestResults

func (p *Provider) TestResults() map[string]*Component

TestResults returns the current record of test results tracked inside the provider.

The result is a direct reference to the internal state of the provider, so the caller mustn't modify it nor store it across calls to provider operations.

func (*Provider) UpgradeResourceState

func (p *Provider) UpgradeResourceState(req providers.UpgradeResourceStateRequest) providers.UpgradeResourceStateResponse

UpgradeResourceState is called to allow the provider to adapt the raw value stored in the state in case the schema has changed since it was originally written.

func (*Provider) ValidateDataResourceConfig

func (p *Provider) ValidateDataResourceConfig(req providers.ValidateDataResourceConfigRequest) providers.ValidateDataResourceConfigResponse

ValidateDataResourceConfig is used to to validate the resource configuration values.

func (*Provider) ValidateProviderConfig

func (p *Provider) ValidateProviderConfig(req providers.ValidateProviderConfigRequest) providers.ValidateProviderConfigResponse

ValidateProviderConfig validates the provider configuration.

func (*Provider) ValidateResourceConfig

func (p *Provider) ValidateResourceConfig(req providers.ValidateResourceConfigRequest) providers.ValidateResourceConfigResponse

ValidateResourceConfig is used to validate configuration values for a resource.

type Status

type Status rune

Status is an enumeration of possible outcomes of a test assertion.

const (
	// Pending indicates that the test was registered (during planning)
	// but didn't register an outcome during apply, perhaps due to being
	// blocked by some other upstream failure.
	Pending Status = '?'

	// Passed indicates that the test condition succeeded.
	Passed Status = 'P'

	// Failed indicates that the test condition was valid but did not
	// succeed.
	Failed Status = 'F'

	// Error indicates that the test condition was invalid or that the
	// test report failed in some other way.
	Error Status = 'E'
)

func (Status) String

func (i Status) String() string

func (Status) SuiteCanPass

func (s Status) SuiteCanPass() bool

SuiteCanPass returns true if a suite containing an assertion with this status could possibly succeed. The suite as a whole succeeds only if all of its assertions have statuses where SuiteCanPass returns true.

type Suite

type Suite struct {
	Name       string
	Components map[string]*Component
}

A Suite is a set of tests run together as a single Terraform configuration.