api

package
v1.9.7 Latest Latest
Warning

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

 Go to latest Published: Jul 8, 2024 License: Apache-2.0 Imports: 8 Imported by: 2

Documentation

Index

Constants

View Source 
const (
	// DefaultRetryAttempts indicates the default number of times to retry
	// retries when the plugin uses retries but has not specified a number of
	// attempts.
	DefaultRetryAttempts = 3 * time.Second
	// DefaultRetryConstantInterval indicates the default interval to use for
	// retries when the plugin uses retries but does not use exponential
	// backoff.
	DefaultRetryConstantInterval = 3 * time.Second
)

Variables

View Source 
var (
	// ErrFailure is the base error class for all errors that represent failed
	// assertions when evaluating a test.
	ErrFailure = errors.New("assertion failed")
	// ErrTimeoutExceeded is an ErrFailure when a test's execution exceeds a
	// timeout length.
	ErrTimeoutExceeded = fmt.Errorf("%s: timeout exceeded", ErrFailure)
	// ErrNotEqual is an ErrFailure when an expected thing doesn't equal an
	// observed thing.
	ErrNotEqual = fmt.Errorf("%w: not equal", ErrFailure)
	// ErrIn is an ErrFailure when a thing unexpectedly appears in an
	// container.
	ErrIn = fmt.Errorf("%w: in", ErrFailure)
	// ErrNotIn is an ErrFailure when an expected thing doesn't appear in an
	// expected container.
	ErrNotIn = fmt.Errorf("%w: not in", ErrFailure)
	// ErrNoneIn is an ErrFailure when none of a list of elements appears in an
	// expected container.
	ErrNoneIn = fmt.Errorf("%w: none in", ErrFailure)
	// ErrUnexpectedError is an ErrFailure when an unexpected error has
	// occurred.
	ErrUnexpectedError = fmt.Errorf("%w: unexpected error", ErrFailure)
)
View Source 
var (
	// ErrUnknownSourceType indicates that a From() function was called with an
	// unknown source parameter type.
	ErrUnknownSourceType = errors.New("unknown source argument type")
	// ErrUnknownSpec indicates that there was a test spec definition in a YAML
	// file that no plugin could parse.
	ErrUnknownSpec = errors.New("no plugin could parse spec definition")
	// ErrUnknownField indicates that there was an unknown field in the parsing
	// of a spec or scenario.
	ErrUnknownField = errors.New("unknown field")
	// ErrParse indicates a YAML definition is not valid
	ErrParse = errors.New("invalid YAML")
	// ErrExpectedMap indicates that we did not find an expected mapping
	// field
	ErrExpectedMap = fmt.Errorf(
		"%w: expected map field", ErrParse,
	)
	// ErrExpectedScalar indicates that we did not find an expected scalar
	// field
	ErrExpectedScalar = fmt.Errorf(
		"%w: expected scalar field", ErrParse,
	)
	// ErrExpectedSequence indicates that we did not find an expected
	// scalar field
	ErrExpectedSequence = fmt.Errorf(
		"%w: expected sequence field", ErrParse,
	)
	// ErrExpectedInt indicates that we did not find an expected integer
	// value
	ErrExpectedInt = fmt.Errorf(
		"%w: expected int value", ErrParse,
	)
	// ErrExpectedScalarOrMap indicates that we did not find an expected
	// scalar or map field
	ErrExpectedScalarOrMap = fmt.Errorf(
		"%w: expected scalar or map field", ErrParse,
	)
	// ErrExpectedScalarOrSequence indicates that we did not find an expected
	// scalar or sequence of scalars field
	ErrExpectedScalarOrSequence = fmt.Errorf(
		"%w: expected scalar or sequence of scalars field", ErrParse,
	)
	// ErrExpectedTimeout indicates that the timeout specification was not
	// valid.
	ErrExpectedTimeout = fmt.Errorf(
		"%w: expected timeout specification", ErrParse,
	)
	// ErrExpectedWait indicates that the wait specification was not valid.
	ErrExpectedWait = fmt.Errorf(
		"%w: expected wait specification", ErrParse,
	)
	// ErrExpectedRetry indicates that the retry specification was not valid.
	ErrExpectedRetry = fmt.Errorf(
		"%w: expected retry specification", ErrParse,
	)
	// ErrInvalidRetryAttempts indicates that the retry attempts was not
	// positive.
	ErrInvalidRetryAttempts = fmt.Errorf(
		"%w: invalid retry attempts", ErrParse,
	)
	// ErrFileNotFound is returned when a file path does not exist for a
	// create/apply/delete target.
	ErrFileNotFound = fmt.Errorf(
		"%w: file not found", ErrParse,
	)
)
View Source 
var (
	// RuntimeError is the base error class for all errors occurring during
	// runtime (and not during the parsing of a scenario or spec)
	RuntimeError = errors.New("runtime error")
	// ErrRequiredFixture is returned when a required fixture has not
	// been registered with the context.
	ErrRequiredFixture = fmt.Errorf(
		"%w: required fixture missing",
		RuntimeError,
	)
	// ErrTimeoutConflict is returned when the Go test tool's timeout conflicts
	// with either a total wait time or a timeout in a scenario or test spec
	ErrTimeoutConflict = fmt.Errorf(
		"%w: timeout conflict",
		RuntimeError,
	)
)
View Source 
var (
	// BaseSpecFields contains the list of base spec fields for plugin Spec
	// types to use in ignoring unknown fields.
	BaseSpecFields = []string{
		"name",
		"description",
		"timeout",
		"wait",
		"retry",
	}
)
View Source 
var (
	// NoRetry indicates that there should not be any retry attempts. It is
	// passed from a plugin to indicate a Spec should not be retried.
	NoRetry = &Retry{}
)

Functions

func ExpectedIntAt 

func ExpectedIntAt(node *yaml.Node) error

ExpectedIntAt returns an ErrExpectedInt error annotated with the line/column of the supplied YAML node.

func ExpectedMapAt 

func ExpectedMapAt(node *yaml.Node) error

ExpectedMapAt returns an ErrExpectedMap error annotated with the line/column of the supplied YAML node.

func ExpectedRetryAt 

func ExpectedRetryAt(node *yaml.Node) error

ExpectedRetryAt returns an ErrExpectedRetry error annotated with the line/column of the supplied YAML node.

func ExpectedScalarAt 

func ExpectedScalarAt(node *yaml.Node) error

ExpectedScalarAt returns an ErrExpectedScalar error annotated with the line/column of the supplied YAML node.

func ExpectedScalarOrMapAt 

func ExpectedScalarOrMapAt(node *yaml.Node) error

ExpectedScalarOrMapAt returns an ErrExpectedScalarOrMap error annotated with the line/column of the supplied YAML node.

func ExpectedScalarOrSequenceAt 

func ExpectedScalarOrSequenceAt(node *yaml.Node) error

ExpectedScalarOrSequenceAt returns an ErrExpectedScalarOrSequence error annotated with the line/column of the supplied YAML node.

func ExpectedSequenceAt 

func ExpectedSequenceAt(node *yaml.Node) error

ExpectedSequenceAt returns an ErrExpectedSequence error annotated with the line/column of the supplied YAML node.

func ExpectedTimeoutAt 

func ExpectedTimeoutAt(node *yaml.Node) error

ExpectedTimeoutAt returns an ErrExpectedTimeout error annotated with the line/column of the supplied YAML node.

func ExpectedWaitAt 

func ExpectedWaitAt(node *yaml.Node) error

ExpectedWaitAt returns an ErrExpectedWait error annotated with the line/column of the supplied YAML node.

func FileNotFound 

func FileNotFound(path string, node *yaml.Node) error

FileNotFound returns ErrFileNotFound for a given file path

func In 

func In(element, container interface{}) error

In returns an ErrIn when a thing unexpectedly appears in a container.

func InvalidRetryAttempts 

func InvalidRetryAttempts(node *yaml.Node, attempts int) error

InvalidRetryAttempts returns an ErrInvalidRetryAttempts error annotated with the line/column of the supplied YAML node.

func NoneIn 

func NoneIn(elements, container interface{}) error

NoneIn returns an ErrNoneIn when none of a list of elements appears in an expected container.

func NotEqual 

func NotEqual(exp, got interface{}) error

NotEqual returns an ErrNotEqual when an expected thing doesn't equal an observed thing.

func NotEqualLength 

func NotEqualLength(exp, got int) error

NotEqualLength returns an ErrNotEqual when an expected length doesn't equal an observed length.

func NotIn 

func NotIn(element, container interface{}) error

NotIn returns an ErrNotIn when an expected thing doesn't appear in an expected container.

func RequiredFixtureMissing 

func RequiredFixtureMissing(name string) error

RequiredFixtureMissing returns an ErrRequiredFixture with the supplied fixture name

func TimeoutConflict added in v1.9.5 

func TimeoutConflict(
	ti *Timings,
) error

TimeoutConflict returns an ErrTimeoutConflict describing how the Go test tool's timeout conflicts with either a total wait time or a timeout value from a scenario or spec.

func TimeoutExceeded 

func TimeoutExceeded(duration string, failure error) error

TimeoutExceeded returns an ErrTimeoutExceeded when a test's execution exceeds a timeout length. The optional failure parameter indicates a failed assertion that occurred before a timeout was reached.

func UnexpectedError 

func UnexpectedError(err error) error

UnexpectedError returns an ErrUnexpectedError when a supplied error is not expected.

func UnknownFieldAt 

func UnknownFieldAt(field string, node *yaml.Node) error

UnknownFieldAt returns an ErrUnknownField for a supplied field annotated with the line/column of the supplied YAML node.

func UnknownSourceType 

func UnknownSourceType(source interface{}) error

UnknownSourceType returns an ErrUnknownSourceType error describing the supplied parameter type.

func UnknownSpecAt 

func UnknownSpecAt(path string, node *yaml.Node) error

UnknownSpecAt returns an ErrUnknownSpec with the line/column of the supplied YAML node.

Types

type Assertions 

type Assertions interface {
	// OK returns true if all contained assertions pass successfully, false
	// otherwise. If false is returned, Failures() is guaranteed to be
	// non-empty.
	OK(context.Context) bool
	// Fail appends a supplied error to the set of failed assertions
	Fail(error)
	// Failures returns a slice of failure messages indicating which assertions
	// did not succeed.
	Failures() []error
}

Assertions track zero or more assertions about some result

type Defaults 

type Defaults map[string]interface{}

Defaults are a collection of default configuration values

func (*Defaults) For 

func (d *Defaults) For(key string) interface{}

type Evaluable 

type Evaluable interface {
	// Eval performs an action and evaluates the results of that action,
	// returning a Result that informs the Scenario about what failed or
	// succeeded about the Evaluable's conditions.
	//
	// Errors returned by Eval() are **RuntimeErrors**, not failures in
	// assertions.
	Eval(context.Context) (*Result, error)
	// SetBase sets the Evaluable's base Spec
	SetBase(Spec)
	// Base returns the Evaluable's base Spec
	Base() *Spec
	// Retry returns the Evaluable's Retry override, if any
	Retry() *Retry
	// Timeout returns the Evaluable's Timeout override, if any
	Timeout() *Timeout
}

Evaluable represents individual test units in a Scenario

type Fixture 

type Fixture interface {
	// Start sets up the fixture
	Start(context.Context) error
	// Stop tears down the fixture, cleaning up any owned resources
	Stop(context.Context)
	// HasState returns true if the fixture contains some state with the given
	// key
	HasState(string) bool
	// State returns the state data at the given key, or nil if no such state
	// key is managed by the fixture
	State(string) interface{}
}

A Fixture allows state to be passed from setups

type FlexStrings 

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

FlexStrings is a struct used to parse an interface{} that can be either a string or a slice of strings.

func (*FlexStrings) UnmarshalYAML 

func (f *FlexStrings) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML is a custom unmarshaler that understands that the value of the FlexStrings can be either a string or a slice of strings.

func (*FlexStrings) Values 

func (f *FlexStrings) Values() []string

Values returns the contained collection of string values.

type Plugin 

type Plugin interface {
	// Info returns a struct that describes what the plugin does
	Info() PluginInfo
	// Defaults returns a YAML Unmarshaler types that the plugin knows how
	// to parse its defaults configuration with.
	Defaults() yaml.Unmarshaler
	// Specs returns a list of YAML Unmarshaler types that the plugin knows
	// how to parse.
	Specs() []Evaluable
}

Plugin is the driver interface for different types of gdt tests.

type PluginInfo 

type PluginInfo struct {
	// Name is the primary name of the plugin
	Name string
	// Aliases is an optional set of aliased names for the plugin
	Aliases []string
	// Description describes what types of tests the plugin can handle.
	Description string
	// Timeout is a Timeout that should be used by default for test specs of
	// this plugin.
	Timeout *Timeout
	// Retry is a Retry that should be used by default for test specs of this
	// plugin.
	Retry *Retry
}

PluginInfo contains basic information about the plugin and what type of tests it can handle.

type Result 

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

Result is returned from a `Evaluable.Eval` execution. It serves two purposes:

1) to return an error, if any, from the Eval execution. This error will *always* be a `gdterrors.RuntimeError`. Failed assertions are not errors. 2) to pass back information about the Run that can be injected into the context's `PriorRun` cache. Some plugins, e.g. the gdt-http plugin, use cached data from a previous run in order to construct current Run fixtures. In the case of the gdt=http plugin, the previous `nethttp.Response` is returned in the Result and the `Scenario.Run` method injects that information into the context that is supplied to the next Spec's `Run`.

func NewResult 

func NewResult(mods ...ResultModifier) *Result

NewResult returns a new Result

func (*Result) Data 

func (r *Result) Data() map[string]interface{}

Data returns the raw run data saved in the result

func (*Result) Failed 

func (r *Result) Failed() bool

Failed returns true if any assertion failed during Eval(), false otherwise.

func (*Result) Failures 

func (r *Result) Failures() []error

Failures returns the collection of assertion failures that occurred during Eval().

func (*Result) HasData 

func (r *Result) HasData() bool

HasData returns true if any of the run data has been set, false otherwise.

func (*Result) SetData 

func (r *Result) SetData(
	key string,
	val interface{},
)

SetData sets a value in the result's run data cache.

func (*Result) SetFailures 

func (r *Result) SetFailures(failures ...error)

SetFailures sets the result's collection of assertion failures.

type ResultModifier 

type ResultModifier func(*Result)

func WithData 

func WithData(key string, val interface{}) ResultModifier

WithData modifies the Result with the supplied run data key and value

func WithFailures 

func WithFailures(failures ...error) ResultModifier

WithFailures modifies the Result the supplied collection of assertion failures

type Retry 

type Retry struct {
	// Attempts is the number of  times that the test unit should be retried in
	// the event of assertion failure.
	Attempts *int `yaml:"attempts,omitempty"`
	// Interval is the amount of time that the plugin should wait before
	// retrying the test unit in the event of assertion failure.
	// Specify a duration using Go's time duration string.
	// See https://pkg.go.dev/time#ParseDuration
	Interval string `yaml:"interval,omitempty"`
	// Exponential indicates that an exponential backoff should be applied to
	// the retry. When true, the value of Interval, if any, is used as the
	// initial interval for the backoff algoritm.
	Exponential bool `yaml:"exponential,omitempty"`
}

Retry contains information about the number of attempts and interval duration with which a Plugin should re-run a Spec's action if the Spec's assertions fail.

func (*Retry) IntervalDuration 

func (r *Retry) IntervalDuration() time.Duration

IntervalDuration returns the time duration of the Retry.Interval

type Runnable added in v1.9.5 

type Runnable interface {
	// Run accepts a context and a `*testing.T` and runs some tests within that
	// context
	//
	// Errors returned by Run() are **RuntimeErrors**, not failures in
	// assertions.
	Run(context.Context, *testing.T) error
}

Runnable are things that Run a `*testing.T`

type SetOn added in v1.9.5 

type SetOn int
const (
	SetOnNone          SetOn = iota
	SetOnSpec                // a test spec override
	SetOnPlugin              // a plugin override
	SetOnPluginDefault       // a plugin default
	SetOnDefault             // a scenario default
)

type Spec 

type Spec struct {
	// Plugin is a pointer to the plugin that successfully parsed the test spec
	Plugin Plugin `yaml:"-"`
	// Defaults contains the parsed defaults for the Spec. These are injected
	// by the scenario during parse.
	Defaults *Defaults `yaml:"-"`
	// Index within the scenario where this Spec is located
	Index int `yaml:"-"`
	// Name for the individual test unit
	Name string `yaml:"name,omitempty"`
	// Description of the test unit
	Description string `yaml:"description,omitempty"`
	// Timeout contains the timeout configuration for the Spec
	Timeout *Timeout `yaml:"timeout,omitempty"`
	// Wait contains the wait configuration for the Spec
	Wait *Wait `yaml:"wait,omitempty"`
	// Retry contains the retry configuration for the Spec
	Retry *Retry `yaml:"retry,omitempty"`
}

Spec represents a single test action and one or more assertions about output or behaviour. All gdt plugins have their own Spec structs that inherit from this base struct.

func (*Spec) Title 

func (s *Spec) Title() string

Title returns the Name of the scenario or the Path's file/base name if there is no name.

func (*Spec) UnmarshalYAML 

func (s *Spec) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML examines the mapping YAML node for base Spec fields and sets the associated struct field from that value node.

type Timeout 

type Timeout struct {
	// After is the amount of time that the test unit should complete within.
	// Specify a duration using Go's time duration string.
	// See https://pkg.go.dev/time#ParseDuration
	After string `yaml:"after,omitempty"`
}

Timeout contains information about the duration within which a Spec should run along with whether a deadline exceeded/timeout error should be expected or not.

func (*Timeout) Duration 

func (t *Timeout) Duration() time.Duration

Duration returns the time duration of the Timeout

type Timings added in v1.9.5 

type Timings struct {
	// GoTestTimeout will be the duration of the timeout specified (or
	// defaulted) by the Go test tool
	GoTestTimeout time.Duration
	// TotalWait will be non-zero when there is a wait specified for either the
	// scenario or a test spec and will contain the aggregate duration of all
	// waits
	TotalWait time.Duration
	// MaxTimeout will be non-zero when there is a timeout specified for either
	// the scenario or a test spec and will contain the duration of the maximum
	// timeout
	MaxTimeout time.Duration
	//TimeoutSetOn indicates where the MaxTimeout value was found
	MaxTimeoutSetOn SetOn
	// TimeoutSpecIndex indicates the test spec's index within the scenario where
	// the max timeout was found
	MaxTimeoutSpecIndex int
}

Timings contains information about a test scenario's maximum wait and timeout duration and what aspect of the scenario (the scenario defaults, a plugin default, a test spec override, etc) had the maximum timeout or wait value.

We use this information when initially assessing whether the Go test tool's overall timeout is shorter than this maximum in order to inform the user to increase the Go test tool timeout.

func (*Timings) AddTimeout added in v1.9.5 

func (t *Timings) AddTimeout(
	d time.Duration,
	on SetOn,
	specIndex int,
)

AddTimeout adds a timeout duration to the Timings and (re)-calculates the Timings' MaxTimeout attributes

func (*Timings) AddWait added in v1.9.5 

func (t *Timings) AddWait(
	d time.Duration,
)

AddWait adds a wait duration to the Timings and (re)-calculates the Timings' MaxWait attributes

type Wait 

type Wait struct {
	// Before is the amount of time that the test unit should wait before
	// executing its action.
	// Specify a duration using Go's time duration string.
	// See https://pkg.go.dev/time#ParseDuration
	Before string `yaml:"before,omitempty"`
	// After is the amount of time that the test unit should wait after
	// executing its action.
	// Specify a duration using Go's time duration string.
	// See https://pkg.go.dev/time#ParseDuration
	After string `yaml:"after,omitempty"`
}

Wait contains information about the duration within which a Spec should run along with whether a deadline exceeded/timeout error should be expected or not.

func (*Wait) AfterDuration 

func (w *Wait) AfterDuration() time.Duration

AfterDuration returns the time duration of the Wait.After

func (*Wait) BeforeDuration 

func (w *Wait) BeforeDuration() time.Duration

BeforeDuration returns the time duration of the Wait.Before

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.