test

type Butler func(data Data, helpers Helpers)

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
}

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

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

type ConfigKey string

type ConfigValue string

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
}

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
}

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

type Executor func(data Data, helpers Helpers) TestableCommand

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
}

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

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
}

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

type Requirement struct {
	// Check is expected to verify if the requirement is fulfilled, 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 reverse order that
	// requirements have been declared
	Cleanup Butler
}

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

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`)
	WithWrapper(binary string, args ...string)
	WithPseudoTTY(writers ...func(*os.File) error)
	// 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)
	// Signal sends a signal to a backgrounded command
	Signal(sig os.Signal) error
	// Stderr allows retrieving the raw stderr output of the command once it has been run
	Stderr() string
}