test

package
v2.0.0 Latest Latest
Warning

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

 Go to latest Published: Nov 6, 2024 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Index

Constants

View Source 
const ExitCodeGenericFail = -1
View Source 
const ExitCodeNoCheck = -2

Variables

View Source 
var Amd64 = Arch("amd64")
View Source 
var Arm64 = Arch("arm64")
View Source 
var Darwin = OS("darwin")
View Source 
var ErrPTYFailure = errors.New("pty failure")
View Source 
var ErrPTYUnsupportedPlatform = errors.New("pty not supported on this platform")
View Source 
var Linux = OS("linux")
View Source 
var Windows = OS("windows")

Functions

func Customize 

func Customize(testable Testable)

func Open 

func Open() (pty, tty *os.File, err error)

func RandomStringBase64 

func RandomStringBase64(n int) string

RandomStringBase64 generates a base64 encoded random string

Types

type Butler 

type Butler func(data Data, helpers Helpers)

A Butler is the function signature meant to be attached to a Setup or Cleanup routine for a Case or Requirement

type Case 

type Case struct {
	// Description contains a human-readable short desc, used as a seed for the identifier and as a title for the test
	Description string
	// NoParallel disables parallel execution if set to true
	// This obviously implies that all tests run in parallel, by default. This is a design choice.
	NoParallel bool
	// Env contains a map of environment variables to use as a base for all commands run in Setup, Command and Cleanup
	// Note that the environment is inherited by subtests
	Env map[string]string
	// Data contains test specific data, accessible to all operations, also inherited by subtests
	Data Data
	// Config contains specific information meaningful to the binary being tested.
	// It is also inherited by subtests
	Config Config

	// Requirement
	Require *Requirement
	// Setup
	Setup Butler
	// Command
	Command Executor
	// Expected
	Expected Manager
	// Cleanup
	Cleanup Butler

	// SubTests
	SubTests []*Case
	// contains filtered or unexported fields
}

Case describes an entire test-case, including data, setup and cleanup routines, command and expectations

func (*Case) Run 

func (test *Case) Run(t *testing.T)

Run prepares and executes the test, and any possible subtests

type Comparator 

type Comparator func(stdout string, info string, t *testing.T)

A Comparator is the function signature to implement for the Output property of an Expected

func All 

func All(comparators ...Comparator) Comparator

All can be used as a parameter for expected.Output to group a set of comparators

func Contains 

func Contains(compare string) Comparator

Contains can be used as a parameter for expected.Output and ensures a comparison string is found contained in the output

func DoesNotContain 

func DoesNotContain(compare string) Comparator

DoesNotContain is to be used for expected.Output to ensure a comparison string is NOT found in the output

func Equals 

func Equals(compare string) Comparator

Equals is to be used for expected.Output to ensure it is exactly the output

func Match 

func Match(reg *regexp.Regexp) Comparator

Provisional - expected use, but have not seen it so far Match is to be used for expected.Output to ensure we match a regexp

type Config 

type Config interface {
	// Write
	Write(key ConfigKey, value ConfigValue) Config
	// Read
	Read(key ConfigKey) ConfigValue
}

Config is meant to hold information relevant to the binary (eg: flags defining certain behaviors, etc.)

func WithConfig 

func WithConfig(key ConfigKey, value ConfigValue) Config

WithConfig returns a config object with a certain config property set

type ConfigKey 

type ConfigKey string

type ConfigValue 

type ConfigValue string

type CustomizableCommand 

type CustomizableCommand interface {
	TestableCommand

	PrependArgs(args ...string)
	// WithBlacklist allows to filter out unwanted variables from the embedding environment - default it pass any that is
	// defined by WithEnv
	WithBlacklist(env []string)
	// contains filtered or unexported methods
}

///////////////////////////////////////////// CustomizableCommand is an interface meant for people who want to heavily customize the base command of their test case It is passed along

type Data 

type Data interface {
	// Get returns the value of a certain key for custom data
	Get(key string) string
	// Set will save `value` for `key`
	Set(key string, value string) Data

	// Identifier returns the test identifier that can be used to name resources
	Identifier(suffix ...string) string
	// TempDir returns the test temporary directory
	TempDir() string
}

Data is meant to hold information about a test: - first, any random key value data that the test implementer wants to carry / modify - this is test data - second, some commonly useful immutable test properties (a way to generate unique identifiers for that test, temporary directory, etc.) Note that Data is inherited, from parent test to subtest (except for Identifier and TempDir of course)

func WithData 

func WithData(key string, value string) Data

WithData returns a data object with a certain key value set

type Evaluator 

type Evaluator func(data Data, helpers Helpers) (bool, string)

An Evaluator is a function that decides whether a test should run or not

type Executor 

type Executor func(data Data, helpers Helpers) TestableCommand

An Executor is the function signature meant to be attached to the Command property of a Case

func Command 

func Command(args ...string) Executor

RunCommand is the simplest way to express a test.TestableCommand for very basic cases when access to test data is not necessary

type Expected 

type Expected struct {
	// ExitCode
	ExitCode int
	// Errors contains any error that (once serialized) should be seen in stderr
	Errors []error
	// Output function to match against stdout
	Output Comparator
}

Expected expresses the expected output of a command

type GenericCommand 

type GenericCommand struct {
	Config  Config
	TempDir string
	Env     map[string]string
	// contains filtered or unexported fields
}

GenericCommand is a concrete Command implementation

func (*GenericCommand) Background 

func (gc *GenericCommand) Background(timeout time.Duration)

func (*GenericCommand) Clone 

func (gc *GenericCommand) Clone() TestableCommand

func (*GenericCommand) PrependArgs 

func (gc *GenericCommand) PrependArgs(args ...string)

func (*GenericCommand) Run 

func (gc *GenericCommand) Run(expect *Expected)

func (*GenericCommand) Stderr 

func (gc *GenericCommand) Stderr() string

func (*GenericCommand) T 

func (gc *GenericCommand) T() *testing.T

func (*GenericCommand) WithArgs 

func (gc *GenericCommand) WithArgs(args ...string)

func (*GenericCommand) WithBinary 

func (gc *GenericCommand) WithBinary(binary string)

func (*GenericCommand) WithBlacklist 

func (gc *GenericCommand) WithBlacklist(env []string)

func (*GenericCommand) WithCwd 

func (gc *GenericCommand) WithCwd(path string)

func (*GenericCommand) WithPseudoTTY 

func (gc *GenericCommand) WithPseudoTTY()

func (*GenericCommand) WithStdin 

func (gc *GenericCommand) WithStdin(r io.Reader)

func (*GenericCommand) WithWrapper 

func (gc *GenericCommand) WithWrapper(binary string, args ...string)

type Helpers 

type Helpers interface {
	// Ensure runs a command and verifies it is succeeding
	Ensure(args ...string)
	// Anyhow runs a command and ignores its result
	Anyhow(args ...string)
	// Fail runs a command and verifies it failed
	Fail(args ...string)
	// Capture runs a command, verifies it succeeded, and returns stdout
	Capture(args ...string) string
	// Err runs a command, and returns stderr regardless of its outcome
	// This is mostly useful for debugging
	Err(args ...string) string

	// Command will return a populated command from the default internal command, with the provided arguments,
	// ready to be Run or further configured
	Command(args ...string) TestableCommand
	// Custom will return a bare command, without configuration nor defaults (still has the Env)
	Custom(binary string, args ...string) TestableCommand

	// Read return the config value associated with a key
	Read(key ConfigKey) ConfigValue
	// Write saves a value in the config
	Write(key ConfigKey, value ConfigValue)

	// T returns the current testing object
	T() *testing.T
}

Helpers provides a set of helpers to run commands with simple expectations, available at all stages of a test (Setup, Cleanup, etc...)

type Manager 

type Manager func(data Data, helpers Helpers) *Expected

A Manager is the function signature to be run to produce expectations to be fed to a command

func Expects 

func Expects(exitCode int, errors []error, output Comparator) Manager

Expects is provided as a simple helper covering "expectations" for simple use-cases where access to the test data is not necessary

type Requirement 

type Requirement struct {
	// Check is expected to perform random operations and return a boolean and an explanatory message
	Check Evaluator
	// Setup, if provided, will be run before any test-specific Setup routine, in the order that requirements have been declared
	Setup Butler
	// Cleanup, if provided, will be run after any test-specific Cleanup routine, in the revers order that requirements have been declared
	Cleanup Butler
}

A Requirement offers a way to verify random conditions to decide if a test should be skipped or run. It can furthermore (optionally) provide custom Setup and Cleanup routines.

func Arch 

func Arch(arch string) *Requirement

func Binary 

func Binary(name string) *Requirement

func Not 

func Not(requirement *Requirement) *Requirement

func OS 

func OS(os string) *Requirement

func Require 

func Require(requirements ...*Requirement) *Requirement

type Testable 

type Testable interface {
	CustomCommand(testCase *Case, t *testing.T) CustomizableCommand
	AmbientRequirements(testCase *Case, t *testing.T)
}

type TestableCommand 

type TestableCommand interface {
	// WithBinary specifies what binary to execute
	WithBinary(binary string)
	// WithArgs specifies the args to pass to the binary. Note that WithArgs can be used multiple times and is additive.
	WithArgs(args ...string)
	// WithWrapper allows wrapping a command with another command (for example: `time`, `unbuffer`)
	WithWrapper(binary string, args ...string)
	// WithPseudoTTY
	WithPseudoTTY()
	// WithStdin allows passing a reader to be used for stdin for the command
	WithStdin(r io.Reader)
	// WithCwd allows specifying the working directory for the command
	WithCwd(path string)
	// Clone returns a copy of the command
	Clone() TestableCommand

	// Run does execute the command, and compare the output with the provided expectation.
	// Passing nil for `Expected` will just run the command regardless of outcome.
	// An empty `&Expected{}` is (of course) equivalent to &Expected{Exit: 0}, meaning the command is verified to be
	// successful
	Run(expect *Expected)
	// Background allows starting a command in the background
	Background(timeout time.Duration)
	// Stderr allows retrieving the raw stderr output of the command
	Stderr() string
}

The TestableCommand interface represents a low-level command to execute, typically to be compared with an Expected A TestableCommand can be used as a Case Command obviously, but also as part of a Setup or Cleanup routine, and as the basis of any type of helper. For more powerful usecase outside of test cases, see below CustomizableCommand

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.