run

Documentation

Overview

Package run starts test runners and interprets their output.

Index

• func Run(ctx context.Context, cfg *Config) (status Status, results []*EntityResult)
• func WriteResults(ctx context.Context, cfg *Config, results []*EntityResult, complete bool) error
• type Config
  • func NewConfig(mode Mode, tastDir, trunkDir string) *Config
  • func (c *Config) Close(ctx context.Context) error
  • func (c *Config) DeriveDefaults() error
  • func (c *Config) SetFlags(f *flag.FlagSet)
• type EntityError
• type EntityResult
• type Mode
• type Status

Functions

func Run

func Run(ctx context.Context, cfg *Config) (status Status, results []*EntityResult)

Run executes or lists tests per cfg and returns the results. Messages are logged using cfg.Logger as the run progresses. If an error is encountered, status.ErrorMsg will be logged to cfg.Logger before returning, but the caller may wish to log it again later to increase its prominence if additional messages are logged.

func WriteResults

func WriteResults(ctx context.Context, cfg *Config, results []*EntityResult, complete bool) error

WriteResults writes results (including errors) to a JSON file in the results directory. It additionally logs each test's status to cfg.Logger. The cfg arg should be the same one that was passed to Run earlier. The complete arg should be true if the run finished successfully (regardless of whether any tests failed) and false if it was aborted. If cfg.CollectSysInfo is true, system information generated on the DUT during testing (e.g. logs and crashes) will also be written to the results dir.

Types

type Config

type Config struct {
	// Logger is used to log progress.
	Logger logging.Logger
	// KeyFile is the path to a private SSH key to use to connect to the target device.
	KeyFile string
	// KeyDir is a directory containing private SSH keys (typically $HOME/.ssh).
	KeyDir string
	// Target is the target device for testing, in the form "[<user>@]host[:<port>]".
	Target string
	// Patterns specifies which tests to operate against.
	Patterns []string
	// ResDir is the path to the directory where test results should be written.
	// It is only used for RunTestsMode.
	ResDir string
	// contains filtered or unexported fields
}

Config contains shared configuration information for running or listing tests.

func NewConfig

func NewConfig(mode Mode, tastDir, trunkDir string) *Config

NewConfig returns a new configuration for executing test runners in the supplied mode. It sets fields that are required by SetFlags. tastDir is the base directory under which files are written (e.g. /tmp/tast). trunkDir is the path to the Chrome OS checkout (within the chroot).

func (*Config) Close

func (c *Config) Close(ctx context.Context) error

Close releases the config's resources (e.g. cached SSH connections). It should be called at the completion of testing.

func (*Config) DeriveDefaults

func (c *Config) DeriveDefaults() error

DeriveDefaults sets default config values to unset members, possibly deriving from already set members. It should be called after non-default values are set to c.

func (*Config) SetFlags

func (c *Config) SetFlags(f *flag.FlagSet)

SetFlags adds common run-related flags to f that store values in Config.

type EntityError

type EntityError struct {
	// Time contains the time at which the error occurred (as reported by the test bundle).
	Time time.Time `json:"time"`
	// Error is an embedded struct describing the error.
	testing.Error
}

EntityError describes an error that occurred while running an entity. Most of its fields are defined in the Error struct in chromiumos/tast/testing. This struct just adds an additional "Time" field.

type EntityResult

type EntityResult struct {
	// EntityInfo contains basic information about the entity.
	testing.EntityInfo
	// Errors contains errors encountered while running the entity.
	// If it is empty, the entity passed.
	Errors []EntityError `json:"errors"`
	// Start is the time at which the entity started (as reported by the test bundle).
	Start time.Time `json:"start"`
	// End is the time at which the entity completed (as reported by the test bundle).
	// It may hold the zero value (0001-01-01T00:00:00Z) to indicate that the entity did not complete
	// (typically indicating that the test bundle, test runner, or DUT crashed mid-test).
	// In this case, at least one error will also be present indicating that the entity was incomplete.
	End time.Time `json:"end"`
	// OutDir is the directory into which entity output is stored.
	OutDir string `json:"outDir"`
	// SkipReason contains a human-readable explanation of why the test was skipped.
	// It is empty if the test actually ran.
	SkipReason string `json:"skipReason"`
}

EntityResult contains the results from a single entity. Fields are exported so they can be marshaled by the json package.

type Mode

type Mode int

Mode describes the action to perform.

const (
	// RunTestsMode indicates that tests should be run and their results reported.
	RunTestsMode Mode = iota
	// ListTestsMode indicates that tests should only be listed.
	ListTestsMode
)

type Status

type Status struct {
	// ExitCode contains the exit code that should be used by the tast process.
	ExitCode subcommands.ExitStatus
	// ErrorMsg describes the reason why the run failed.
	ErrorMsg string
	// FailedBeforeRun is true if a failure occurred before trying to run tests,
	// e.g. while compiling tests. If so, the caller shouldn't write a results dir.
	FailedBeforeRun bool
}

Status describes the result of a Run call.