command

Documentation

Overview

Package command defines the behavior of commands invoked by project configuration files.

Index

• Constants
• func GetFullDisplayName(cmdName, displayName string, blockInfo BlockInfo, funcInfo FunctionInfo) string
• func GetWorkingDirectory(conf *internal.TaskConfig, path string) string
• func RegisterCommand(name string, factory CommandFactory) error
• func RegisteredCommandNames() []string
• func ToModelTestResults(results []*goTestResult, suiteName string) []testresult.TestResult
• type BlockInfo
• type BlockType
• type Command
  • func MockCommandFactory() Command
  • func Render(c model.PluginCommandConf, project *model.Project, blockInfo BlockInfo) ([]Command, error)
• type CommandFactory
  • func GetCommandFactory(name string) (CommandFactory, bool)
• type FunctionInfo

Constants

const (
	PASS = "PASS"
	FAIL = "FAIL"
	SKIP = "SKIP"
)

Functions

func GetFullDisplayName

func GetFullDisplayName(cmdName, displayName string, blockInfo BlockInfo, funcInfo FunctionInfo) string

GetFullDisplayName returns the full, unambiguous display name for a command. cmdName is the type of command (e.g. shell.exec), displayName is the human-readable display name (if specified), or the command name (if no display name is given). blockInfo and funcInfo include contextual information about the block/func that the command is running in.

func GetWorkingDirectory

func GetWorkingDirectory(conf *internal.TaskConfig, path string) string

GetWorkingDirectory joins the conf.WorkDir A with B like this:

if B is relative, return A+B.
if B is absolute, return B.

We use this because B might be absolute.

func RegisterCommand

func RegisterCommand(name string, factory CommandFactory) error

func RegisteredCommandNames

func RegisteredCommandNames() []string

func ToModelTestResults

func ToModelTestResults(results []*goTestResult, suiteName string) []testresult.TestResult

ToModelTestResults converts the implementation of LocalTestResults native to the goTest plugin to the implementation used by MCI tasks.

Types

type BlockInfo

type BlockInfo struct {
	// Block is the name of the block that the command is part of.
	Block BlockType
	// CmdNum is the ordinal of a command in the block.
	CmdNum int
	// TotalCmds is the total number of commands in the block.
	TotalCmds int
}

BlockInfo contains information about the enclosing block in which a function or standalone command runs. For example, this would contain information about the pre block that contains a particular shell.exec command.

type BlockType

type BlockType string

BlockType is the name of the block that a command runs in.

const (
	MainTaskBlock      BlockType = ""
	TaskTimeoutBlock   BlockType = "timeout"
	PreBlock           BlockType = "pre"
	SetupTaskBlock     BlockType = "setup_task"
	TeardownTaskBlock  BlockType = "teardown_task"
	SetupGroupBlock    BlockType = "setup_group"
	TeardownGroupBlock BlockType = "teardown_group"
	PostBlock          BlockType = "post"
	TaskSyncBlock      BlockType = "task_sync"
)

type Command

type Command interface {
	// ParseParams takes a map of fields to values extracted from
	// the project config and passes them to the command. Any
	// errors parsing the information are returned.
	ParseParams(map[string]interface{}) error

	// Execute runs the command using the agent's logger, communicator,
	// task config, and a channel for interrupting long-running commands.
	// Execute is called after ParseParams.
	Execute(context.Context, client.Communicator, client.LoggerProducer, *internal.TaskConfig) error

	// Name is the name of the command.
	Name() string

	// Type returns the command's type (e.g. system or test).
	Type() string
	// SetType sets the command's type (e.g. system or test).
	SetType(string)

	// FullDisplayName is the full display name for the command. The full
	// command name includes the command name (including the type of command and
	// the user-defined display name if any) as well as other relevant context
	// like the function and block the command runs in.
	FullDisplayName() string
	SetFullDisplayName(string)

	// IdleTimeout is the user-configurable timeout for how long an individual
	// command can run without writing output to the task logs. If the command
	// hits this timeout, then it will time out and stop early.
	// This timeout only applies in certain blocks, such as pre, setup group,
	// setup task, and the main task block.
	IdleTimeout() time.Duration
	SetIdleTimeout(time.Duration)

	// JasperManager is the Jasper process manager for the command. Jasper can
	// be used to run and manage processes that are started within commands.
	JasperManager() jasper.Manager
	SetJasperManager(jasper.Manager)

	// RetryOnFailure indicates whether the entire task should be retried if this command fails.
	RetryOnFailure() bool
	SetRetryOnFailure(bool)

	// FailureMetadataTags are user-defined tags which are not used directly by
	// Evergreen but can be used to allow users to set additional metadata about
	// the command/function if it fails.
	FailureMetadataTags() []string
	SetFailureMetadataTags([]string)
}

Command is an interface that defines a command A Command takes parameters as a map, and is executed after those parameters are parsed.

func MockCommandFactory

func MockCommandFactory() Command

MockCommandFactory is a factory used to produce a mock command for testing. should not be used in production.

func Render

func Render(c model.PluginCommandConf, project *model.Project, blockInfo BlockInfo) ([]Command, error)

Render takes a command specification and returns the commands to actually run. It resolves the command specification into either a single command (in the case of standalone command) or a list of commands (in the case of a function).

type CommandFactory

type CommandFactory func() Command

func GetCommandFactory

func GetCommandFactory(name string) (CommandFactory, bool)

type FunctionInfo

type FunctionInfo struct {
	// Function is the name of the function that the command is part of.
	Function string
	// SubCmdNum is the ordinal of the command within the function.
	SubCmdNum int
	// TotalSubCmds is the total number of sub-commands within the function.
	TotalSubCmds int
}

FunctionInfo contains information about the enclosing function in which a command runs. For example, this would contain information about the second shell.exec that runs in a function.