runner

Documentation

Overview

Package runner provides functionality shared by test runners.

Test runners are executables that run one or more test bundles and aggregate the results. Runners are executed by the tast command.

local_test_runner executes local bundles on-device, while remote_test_runner executes remote bundles on the system where the tast command is running (e.g. a developer's workstation).

The tast command writes a JSON-marshaled RunnerArgs struct to a runner's stdin, which instructs the runner to report progress by writing JSON-marshaled control messages to stdout. In this mode, the runner exits with status code 0 in almost all cases (the one exception being malformed arguments), since the result of the run is already communicated via control messages.

When a test runner is executed manually in conjunction with command-line flags, the runner instead logs human-readable progress to stdout. The runner exits with a nonzero status code if an error is encountered.

Index

• Variables
• func Run(clArgs []string, stdin io.Reader, stdout, stderr io.Writer, scfg *StaticConfig) int
• type DeprecatedDirectRunConfig
  • func (c *DeprecatedDirectRunConfig) RunConfig(tests []string) *protocol.RunConfig
• type RunnerType
• type StaticConfig

Variables

var ErrFailedToReadFile = errors.New("failed to read file at the beginning")

ErrFailedToReadFile is used for indicating a file failed to open at the beginning.

Functions

func Run

func Run(clArgs []string, stdin io.Reader, stdout, stderr io.Writer, scfg *StaticConfig) int

Run reads command-line flags from clArgs and performs the requested action. clArgs should typically be os.Args[1:]. The caller should exit with the returned status code.

Types

type DeprecatedDirectRunConfig

type DeprecatedDirectRunConfig struct {
	// BundleGlob is a glob-style path matching test bundles to execute.
	BundleGlob string
	// DataDir is the path to the directory containing test data files.
	DataDir string
	// TempDir is the path to the directory under which temporary files for
	// tests are written.
	TempDir string

	// Patterns contains patterns (either empty to run all tests, exactly one attribute expression,
	// or one or more globs) describing which tests to run.
	Patterns []string
	// OutDir is the path to the base directory under which tests should write output files.
	OutDir string
	// Devservers contains URLs of devservers that can be used to download files.
	Devservers []string
	// WaitUntilReady indicates that the test bundle's "ready" function (see ReadyFunc) should
	// be executed before any tests are executed.
	WaitUntilReady bool
	// ConnectionSpec is the DUT connection spec as [<user>@]host[:<port>].
	// It is only relevant for remote tests.
	ConnectionSpec string
	// KeyFile is the path to the SSH private key to use to connect to the DUT.
	// It is only relevant for remote tests.
	KeyFile string
	// KeyDir is the directory containing SSH private keys (typically $HOME/.ssh).
	// It is only relevant for remote tests.
	KeyDir string
	// CheckDeps indicates whether test runners should skip tests whose
	// dependencies are not satisfied by available features.
	CheckDeps bool
	// AvailableSoftwareFeatures contains a list of software features supported by the DUT.
	AvailableSoftwareFeatures []string
	// UnavailableSoftwareFeatures contains a list of software features supported by the DUT.
	UnavailableSoftwareFeatures []string
}

DeprecatedDirectRunConfig contains configuration values used when the user executes a test runner directly to run tests.

DEPRECATED: Direct test execution is deprecated. Tast tests should be always initiated with Tast CLI.

func (*DeprecatedDirectRunConfig) RunConfig

func (c *DeprecatedDirectRunConfig) RunConfig(tests []string) *protocol.RunConfig

RunConfig generates protocol.RunConfig. Tests should be a resolved list of test names according to a.Patterns. Todo: Use primary dut for now, will add companion features in the future

type RunnerType

type RunnerType int // NOLINT

RunnerType describes the type of test runner that is using this package.

const (
	// LocalRunner indicates that this package is being used by local_test_runner.
	LocalRunner RunnerType = iota
	// RemoteRunner indicates that this package is being used by remote_test_runner.
	RemoteRunner
)

type StaticConfig

type StaticConfig struct {
	// Type describes the type of runner being executed.
	Type RunnerType

	// KillStaleRunners dictates whether SIGTERM should be sent to any existing test runner processes
	// when using RunnerRunTestsMode. This can help prevent confusing failures if multiple test jobs are
	// incorrectly scheduled on the same DUT: https://crbug.com/941829
	KillStaleRunners bool
	// EnableSyslog specifies whether to copy logs to syslog. It should be
	// always enabled on production, but can be disabled in unit tests to
	// avoid spamming syslog.
	EnableSyslog bool

	// GetDUTInfo is a function to respond to GetDUTInfo RPC.
	// If it is nil, an empty GetDUTInfoResponse is always returned.
	GetDUTInfo func(ctx context.Context, req *protocol.GetDUTInfoRequest) (*protocol.GetDUTInfoResponse, error)

	// GetSysInfoState is a function to respond to GetSysInfoState RPC.
	// If it is nil, an empty GetSysInfoStateResponse is always returned.
	GetSysInfoState func(ctx context.Context, req *protocol.GetSysInfoStateRequest) (*protocol.GetSysInfoStateResponse, error)

	// CollectSysInfo is a function to respond to CollectSysInfo RPC.
	// If it is nil, an empty CollectSysInfoResponse is always returned.
	CollectSysInfo func(ctx context.Context, req *protocol.CollectSysInfoRequest) (*protocol.CollectSysInfoResponse, error)

	// PrivateBundlesStampPath contains the path to a stamp file indicating private test bundles have been
	// successfully downloaded and installed before. This prevents downloading private test bundles for
	// every runner invocation.
	PrivateBundlesStampPath string

	// DeprecatedDirectRunDefaults is default configuration values used when
	// the user executes a test runner directly to run tests.
	//
	// DEPRECATED: Direct test execution is deprecated. Tast tests should be
	// always initiated with Tast CLI, in which case default values here are
	// ignored.
	DeprecatedDirectRunDefaults DeprecatedDirectRunConfig
}

StaticConfig contains fixed parameters for the runner that are passed in from local_test_runner or remote_test_runner.