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 Args 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

Constants

View Source
const (
	// RunTestsMode indicates that the runner should run all matched tests.
	RunTestsMode RunMode = 0
	// ListTestsMode indicates that the runner should write information about matched tests to stdout as a
	// JSON array of testing.Test structs and exit.
	ListTestsMode = 2
	// GetSysInfoStateMode indicates that the runner should write a JSON-marshaled GetSysInfoStateResult struct
	// to stdout and exit. It's used by the tast executable to get the initial state of the system before tests
	// are executed. This mode is only supported by local_test_runner.
	GetSysInfoStateMode = 3
	// CollectSysInfoMode indicates that the runner should collect system information that was written in the
	// course of testing and write a JSON-marshaled CollectSysInfoResult struct to stdout and exit. It's used by
	// the tast executable to get system info after testing is completed.
	// This mode is only supported by local_test_runner.
	CollectSysInfoMode = 4
	// GetDUTInfoMode indicates that the runner should return DUT information via a JSON-marshaled
	// GetDUTInfoResult struct written to stdout. This mode is only supported by local_test_runner.
	GetDUTInfoMode = 5
	// DownloadPrivateBundlesMode indicates that the runner should download private bundles from devservers,
	// install them to the DUT, write a JSON-marshaled DownloadPrivateBundlesResult struct to stdout and exit.
	// This mode is only supported by local_test_runner.
	DownloadPrivateBundlesMode = 6
	// ListFixturesMode indicates that the runner should write information about fixtures to stdout
	// as a JSON serialized ListFixturesResult.
	ListFixturesMode = 7
)
View Source
const (
	// Intel family
	INTEL_FAM6_CORE_YONAH           = 0xe
	INTEL_FAM6_CORE2_MEROM          = 0xf
	INTEL_FAM6_CORE2_MEROM_L        = 0x16
	INTEL_FAM6_CORE2_PENRYN         = 0x17
	INTEL_FAM6_NEHALEM_EP           = 0x1a
	INTEL_FAM6_ATOM_BONNELL         = 0x1c
	INTEL_FAM6_CORE2_DUNNINGTON     = 0x1d
	INTEL_FAM6_NEHALEM              = 0x1e
	INTEL_FAM6_NEHALEM_G            = 0x1f
	INTEL_FAM6_WESTMERE             = 0x25
	INTEL_FAM6_ATOM_BONNELL_MID     = 0x26
	INTEL_FAM6_ATOM_SALTWELL_MID    = 0x27
	INTEL_FAM6_SANDYBRIDGE          = 0x2a
	INTEL_FAM6_WESTMERE_EP          = 0x2c
	INTEL_FAM6_SANDYBRIDGE_X        = 0x2d
	INTEL_FAM6_NEHALEM_EX           = 0x2e
	INTEL_FAM6_WESTMERE_EX          = 0x2f
	INTEL_FAM6_ATOM_SALTWELL_TABLET = 0x35
	INTEL_FAM6_ATOM_SALTWELL        = 0x36
	INTEL_FAM6_ATOM_SILVERMONT      = 0x37
	INTEL_FAM6_IVYBRIDGE            = 0x3a
	INTEL_FAM6_HASWELL              = 0x3c
	INTEL_FAM6_BROADWELL            = 0x3d
	INTEL_FAM6_IVYBRIDGE_X          = 0x3e
	INTEL_FAM6_HASWELL_X            = 0x3f
	INTEL_FAM6_HASWELL_L            = 0x45
	INTEL_FAM6_HASWELL_G            = 0x46
	INTEL_FAM6_BROADWELL_G          = 0x47
	INTEL_FAM6_ATOM_SILVERMONT_MID  = 0x4a
	INTEL_FAM6_ATOM_AIRMONT         = 0x4c
	INTEL_FAM6_ATOM_SILVERMONT_D    = 0x4d
	INTEL_FAM6_SKYLAKE_L            = 0x4e
	INTEL_FAM6_BROADWELL_X          = 0x4f
	INTEL_FAM6_SKYLAKE_X            = 0x55
	INTEL_FAM6_BROADWELL_D          = 0x56
	INTEL_FAM6_XEON_PHI_KNL         = 0x57
	INTEL_FAM6_ATOM_AIRMONT_MID     = 0x5a
	INTEL_FAM6_ATOM_GOLDMONT        = 0x5c
	INTEL_FAM6_SKYLAKE              = 0x5e
	INTEL_FAM6_ATOM_GOLDMONT_D      = 0x5f
	INTEL_FAM6_CANNONLAKE_L         = 0x66
	INTEL_FAM6_ICELAKE_X            = 0x6a
	INTEL_FAM6_ICELAKE_D            = 0x6c
	INTEL_FAM6_ATOM_AIRMONT_NP      = 0x75
	INTEL_FAM6_ATOM_GOLDMONT_PLUS   = 0x7a
	INTEL_FAM6_ICELAKE              = 0x7d
	INTEL_FAM6_ICELAKE_L            = 0x7e
	INTEL_FAM6_XEON_PHI_KNM         = 0x85
	INTEL_FAM6_ATOM_TREMONT_D       = 0x86
	INTEL_FAM6_TIGERLAKE_L          = 0x8c
	INTEL_FAM6_TIGERLAKE            = 0x8d
	INTEL_FAM6_KABYLAKE_L           = 0x8e
	INTEL_FAM6_ATOM_TREMONT         = 0x96
	INTEL_FAM6_ATOM_TREMONT_L       = 0x9c
	INTEL_FAM6_ICELAKE_NNPI         = 0x9d
	INTEL_FAM6_KABYLAKE             = 0x9e
	INTEL_FAM6_COMETLAKE            = 0xa5
	INTEL_FAM6_COMETLAKE_L          = 0xa6
)

Variables

This section is empty.

Functions

func Run

func Run(clArgs []string, stdin io.Reader, stdout, stderr io.Writer, args *Args, cfg *Config) int

Run reads command-line flags from clArgs (in the case of a manual run) or a JSON-marshaled Args struct from stdin (when run by the tast command) and performs the requested action. Default arguments may be passed via args, which is filled with the additional args that are read. clArgs should typically be os.Args[1:]. The caller should exit with the returned status code.

Types

type Args

type Args struct {
	// Mode describes the mode that should be used by the runner.
	Mode RunMode `json:"mode"`

	// RunTests contains arguments used by RunTestsMode.
	RunTests *RunTestsArgs `json:"runTests,omitempty"`
	// ListTests contains arguments used by ListTestsMode.
	ListTests *ListTestsArgs `json:"listTests,omitempty"`
	// ListFixtures contains arguments used by ListFixturesMode.
	ListFixtures *ListFixturesArgs `json:"listFixtures,omitempty"`
	// CollectSysInfo contains arguments used by CollectSysInfoMode.
	CollectSysInfo *CollectSysInfoArgs `json:"collectSysInfo,omitempty"`
	// GetDUTInfo contains arguments used by GetDUTInfoMode.
	// Note that, for backward compatibility, the JSON's field name is getSoftwareFeatures.
	GetDUTInfo *GetDUTInfoArgs `json:"getSoftwareFeatures,omitempty"`
	// DownloadPrivateBundles contains arguments used by DownloadPrivateBundlesMode.
	DownloadPrivateBundles *DownloadPrivateBundlesArgs `json:"downloadPrivateBundles,omitempty"`
	// contains filtered or unexported fields
}

Args provides a backward- and forward-compatible way to pass arguments from the tast executable to test runners. The tast executable writes the struct's JSON-serialized representation to the runner's stdin.

func (*Args) FillDeprecated

func (a *Args) FillDeprecated()

FillDeprecated backfills deprecated fields from the corresponding non-deprecated fields. This method is called by the tast process to ensure that args will be interpreted correctly by older test runners.

func (*Args) PromoteDeprecated

func (a *Args) PromoteDeprecated()

PromoteDeprecated copies all non-zero-valued deprecated fields to the corresponding non-deprecated fields. Missing sub-structs (e.g. RunTestsArgs and ListTestsArgs) are initialized. This method is called by test runners to normalize args that were marshaled by an older tast executable.

If both an old and new field are set, the old field takes precedence. This is counter-intuitive but necessary: a default value for the new field may have been passed to Run. If the corresponding old field is non-zero, it was passed by an old tast executable (or by a new executable that called FillDeprecated), so we use the old field to make sure that it overrides the default.

type CollectSysInfoArgs

type CollectSysInfoArgs struct {
	// InitialState describes the pre-testing state of the DUT. It should be generated by a GetSysInfoStateMode
	// command executed before tests are run.
	InitialState SysInfoState `json:"initialState"`
}

CollectSysInfoArgs is nested within Args and holds arguments used by CollectSysInfoMode.

type CollectSysInfoResult

type CollectSysInfoResult struct {
	// LogDir is the directory where log files were copied. The caller should delete it.
	LogDir string `json:"logDir,omitempty"`
	// CrashDir is the directory where minidump crash files were copied. The caller should delete it.
	CrashDir string `json:"crashDir,omitempty"`
	// Warnings contains descriptions of non-fatal errors encountered while collecting data.
	Warnings []string `json:"warnings,omitempty"`
}

CollectSysInfoResult contains the result of a CollectSysInfoMode command.

type Config

type Config 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 RunTestsMode. This can help prevent confusing failures if multiple test jobs are
	// incorrectly scheduled on the same DUT: https://crbug.com/941829
	KillStaleRunners bool

	// SystemLogDir contains the directory where information is logged by syslog and other daemons.
	SystemLogDir string
	// SystemLogExcludes contains relative paths of directories and files in SystemLogDir to exclude.
	SystemLogExcludes []string
	// UnifiedLogSubdir contains the subdirectory within CollectSysInfoResult.LogDir where unified system logs will be written.
	// No system logs will be be collected if this is empty.
	UnifiedLogSubdir string `json:"-"`
	// SystemInfoFunc contains a function that will be executed to gather additional system info.
	// The information should be written to dir.
	SystemInfoFunc func(ctx context.Context, dir string) error
	// SystemCrashDirs contains directories where crash dumps are written when processes crash.
	SystemCrashDirs []string
	// CleanupLogsPausedPath is a path to the marker file on the DUT to pause log cleanup.
	CleanupLogsPausedPath string

	// USEFlagsFile contains the path to a file listing a subset of USE flags that were set when building
	// the system image. These USE flags are used by expressions in SoftwareFeatureDefinitions to determine
	// available software features.
	USEFlagsFile string
	// LSBReleaseFile contains the path to the lsb-release file to determine board name used for
	// the expressions in SoftwareFeatureDefinitions.
	LSBReleaseFile string
	// SoftwareFeatureDefinitions maps from software feature names (e.g. "myfeature") to boolean expressions
	// used to compose them from USE flags (e.g. "a && !(b || c)"). The USE flags used in these expressions
	// must be listed in USEFlagsFile if they were set when building the system image.
	// See chromiumos/tast/internal/expr for details about expression syntax.
	SoftwareFeatureDefinitions map[string]string
	// AutotestCapabilityDir contains the path to a directory containing autotest-capability YAML files used to
	// define the DUT's capabilities for the purpose of determining which video tests it is able to run.
	// See https://chromium.googlesource.com/chromiumos/overlays/chromiumos-overlay/+/master/chromeos-base/autotest-capability-default/
	// and the autocaps package for more information.
	AutotestCapabilityDir string
	// DefaultBuildArtifactsURL is the URL of Google Cloud Storage directory, ending with a slash,
	// containing build artifacts for the current Chrome OS image. It can be empty if the image is
	// not built by an official builder.
	DefaultBuildArtifactsURL string
	// 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
	// OSVersion contains the value of CHROMEOS_RELEASE_BUILDER_PATH in /etc/lsb-release
	// or combination of CHROMEOS_RELEASE_BOARD, CHROMEOS_RELEASE_CHROME_MILESTONE,
	// CHROMEOS_RELEASE_BUILD_TYPE and CHROMEOS_RELEASE_VERSION if CHROMEOS_RELEASE_BUILDER_PATH
	// is not available in /etc/lsb-release
	OSVersion string
}

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

type DownloadPrivateBundlesArgs

type DownloadPrivateBundlesArgs struct {
	// Devservers contains URLs of devservers that can be used to download files.
	Devservers []string `json:"devservers,omitempty"`

	// TLWServer contains host and port name of TLW server that can be used for downloading files.
	// When this is set, it takes precedence over Devservers.
	TLWServer string `json:"tlsServer,omitempty"`

	// DUTName contains the name of the DUT recognized by the TLW service.
	// This must be set when TLWServer is used.
	DUTName string `json:"dutName,omitempty"`

	// BuildArtifactsURL is the URL of Google Cloud Storage directory, ending with a slash,
	// containing build artifacts for the current Chrome OS image.
	// If it is empty, DefaultBuildArtifactsURL in runner.Config is used.
	BuildArtifactsURL string `json:"buildArtifactsUrl,omitempty"`
}

DownloadPrivateBundlesArgs is nested within Args and contains arguments used by DownloadPrivateBundlesMode.

type DownloadPrivateBundlesResult

type DownloadPrivateBundlesResult struct {
	// Messages contains log messages emitted while downloading test bundles.
	Messages []string `json:"logs,omitempty"`
}

DownloadPrivateBundlesResult contains the result of a DownloadPrivateBundlesMode command.

type GetDUTInfoArgs

type GetDUTInfoArgs struct {
	// ExtraUSEFlags lists USE flags that should be treated as being set an addition to
	// the ones read from Config.USEFlagsFile when computing the feature sets for GetDUTInfoResult.
	ExtraUSEFlags []string `json:"extraUseFlags,omitempty"`

	// RequestDeviceConfig specifies if GetDUTInfoMode should return a device.Config instance
	// generated from runtime DUT configuration.
	RequestDeviceConfig bool `json:"requestDeviceConfig,omitempty"`
}

GetDUTInfoArgs is nested within Args and contains arguments used by GetDUTInfoMode.

type GetDUTInfoResult

type GetDUTInfoResult struct {
	// SoftwareFeatures contains the information about the software features of the DUT.
	// For backward compatibility, in JSON format, fields are flatten.
	// This struct has MarshalJSON/UnmarshalJSON and the serialization/deserialization
	// of this field are handled in the methods respectively.
	SoftwareFeatures *dep.SoftwareFeatures `json:"-"`

	// DeviceConfig contains the DUT's device characteristic.
	// Similar to SoftwareFeatures field, the serialization/deserialization
	// of this field are handled in MarshalJSON/UnmarshalJSON respectively.
	DeviceConfig     *device.Config             `json:"-"`
	HardwareFeatures *configpb.HardwareFeatures `json:"-"`

	// OSVersion contains the DUT's OS Version
	OSVersion string `json:"osVersion,omitempty"`

	// Warnings contains descriptions of non-fatal errors encountered while determining features.
	Warnings []string `json:"warnings,omitempty"`
}

GetDUTInfoResult contains the result of a GetDUTInfoMode command.

func (*GetDUTInfoResult) MarshalJSON

func (r *GetDUTInfoResult) MarshalJSON() ([]byte, error)

MarshalJSON marshals the given GetDUTInfoResult with handing protocol backward compatibility.

func (*GetDUTInfoResult) UnmarshalJSON

func (r *GetDUTInfoResult) UnmarshalJSON(b []byte) error

UnmarshalJSON unmarshals the given b to this r object with handing protocol backward compatibility.

type GetSysInfoStateResult

type GetSysInfoStateResult struct {
	// SysInfoState contains the collected state.
	State SysInfoState `json:"state"`
	// Warnings contains descriptions of non-fatal errors encountered while collecting data.
	// Each warning can be logged directly without additional information.
	Warnings []string `json:"warnings,omitempty"`
}

GetSysInfoStateResult holds the result of a GetSysInfoStateMode command.

type ListFixturesArgs

type ListFixturesArgs struct {
	// BundleGlob is a glob-style path matching test bundles to execute.
	BundleGlob string `json:"bundleGlob,omitempty"`
}

ListFixturesArgs is nested within Args and contains arguments used by ListFixturesMode.

type ListFixturesResult

type ListFixturesResult struct {
	// Fixtures maps bundle path to the fixtures it contains.
	Fixtures map[string][]*testing.FixtureInfo `json:"fixtures,omitempty"`
}

ListFixturesResult holds the result of a ListFixturesMode command.

type ListTestsArgs

type ListTestsArgs struct {
	// BundleArgs contains arguments that are relevant to test bundles.
	BundleArgs bundle.ListTestsArgs `json:"bundleArgs"`
	// BundleGlob is a glob-style path matching test bundles to execute.
	BundleGlob string `json:"bundleGlob,omitempty"`
}

ListTestsArgs is nested within Args and contains arguments used by ListTestsMode.

type RunMode

type RunMode int

RunMode describes the runner's behavior.

type RunTestsArgs

type RunTestsArgs struct {
	// BundleArgs contains arguments that are relevant to test bundles.
	BundleArgs bundle.RunTestsArgs `json:"bundleArgs"`
	// BundleGlob is a glob-style path matching test bundles to execute.
	BundleGlob string `json:"bundleGlob,omitempty"`
	// Devservers contains URLs of devservers that can be used to download files.
	Devservers []string `json:"devservers,omitempty"`
	// BuildArtifactsURLDeprecated is the URL of Google Cloud Storage directory, ending with a slash,
	// containing build artifacts for the current Chrome OS image.
	// If it is empty, DefaultBuildArtifactsURL in runner.Config is used.
	// DEPRECATED: Use bundle.RunTestsArgs.BuildArtifactsURL instead.
	BuildArtifactsURLDeprecated string `json:"buildArtifactsUrl,omitempty"`
}

RunTestsArgs is nested within Args and contains arguments used by RunTestsMode.

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 SysInfoState

type SysInfoState struct {
	// LogInodeSizes maps from each log file's inode to its size in bytes.
	LogInodeSizes map[uint64]int64 `json:"logInodeSizes,omitempty"`
	// UnifiedLogCursor contains an opaque cursor pointing at the current tip of unified system logs.
	// The name of json field is "journaldCursor" for historical reason.
	UnifiedLogCursor string `json:"journaldCursor,omitempty"`
	// MinidumpPaths contains absolute paths to minidump crash files.
	MinidumpPaths []string `json:"minidumpPaths,omitempty"`
}

SysInfoState contains the state of the DUT's system information.

Directories

Path Synopsis
gen Package main implements a script for writing a Go source file containing intel family constants.