runner

Documentation

Overview

Package runner provides helpers for compiling and running the Terramate binary with the intent of doing e2e tests. Additionally, it also provides functions for building and installing dependency binaries.

Index

• Variables
• func AssertRun(t *testing.T, got RunResult)
• func AssertRunResult(t *testing.T, got RunResult, want RunExpected)
• func BuildTerramate(projectRoot, binDir string) (string, error)
• func BuildTestHelper(projectRoot, binDir string) (string, error)
• func InstallTerraform(preferredVersion string) (string, string, func(), error)
• func PollBufferForMsgs(buf *buffer, done chan error, wantMsgs ...string) error
• func RemoveEnv(environ []string, names ...string) []string
• func SendUntilMsgIsReceived(t *testing.T, cmd *Cmd, signal os.Signal, msgs ...string)
• func Setup(projectRoot string) (err error)
• func Teardown()
• type CLI
  • func NewCLI(t *testing.T, chdir string, env ...string) CLI
  • func NewInteropCLI(t *testing.T, chdir string, env ...string) CLI
  • func (tm CLI) ListChangedStacks(args ...string) RunResult
  • func (tm CLI) ListStacks(args ...string) RunResult
  • func (tm CLI) NewCmd(args ...string) *Cmd
  • func (tm *CLI) NewRunFixture(mode RunMode, rootdir string, flags ...string) RunFixture
  • func (tm *CLI) PrependToPath(dir string)
  • func (tm CLI) Run(args ...string) RunResult
  • func (tm CLI) RunScript(args ...string) RunResult
  • func (tm CLI) RunWithStdin(stdin string, args ...string) RunResult
  • func (tm *CLI) SetWorkingDir(dir string)
  • func (tm CLI) StacksRunGraph(args ...string) RunResult
  • func (tm CLI) Trigger(flags ...string) RunResult
  • func (tm CLI) TriggerRecursively(kind trigger.Kind, base string) RunResult
  • func (tm CLI) TriggerStack(kind trigger.Kind, stack string) RunResult
• type Cmd
  • func (tc *Cmd) ExitCode() int
  • func (tc *Cmd) Run() error
  • func (tc *Cmd) Setpgid()
  • func (tc *Cmd) SignalGroup(s os.Signal)
  • func (tc *Cmd) Start()
  • func (tc *Cmd) Wait() error
• type RunExpected
• type RunFixture
  • func (run *RunFixture) Run() RunResult
• type RunMode
• type RunResult

Variables

var HelperPath string

HelperPath is the path to the test binary we compiled for test purposes

var HelperPathAsHCL string

HelperPathAsHCL is the path to the test binary but as a safe HCL expression that's valid in all supported OSs.

var TerraformTestPath string

TerraformTestPath is the path to the installed terraform binary.

var TerraformVersion string

TerraformVersion is the detected or installed Terraform version.

Functions

func AssertRun

func AssertRun(t *testing.T, got RunResult)

AssertRun asserts that the provided run result is successfully and with no output.

func AssertRunResult

func AssertRunResult(t *testing.T, got RunResult, want RunExpected)

AssertRunResult asserts that the result matches the expected.

func BuildTerramate

func BuildTerramate(projectRoot, binDir string) (string, error)

BuildTerramate build the Terramate binary from the current filesystem tree provided in the projectRoot directory. The binary is built into the provided binDir directory. The projectRoot is also used to compute the Terramate main package.

func BuildTestHelper

func BuildTestHelper(projectRoot, binDir string) (string, error)

BuildTestHelper builds the helper tool from the provided projectRoot directory into the binDir directory. The projectRoot is also used to compute the helper main package.

func InstallTerraform

func InstallTerraform(preferredVersion string) (string, string, func(), error)

InstallTerraform installs Terraform (if needed). The preferredVersion is used if terraform is not yet installed.

func PollBufferForMsgs

func PollBufferForMsgs(buf *buffer, done chan error, wantMsgs ...string) error

PollBufferForMsgs will check if each message is present on the buffer on signal handling sometimes we get extraneous signals on the test process like "urgent I/O condition". This function will ignore any unknown messages in between but check that at least all msgs where received in the provided order (but ignoring unknown messages in between).

func RemoveEnv

func RemoveEnv(environ []string, names ...string) []string

RemoveEnv removes an environment variable from the set.

func SendUntilMsgIsReceived

func SendUntilMsgIsReceived(t *testing.T, cmd *Cmd, signal os.Signal, msgs ...string)

SendUntilMsgIsReceived send a signal until the provided messages are read in the output.

func Setup

func Setup(projectRoot string) (err error)

Setup the e2e test runner.

func Teardown

func Teardown()

Teardown cleanup the runner files.

Types

type CLI

type CLI struct {
	Chdir    string
	LogLevel string

	AppendEnv []string
	// contains filtered or unexported fields
}

CLI is a Terramate CLI runner.

func NewCLI

func NewCLI(t *testing.T, chdir string, env ...string) CLI

NewCLI creates a new runner for the CLI.

func NewInteropCLI

func NewInteropCLI(t *testing.T, chdir string, env ...string) CLI

NewInteropCLI creates a new runner CLI suited for interop tests.

func (CLI) ListChangedStacks

func (tm CLI) ListChangedStacks(args ...string) RunResult

ListChangedStacks is a helper for executing `terramate list --changed`.

func (CLI) ListStacks

func (tm CLI) ListStacks(args ...string) RunResult

ListStacks is a helper for executinh `terramate list`.

func (CLI) NewCmd

func (tm CLI) NewCmd(args ...string) *Cmd

NewCmd creates a new terramate command prepared to executed.

func (*CLI) NewRunFixture

func (tm *CLI) NewRunFixture(mode RunMode, rootdir string, flags ...string) RunFixture

NewRunFixture returns a new runFixture ready to be executed which supports 3 execution modes:

• [NormalMode]
• HangRun
• SleepRun

In the case of HangRun mode, the steps below will happen:

1. The helper `hang` command is invoked.
2. The test will poll the stdout buffer waiting for a "ready" message.
3. When the process is ready, the testing will send CTRL-C twice and wait for the process acknowledge.
4. The test will wait for [hangTimeout] seconds for a graceful exit, otherwise the process is killed with SIGKILL.

In the case of SleepRun mode, the steps below will happen:

1. The helper `sleep` command is invoked.
2. The test will poll the stdout buffer waiting for a "ready" message.
3. When the process is ready, the testing will send a single CTRL-C.
4. The test will wait for process graceful exit.

Usage:

cli := NewCli(t, chdir)
fixture := NewRunFixture(hangRun, s.RootDir(), "--sync-deployment")
result = fixture.Run()
AssertRunResult(t, result, expected)

func (*CLI) PrependToPath

func (tm *CLI) PrependToPath(dir string)

PrependToPath prepend the provided directory to the OS's PATH environment variable in a portable way.

func (CLI) Run

func (tm CLI) Run(args ...string) RunResult

Run the cli command.

func (CLI) RunScript

func (tm CLI) RunScript(args ...string) RunResult

RunScript is a helper for executing `terramate run-script`.

func (CLI) RunWithStdin

func (tm CLI) RunWithStdin(stdin string, args ...string) RunResult

RunWithStdin runs the CLI but uses the provided string as stdin.

func (*CLI) SetWorkingDir

func (tm *CLI) SetWorkingDir(dir string)

SetWorkingDir sets the process working directory. Not to be confused with tm.Chdir which controls the `--chdir` flag.

func (CLI) StacksRunGraph

func (tm CLI) StacksRunGraph(args ...string) RunResult

StacksRunGraph is a helper for executing `terramate experimental run-graph`.

func (CLI) Trigger

func (tm CLI) Trigger(flags ...string) RunResult

Trigger is a helper for executing `terramate experimental trigger ...`.

func (CLI) TriggerRecursively

func (tm CLI) TriggerRecursively(kind trigger.Kind, base string) RunResult

TriggerRecursively is a helper for executing `terramate experimental trigger --recursively`.

func (CLI) TriggerStack

func (tm CLI) TriggerStack(kind trigger.Kind, stack string) RunResult

TriggerStack is a helper for executing `terramate experimental trigger`.

type Cmd

type Cmd struct {
	Stdin  *buffer
	Stdout *buffer
	Stderr *buffer
	// contains filtered or unexported fields
}

Cmd is a generic runner that can be used to run any command.

func (*Cmd) ExitCode

func (tc *Cmd) ExitCode() int

ExitCode returns the exit code for a finished command.

func (*Cmd) Run

func (tc *Cmd) Run() error

Run the command.

func (*Cmd) Setpgid

func (tc *Cmd) Setpgid()

Setpgid sets the pgid process attribute. When set, the command will execute in a new process group id.

func (*Cmd) SignalGroup

func (tc *Cmd) SignalGroup(s os.Signal)

SignalGroup sends the signal to all processes part of the cmd group.

func (*Cmd) Start

func (tc *Cmd) Start()

Start the command.

func (*Cmd) Wait

func (tc *Cmd) Wait() error

Wait for the command completion.

type RunExpected

type RunExpected struct {
	Stdout      string
	Stderr      string
	StdoutRegex string
	StderrRegex string

	StdoutRegexes []string
	StderrRegexes []string

	NoStdoutRegex   string
	NoStdoutRegexes []string

	NoStderrRegex   string
	NoStderrRegexes []string

	IgnoreStdout bool
	IgnoreStderr bool

	FlattenStdout bool
	Status        int
}

RunExpected specifies the expected result for the CLI execution.

type RunFixture

type RunFixture struct {
	Command []string
	// contains filtered or unexported fields
}

RunFixture defines a runner fixture for specialized modes of run.

func (*RunFixture) Run

func (run *RunFixture) Run() RunResult

Run the fixture.

type RunMode

type RunMode int

RunMode is a run mode for the command.

const (
	// NormalRun executes any command and wait for its completion.
	NormalRun RunMode = iota
	// HangRun executes an specialized command which never terminates and ignore all signals.
	HangRun
	// SleepRun executes an specialized command which sleeps for a configured amount of seconds.
	SleepRun
)

type RunResult

type RunResult struct {
	Cmd    string
	Stdout string
	Stderr string
	Status int
}

RunResult specify the result of executing the cli.