testing

package
v0.0.0-...-15a9a0c Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 19, 2023 License: BSD-3-Clause Imports: 36 Imported by: 0

Documentation

Overview

Package testing implements public framework APIs, as well as framework-internal facility to run an entity.

An entity is a piece of user code registered to the framework with metadata. Currently there are three types of entities: tests, fixtures, and services. Entities are registered to the framework by calling testing.Add* at the test bundle initialization time. Entity metadata contain various information the framework needs to know to call into an entity properly. For example: an entity name is used to mention it in other entities' metadata and command line arguments; dependencies (data files, services, ...) specify requirements that must be prepared before running an entity. When a test bundle is started, the framework builds an execution plan of entities according to the request, and prepare necessary dependencies before calling into entities.

A semi-entity is a piece of user code known indirectly to the framework without explicit registration. Currently there are three types of semi-entities: preconditions, test hooks, and subtests. Since semi-entities are not explicitly registered to the framework, they do not have associated metadata. As an important consequence, semi-entities can't declare their own dependencies.

Entities and semi-entities are implemented either as a simple user function or an interface (that is, a set of user functions). The framework typically calls into user functions with two arguments: context.Context and testing.*State (the exact State type varies).

context.Context is associated with an entity for which a user function is called. Note that an associated entity might not be the one closest to a function being called, in terms of code location; for example, context.Context passed to a gRPC service method is associated with a test or a fixture calling into the method, not the service implementing the method. One can call testing.Context* functions with a given context to query an entity metadata (e.g. testcontext.ServiceDeps), or emit logs for an entity (testing.ContextLog).

A new State object is created by the framework every time on calling into a (semi-)entity. This means that there might be multiple State objects for an entity at a time. To maintain states common to multiple State objects for the same entity, a single EntityRoot object (and additionally a TestEntityRoot object in the case of a test) is allocated. Root objects are private to the framework, and user code always access Root objects indirectly via State objects.

Since there are many State types that provide similar but different sets of methods, State types typically embed mix-in types that actually implements API methods.

Index

Constants

View Source 
const (
	// ExternalLinkSuffix is a file name suffix for external data link files.
	// These are JSON files that can be unmarshaled into the externalLink struct.
	ExternalLinkSuffix = ".external"

	// ExternalErrorSuffix is a file name suffix for external data download error files.
	// An error message is written to the file when we encounter an error downloading
	// the corresponding external data file. This mechanism is used to pass errors from
	// the test runner (which downloads the files) to the test bundle so the bundle
	// can include them in the test's output.
	ExternalErrorSuffix = ".external-error"

	// ExternalURLSuffix is a file name suffix to store external data file's source url.
	// It is used to perform staleness check for external files. If this file is present
	// tast first refer this file to see if it has previously downloaded file from the
	// url. If so then file is not downloaded again. This is useful in case when
	// the artifact name in External data files does not change, however the
	// buildartifactsurl cli flag changed, resulting in different source url.
	ExternalURLSuffix = ".external-url"
)
View Source 
const (
	// LacrosVariantUnknown indicates that this test has not yet been checked as to whether it requires a lacros variant.
	// New tests should not use this value, i.e. new tests should always consider lacros.
	LacrosVariantUnknown = iota
	// LacrosVariantNeeded indicates that a lacros variant for this is needed but hasn't been created yet.
	LacrosVariantNeeded
	// LacrosVariantExists indicates that all required lacros variants for this test have been created.
	LacrosVariantExists
	// LacrosVariantUnneeded indicates that lacros variants for this test are not needed.
	LacrosVariantUnneeded
)
View Source 
const TestDidNotRunMsg = "Test did not run"

TestDidNotRunMsg is the error message for when a test failed before it started. This is a magic string that tast.py treats as a NOT_RUN status.

Variables

This section is empty.

Functions

func ExtractLocalBundleDir 

func ExtractLocalBundleDir(h *RPCHint) string

ExtractLocalBundleDir extracts localBundleDir from RPCHint.

func ExtractTestVars 

func ExtractTestVars(h *RPCHint) map[string]string

ExtractTestVars extracts test vars from RPCHint.

func NewContext 

func NewContext(ctx context.Context, ec *testcontext.CurrentEntity, sink logging.Sink) context.Context

NewContext returns a context.Context to be used for the entity.

func NewError 

func NewError(err error, fullMsg, lastMsg string, skipFrames int) *protocol.Error

NewError returns a new Error object containing reason rsn. skipFrames contains the number of frames to skip to get the code that's reporting the error: the caller should pass 0 to report its own frame, 1 to skip just its own frame, 2 to additionally skip the frame that called it, and so on.

func NewTestGlobRegexp 

func NewTestGlobRegexp(glob string) (*regexp.Regexp, error)

NewTestGlobRegexp returns a compiled regular expression corresponding to glob.

DEPRECATED: Use Matcher instead.

func RelativeDataDir 

func RelativeDataDir(pkg string) string

RelativeDataDir returns the path to the directory in which data files for tests in pkg will be located, relative to the top-level directory containing data files.

func WriteTestsAsProto 

func WriteTestsAsProto(w io.Writer, ts []*TestInstance) error

WriteTestsAsProto exports test metadata in the protobuf format defined by infra.

Types

type CloudStorage 

type CloudStorage struct {
	// contains filtered or unexported fields
}

CloudStorage allows Tast tests to read files on Google Cloud Storage.

func NewCloudStorage 

func NewCloudStorage(devservers []string,
	tlwServer, dutName, dutServer, buildArtifactsURL, swarmingTaskID, buildBucketID string) *CloudStorage

NewCloudStorage constructs a new CloudStorage from a list of Devserver URLs. This function is for the framework; tests should call testing.State.CloudStorage to get an instance.

func (*CloudStorage) Open 

func (c *CloudStorage) Open(ctx context.Context, url string) (io.ReadCloser, error)

Open opens a file on Google Cloud Storage for read. Callers are responsible for closing the returned io.ReadCloser. Urls that start with build-artifact:/// will be treated as relative to the BuildArtifactsURL passed to tast in the --buildartifactsurl argument.

func (*CloudStorage) Stage 

func (c *CloudStorage) Stage(ctx context.Context, url string) (*url.URL, error)

Stage opens a file on Google Cloud Storage for read. Returns a http or file url to the data. Urls that start with build-artifact:/// will be treated as relative to the BuildArtifactsURL passed to tast in the --buildartifactsurl argument.

type EntityCondition 

type EntityCondition struct {
	// contains filtered or unexported fields
}

EntityCondition stores mutable condition of an entity.

func NewEntityCondition 

func NewEntityCondition() *EntityCondition

NewEntityCondition creates a new EntityCondition

func (*EntityCondition) HasError 

func (c *EntityCondition) HasError() bool

HasError returns whether an error has been reported for the entity.

func (*EntityCondition) RecordError 

func (c *EntityCondition) RecordError()

RecordError record that an error has been reported for the entity.

type EntityConstraints 

type EntityConstraints struct {
	// contains filtered or unexported fields
}

EntityConstraints represents constraints imposed to an entity. For example, a test can only access runtime variables declared on its registration. This struct carries a list of declared runtime variables to be checked against in State.Var.

type EntityRoot 

type EntityRoot struct {
	// contains filtered or unexported fields
}

EntityRoot is the root of all State objects associated with an entity. EntityRoot keeps track of states shared among all State objects associated with an entity (e.g. whether any error has been reported), as well as immutable entity information such as RuntimeConfig. Make sure to create State objects for an entity from the same EntityRoot. EntityRoot must be kept private to the framework.

func NewEntityRoot 

func NewEntityRoot(ce *testcontext.CurrentEntity, cst *EntityConstraints, cfg *RuntimeConfig, out OutputStream, condition *EntityCondition) *EntityRoot

NewEntityRoot returns a new EntityRoot object.

func (*EntityRoot) NewContext 

func (r *EntityRoot) NewContext(ctx context.Context) context.Context

NewContext creates a new context associated with the entity.

func (*EntityRoot) NewFixtState 

func (r *EntityRoot) NewFixtState() *FixtState

NewFixtState creates a FixtState for a fixture.

type FixtState 

type FixtState struct {
	// contains filtered or unexported fields
}

FixtState is the state the framework passes to Fixture.SetUp and Fixture.TearDown.

func (FixtState) CloudStorage 

func (s FixtState) CloudStorage() *CloudStorage

CloudStorage returns a client for Google Cloud Storage.

func (FixtState) CompanionDUT 

func (s FixtState) CompanionDUT(role string) *dut.DUT

CompanionDUT returns a shared SSH connection for a companion DUT. It can only be called by remote entities.

func (FixtState) DUT 

func (s FixtState) DUT() *dut.DUT

DUT returns a shared SSH connection. It can only be called by remote entities.

func (FixtState) DataFileSystem 

func (s FixtState) DataFileSystem() *dataFS

DataFileSystem returns an http.FileSystem implementation that serves an entity's data files. 

srv := httptest.NewServer(http.FileServer(s.DataFileSystem()))
defer srv.Close()
resp, err := http.Get(srv.URL+"/data_file.html")

func (FixtState) DataPath 

func (s FixtState) DataPath(p string) string

DataPath returns the absolute path to use to access a data file previously registered via Data. It aborts the entity if the p was not declared.

func (FixtState) Error 

func (s FixtState) Error(args ...interface{})

Error formats its arguments using default formatting and marks the entity as having failed (using the arguments as a reason for the failure) while letting the entity continue execution.

func (FixtState) Errorf 

func (s FixtState) Errorf(format string, args ...interface{})

Errorf is similar to Error but formats its arguments using fmt.Sprintf.

func (FixtState) Fatal 

func (s FixtState) Fatal(args ...interface{})

Fatal is similar to Error but additionally immediately ends the entity.

func (FixtState) Fatalf 

func (s FixtState) Fatalf(format string, args ...interface{})

Fatalf is similar to Fatal but formats its arguments using fmt.Sprintf.

func (FixtState) Features 

func (s FixtState) Features(role string) *frameworkprotocol.DUTFeatures

Features returns the features of a DUT based on role name. For primary DUT, use "" as the role name.

func (*FixtState) FixtContext 

func (s *FixtState) FixtContext() context.Context

FixtContext returns fixture-scoped context. i.e. the context is alive until TearDown returns. The context is also associated with the fixture metadata. For example, testing.ContextOutDir(ctx) returns the output directory allocated to the fixture.

func (FixtState) HasError 

func (s FixtState) HasError() bool

HasError reports whether the entity has already reported errors.

func (FixtState) Log 

func (s FixtState) Log(args ...interface{})

Log formats its arguments using default formatting and logs them.

func (FixtState) Logf 

func (s FixtState) Logf(format string, args ...interface{})

Logf is similar to Log but formats its arguments using fmt.Sprintf.

func (*FixtState) OutDir 

func (s *FixtState) OutDir() string

OutDir returns a directory into which the entity may place arbitrary files that should be included with the entity results.

func (*FixtState) Param 

func (s *FixtState) Param() interface{}

Param returns Val specified at the Param struct for the current fixture.

func (*FixtState) ParentFillValue 

func (s *FixtState) ParentFillValue(v any) error

ParentFillValue stores the parent fixture value iin the value pointed to by v.

func (*FixtState) ParentValue 

func (s *FixtState) ParentValue() interface{}

ParentValue returns the parent fixture value if the fixture has a parent in the same process. ParentValue returns nil otherwise.

func (FixtState) RPCHint 

func (s FixtState) RPCHint() *RPCHint

RPCHint returns information needed to establish gRPC connections. It can only be called by remote entities.

func (FixtState) RequiredVar 

func (s FixtState) RequiredVar(name string) string

RequiredVar is similar to Var but aborts the entity if the named variable was not supplied.

func (FixtState) Var 

func (s FixtState) Var(name string) (val string, ok bool)

Var returns the value for the named variable, which must have been registered via Vars. If a value was not supplied at runtime via the -var flag to "tast run", ok will be false.

type FixtTestEntityRoot 

type FixtTestEntityRoot struct {
	// contains filtered or unexported fields
}

FixtTestEntityRoot is the root of all State objects associated with a test and a fixture. Such state is only FixtTestState. FixtTestEntityRoot must be kept private to the framework.

func NewFixtTestEntityRoot 

func NewFixtTestEntityRoot(fixture *FixtureInstance, cfg *RuntimeConfig, out OutputStream, condition *EntityCondition) *FixtTestEntityRoot

NewFixtTestEntityRoot creates a new FixtTestEntityRoot.

func (*FixtTestEntityRoot) LogSink 

func (r *FixtTestEntityRoot) LogSink() logging.Sink

LogSink returns a logging sink for the entity.

func (*FixtTestEntityRoot) NewFixtTestState 

func (r *FixtTestEntityRoot) NewFixtTestState(ctx context.Context, name string) *FixtTestState

NewFixtTestState creates a FixtTestState. ctx should have the same lifetime as the test, including PreTest and PostTest.

func (*FixtTestEntityRoot) OutDir 

func (r *FixtTestEntityRoot) OutDir() string

OutDir returns a directory into which the entity may place arbitrary files that should be included with the test results.

type FixtTestState 

type FixtTestState struct {
	// contains filtered or unexported fields
}

FixtTestState is the state the framework passes to PreTest and PostTest.

func (FixtTestState) CloudStorage 

func (s FixtTestState) CloudStorage() *CloudStorage

CloudStorage returns a client for Google Cloud Storage.

func (FixtTestState) CompanionDUT 

func (s FixtTestState) CompanionDUT(role string) *dut.DUT

CompanionDUT returns a shared SSH connection for a companion DUT. It can only be called by remote entities.

func (FixtTestState) DUT 

func (s FixtTestState) DUT() *dut.DUT

DUT returns a shared SSH connection. It can only be called by remote entities.

func (FixtTestState) Error 

func (s FixtTestState) Error(args ...interface{})

Error formats its arguments using default formatting and marks the entity as having failed (using the arguments as a reason for the failure) while letting the entity continue execution.

func (FixtTestState) Errorf 

func (s FixtTestState) Errorf(format string, args ...interface{})

Errorf is similar to Error but formats its arguments using fmt.Sprintf.

func (FixtTestState) Fatal 

func (s FixtTestState) Fatal(args ...interface{})

Fatal is similar to Error but additionally immediately ends the entity.

func (FixtTestState) Fatalf 

func (s FixtTestState) Fatalf(format string, args ...interface{})

Fatalf is similar to Fatal but formats its arguments using fmt.Sprintf.

func (FixtTestState) Features 

func (s FixtTestState) Features(role string) *frameworkprotocol.DUTFeatures

Features returns the features of a DUT based on role name. For primary DUT, use "" as the role name.

func (FixtTestState) HasError 

func (s FixtTestState) HasError() bool

HasError reports whether the entity has already reported errors.

func (FixtTestState) Log 

func (s FixtTestState) Log(args ...interface{})

Log formats its arguments using default formatting and logs them.

func (FixtTestState) Logf 

func (s FixtTestState) Logf(format string, args ...interface{})

Logf is similar to Log but formats its arguments using fmt.Sprintf.

func (*FixtTestState) OutDir 

func (s *FixtTestState) OutDir() string

OutDir returns a directory into which the entity may place arbitrary files that should be included with the entity results.

func (FixtTestState) RPCHint 

func (s FixtTestState) RPCHint() *RPCHint

RPCHint returns information needed to establish gRPC connections. It can only be called by remote entities.

func (*FixtTestState) TestContext 

func (s *FixtTestState) TestContext() context.Context

TestContext returns context associated with the test. It has the same lifetime as the test (including PreTest and PostTest), and the same metadata as the ctx passed to PreTest and PostTest.

func (*FixtTestState) TestName 

func (s *FixtTestState) TestName() string

TestName returns test name of the test.

type Fixture 

type Fixture struct {
	// Name is the name of the fixture.
	// Tests and fixtures use the name to specify the fixture.
	// The name must be camelCase starting with a lowercase letter and containing only digits and letters.
	Name string

	// Desc is the description of the fixture.
	Desc string

	// Contacts is a list of email addresses of persons and groups who are familiar with the
	// fixture. At least one personal email address of an active committer should be specified so
	// that we can file bugs or ask for code review.
	Contacts []string

	// Impl is the implementation of the fixture.
	Impl FixtureImpl

	// Parent specifies the parent fixture name, or empty if it has no parent.
	Parent string

	// SetUpTimeout is the timeout applied to SetUp.
	// Even if fixtures are nested, the timeout is applied only to this stage.
	// This timeout is by default 0.
	SetUpTimeout time.Duration

	// ResetTimeout is the timeout applied to Reset.
	// Even if fixtures are nested, the timeout is applied only to this stage.
	// This timeout is by default 0.
	ResetTimeout time.Duration

	// PreTestTimeout is the timeout applied to PreTest.
	// Even if fixtures are nested, the timeout is applied only to this stage.
	// This timeout is by default 0.
	PreTestTimeout time.Duration

	// PostTestTimeout is the timeout applied to PostTest.
	// Even if fixtures are nested, the timeout is applied only to this stage.
	// This timeout is by default 0.
	PostTestTimeout time.Duration

	// TearDownTimeout is the timeout applied to TearDown.
	// Even if fixtures are nested, the timeout is applied only to this stage.
	// This timeout is by default 0.
	TearDownTimeout time.Duration

	// ServiceDeps contains a list of RPC service names in local test bundles that this remote fixture
	// will access. This field is valid only for remote fixtures.
	ServiceDeps []string

	// Vars contains the names of runtime variables used to pass out-of-band data to tests.
	// Values are supplied using "tast run -var=name=value", and tests can access values via State.Var.
	Vars []string

	// Data contains paths of data files needed by the fixture, relative to a
	// "data" subdirectory within the directory in which the fixture is registered.
	Data []string

	// PrivateAttr contains freeform text private attributres describing the fixture.
	PrivateAttr []string
}

Fixture represents fixtures to register to the framework.

type FixtureImpl 

type FixtureImpl interface {
	// SetUp is called by the framework to set up the environment with possibly heavy-weight
	// operations.
	//
	// The context and state passed to SetUp are associated with the fixture metadata. For example,
	// testing.ContextOutDir(ctx) and s.OutDir() return the output directory allocated for the
	// fixture itself. testing.ContextSoftwareDeps(ctx) fails since fixtures can't declare software
	// dependencies.
	//
	// TODO(oka): Consider updating ContextSoftwareDeps API so that it's meaningful for fixture
	// scoped contexts. For tests, ContextSoftwareDeps returns the dependencies the test declares,
	// and utility methods (e.g. arc.New) use it to check that tests declare proper software
	// dependencies. For fixtures, it is uncertain what ContextSoftwareDeps should return. One
	// might think it could return the intersection of the software deps of the tests depending on
	// the fixture, but it doesn't work considering arc.New checks OR condition of the software
	// deps. Still, fixtures can call functions like arc.New that calls ContextSoftwareDeps. It
	// indicates that we need to reconsider ContextSoftwareDeps API.
	//
	// The return value is made available to the direct children of this fixture in the entity
	// graph, as long as this fixture and a child live in the same process.
	// If any resource is associated with the value (e.g. Chrome browser connection), it must not
	// be released in Reset, PreTest and PostTest because descendant fixtures may cache it or
	// construct subresources derived from it (e.g. Chrome tab connection).
	//
	// SetUp is called in descending order (parents to children) when fixtures are nested.
	//
	// SetUp can be called multiple times. This happens when this fixture's TearDown is called
	// before completing all tests depending on it in the following cases:
	//  - This fixture's Reset requested it by returning an error.
	//  - Ascendant fixtures' Reset requested it by returning an error.
	// In any case, TearDown is called in a pair with a successful SetUp call.
	//
	// Errors in this method are reported as errors of the fixture itself, rather than tests
	// depending on it.
	//
	// If one or more errors are reported in SetUp by s.Error or s.Fatal, all remaining tests
	// depending on this fixture are marked failed without actually running. TearDown is not called
	// in this case. If s.Fatal is called, SetUp immediately aborts.
	//
	// This method is the best place to do a heavy-weight setup of the system environment, e.g.
	// restarting a Chrome session.
	//
	// Note that SetUpTimeout is by default 0. Change it to have a valid context.
	SetUp(ctx context.Context, s *FixtState) interface{}

	// Reset is called by the framework after each test (except for the last one) to do a
	// light-weight reset of the environment to the original state.
	//
	// The context passed to Reset is associated with the fixture metadata. See SetUp for details.
	//
	// If Reset returns a non-nil error, the framework tears down and re-sets up the fixture to
	// recover. To be accurate, the following methods are called in order:
	//  - Descendant fixtures' TearDown in ascending order
	//  - This fixture's TearDown
	//  - This fixture's SetUp
	//  - Descendant fixtures' SetUp in descending order
	// Consequently, errors Reset returns don't affect ascendant fixtures.
	//
	// Returning an error from Reset is valid when light-weight reset doesn't restore the
	// condition the fixture declares.
	//
	// Reset is called in descending order (parents to children) when fixtures are nested.
	//
	// This method is the best place to do a light-weight cleanup of the system environment to the
	// original one when the fixture was set up, e.g. closing open Chrome tabs.
	//
	// Note that ResetTimeout is by default 0. Change it to have a valid context.
	Reset(ctx context.Context) error

	// PreTest is called by the framework before each test to do a light-weight set up for the test.
	//
	// The context and state passed to PreTest are associated with the test metadata. For example,
	// testing.ContextOutDir(ctx) and s.OutDir() return the output directory allocated to the test.
	//
	// PreTest is called in descending order (parents to children) when fixtures are nested.
	//
	// s.Error or s.Fatal can be used to report errors in PreTest. When s.Fatal is called PreTest
	// immediately aborts. The error is marked as the test failure.
	//
	// This method is always called if fixture is successfully reset by SetUp or Reset.
	//
	// In any case, PostTest is called in a pair with a successful PreTest call.
	//
	// If errors are reported in PreTest, it is reported as the test failure.
	//
	// If errors are reported in PreTest, the test and PostTest are not run.
	//
	// This method is the best place to do a setup for the test runs next. e.g. redirect logs to a
	// file in the test's output directory.
	//
	// Note that PreTestTimeout is by default 0. Change it to have a valid context.
	PreTest(ctx context.Context, s *FixtTestState)

	// PostTest is called by the framework after each test to tear down changes PreTest made.
	//
	// The context and state passed to PostTest are associated with the test metadata. For example,
	// testing.ContextOutDir(ctx) and s.OutDir() return the output directory allocated to the test.
	//
	// PostTest is called in ascending order (children to parent) when fixtures are nested.
	//
	// s.Error or s.Fatal can be used to report errors in PostTest. When s.Fatal is called PostTest
	// immediately aborts. The error is marked as the test failure.
	//
	// This method is always called if PreTest succeeds.
	//
	// PostTest is always called in a pair with a successful PreTest call.
	//
	// If errors are reported in PostTest, it is reported as the test failure.
	//
	// The errors PostTest reports don't affect the order of the fixture methods the framework
	// calls.
	//
	// This method is the best place to tear down changes PreTest made. e.g. close log files in the
	// test output directory.
	//
	// Note that PostTestTimeout is by default 0. Change it to have a valid context.
	PostTest(ctx context.Context, s *FixtTestState)

	// TearDown is called by the framework to tear down the environment SetUp set up.
	//
	// The context and state passed to TearDown are associated with the fixture metadata. See SetUp
	// for details.
	//
	// TearDown is called in an ascending order (children to parents) when fixtures are nested.
	//
	// TearDown is always called in a pair with a successful SetUp call.
	//
	// Errors in this method are reported as errors of the fixture itself, rather than tests
	// depending on it.
	//
	// Errors in TearDown doesn't affect the order of the fixture methods the framework calls.
	// That is, even if this fixture's TearDown reports errors, its ascendants' TearDown are still
	// called.
	//
	// This method is the best place to tear down changes SetUp made. e.g. Unenroll enterprise
	// enrollment.
	// Changes that shouldn't hinder healthy execution of succeeding tests are not necessarily to
	// be teared down. e.g. Chrome session can be left open.
	//
	// Note that TearDownTimeout is by default 0. Change it to have a valid context.
	TearDown(ctx context.Context, s *FixtState)
}

FixtureImpl provides implementation of the fixture registered to the framework.

type FixtureInstance 

type FixtureInstance struct {
	// Pkg is the package from which the fixture is registered.
	Pkg string

	// Following fields are copied from Fixture.
	Name            string
	Desc            string
	Contacts        []string
	Impl            FixtureImpl
	Parent          string
	SetUpTimeout    time.Duration
	ResetTimeout    time.Duration
	PreTestTimeout  time.Duration
	PostTestTimeout time.Duration
	TearDownTimeout time.Duration
	Data            []string
	ServiceDeps     []string
	Vars            []string
	PrivateAttr     []string

	// Bundle is the name of the test bundle this test belongs to.
	// This field is empty initially, and later set when the test is added
	// to testing.Registry.
	Bundle string
}

FixtureInstance represents a fixture instance registered to the framework.

FixtureInstance is to Fixture what TestInstance is to Test.

func (*FixtureInstance) Constraints 

func (f *FixtureInstance) Constraints() *EntityConstraints

Constraints returns EntityConstraints for this fixture.

func (*FixtureInstance) EntityProto 

func (f *FixtureInstance) EntityProto() *protocol.Entity

EntityProto returns a protocol buffer message representation of f.

type LacrosMetadata 

type LacrosMetadata int

LacrosMetadata indicates whether lacros variants have been considered for this test or not.

func (LacrosMetadata) String 

func (m LacrosMetadata) String() string

type Matcher 

type Matcher struct {
	// contains filtered or unexported fields
}

Matcher holds compiled patterns to match tests.

func NewMatcher 

func NewMatcher(pats []string) (*Matcher, error)

NewMatcher creates a new Matcher from patterns.

func (*Matcher) Match 

func (m *Matcher) Match(name string, attrs []string) bool

Match matches a test.

func (*Matcher) UnmatchedPatterns 

func (m *Matcher) UnmatchedPatterns(tests []string) []string

UnmatchedPatterns returns a list of test name patterns (exact or wildcards) in the matcher that do not match any of supplied test names. This method always returns nil if the pattern in the matcher is an attribute expression.

type Meta 

type Meta struct {
	// TastPath contains the absolute path to the tast executable.
	TastPath string
	// Target contains information about the DUT as "[<user>@]host[:<port>]".
	// DEPRECATED: Use ConnectionSpec instead.
	Target string
	// Flags contains flags that should be passed to the tast command's "run" subcommands.
	RunFlags []string
	// Flags contains flags that should be passed to the tast command's "list" subcommands.
	ListFlags []string
	// ConnectionSpec contains information about the DUT as "[<user>@]host[:<port>]".
	ConnectionSpec string
}

Meta contains information about how the "tast" process used to initiate testing was run. It is used by remote tests in the "meta" category that run the tast executable to test Tast's behavior.

type OutputStream 

type OutputStream interface {
	// Log reports an informational log message from an entity.
	Log(msg string) error

	// Error reports an error from by an entity. An entity that reported one or
	// more errors should be considered failure.
	Error(e *protocol.Error) error
}

OutputStream is an interface to report streamed outputs of an entity. Note that planner.OutputStream is for multiple entities in contrast.

type Param 

type Param struct {
	// Name is the name of this parameterized test.
	// Full name of the test case will be category.TestFuncName.param_name,
	// or category.TestFuncName if Name is empty.
	// Name should match with [a-z0-9_]*.
	Name string

	// ExtraAttr contains freeform text attributes describing the test,
	// in addition to Attr declared in the enclosing Test.
	ExtraAttr []string

	// ExtraPrivateAttr contains freeform text private attributes describing the test,
	// in addition to PrivateAttr declared in the enclosing Test.
	ExtraPrivateAttr []string

	// ExtraSearchFlags contains name-value pairs describing the test,
	// in addition to SearchFlags declared in the enclosing Test.
	ExtraSearchFlags []*protocol.StringPair

	// ExtraData contains paths of data files needed by the test case of this
	// param in addition to Data declared in the enclosing Test.
	ExtraData []string

	// ExtraSoftwareDeps lists software features that are required to run the test case for this param,
	// in addition to SoftwareDeps in the enclosing Test.
	ExtraSoftwareDeps []string

	// ExtraHardwareDeps describes hardware features and setup that are required to run the test for this
	// param, in addition to HardwareDeps in the enclosing Test.
	ExtraHardwareDeps hwdep.Deps

	// ExtraRequirements are used for linking test cases to requirements. These are not used by
	// tests themselves, but added to test metadata definitions used by infra services.  This slice is
	// appended to an Requirements declared by the test.
	ExtraRequirements []string

	// Pre contains a precondition that must be met before the test is run.
	// Can only be set if the enclosing test doesn't have one already set.
	Pre Precondition

	// Fixture is the name of the fixture the test depends on.
	// Can only be set if the enclosing test doesn't have one already set.
	Fixture string

	// Timeout contains the maximum duration for which Func may run before the test is aborted.
	// Can only be set if the enclosing test doesn't have one already set.
	Timeout time.Duration

	// Val is the value which can be retrieved from testing.State.Param() method.
	Val interface{}

	// ExtraSoftwareDepsForAll lists software features of all DUTs
	// that are required to run the test case for this param,
	// in addition to SoftwareDepsForAll in the enclosing Test.
	// The primary DUT software dependency will be the union of
	// SoftwareDeps, SoftwareDepsForAll[""], ExtraSoftwareDeps and
	// ExtraSoftwareDepsForAll[""].
	// It is a map of companion roles and software features.
	ExtraSoftwareDepsForAll map[string][]string

	// ExtraHardwareDepsForAll describes hardware features and setup
	// companion DUTs that are required to run the test case for this param,
	// in addition to HardwareDepsForAll in the enclosing Test.
	// It is a map of companion roles and hardware features.
	// The role for primary DUT should be ""
	// The primary DUT hardware dependency will be the union of
	// HardwareDeps, HardwareDepsForAll[""], ExtraHardwareDeps and
	// ExtraHardwareDep and ExtraHardwareDepsForAll[""].
	ExtraHardwareDepsForAll map[string]hwdep.Deps

	// BugComponent overrides BugComponent defined in the test.
	// This field is for infra/external use only and should not be used
	// or referenced within the test code..
	BugComponent string
}

Param defines parameters for a parameterized test case. See also https://chromium.googlesource.com/chromiumos/platform/tast/+/HEAD/docs/writing_tests.md#Parameterized-tests

type PreState 

type PreState struct {
	// contains filtered or unexported fields
}

PreState holds state relevant to the execution of a single precondition.

This is a State for preconditions. See State's documentation for general guidance on how to treat PreState in preconditions.

func (PreState) CloudStorage 

func (s PreState) CloudStorage() *CloudStorage

CloudStorage returns a client for Google Cloud Storage.

func (PreState) CompanionDUT 

func (s PreState) CompanionDUT(role string) *dut.DUT

CompanionDUT returns a shared SSH connection for a companion DUT. It can only be called by remote entities.

func (PreState) DUT 

func (s PreState) DUT() *dut.DUT

DUT returns a shared SSH connection. It can only be called by remote entities.

func (PreState) DataFileSystem 

func (s PreState) DataFileSystem() *dataFS

DataFileSystem returns an http.FileSystem implementation that serves an entity's data files. 

srv := httptest.NewServer(http.FileServer(s.DataFileSystem()))
defer srv.Close()
resp, err := http.Get(srv.URL+"/data_file.html")

func (PreState) DataPath 

func (s PreState) DataPath(p string) string

DataPath returns the absolute path to use to access a data file previously registered via Data. It aborts the entity if the p was not declared.

func (PreState) Error 

func (s PreState) Error(args ...interface{})

Error formats its arguments using default formatting and marks the entity as having failed (using the arguments as a reason for the failure) while letting the entity continue execution.

func (PreState) Errorf 

func (s PreState) Errorf(format string, args ...interface{})

Errorf is similar to Error but formats its arguments using fmt.Sprintf.

func (PreState) Fatal 

func (s PreState) Fatal(args ...interface{})

Fatal is similar to Error but additionally immediately ends the entity.

func (PreState) Fatalf 

func (s PreState) Fatalf(format string, args ...interface{})

Fatalf is similar to Fatal but formats its arguments using fmt.Sprintf.

func (PreState) Features 

func (s PreState) Features(role string) *frameworkprotocol.DUTFeatures

Features returns the features of a DUT based on role name. For primary DUT, use "" as the role name.

func (PreState) HasError 

func (s PreState) HasError() bool

HasError reports whether the entity has already reported errors.

func (PreState) Log 

func (s PreState) Log(args ...interface{})

Log formats its arguments using default formatting and logs them.

func (PreState) Logf 

func (s PreState) Logf(format string, args ...interface{})

Logf is similar to Log but formats its arguments using fmt.Sprintf.

func (PreState) OutDir 

func (s PreState) OutDir() string

OutDir returns a directory into which the entity may place arbitrary files that should be included with the entity results.

func (*PreState) PreCtx 

func (s *PreState) PreCtx() context.Context

PreCtx returns a context that lives as long as the precondition. Can only be called from inside a precondition; it panics otherwise.

func (PreState) RPCHint 

func (s PreState) RPCHint() *RPCHint

RPCHint returns information needed to establish gRPC connections. It can only be called by remote entities.

func (PreState) RequiredVar 

func (s PreState) RequiredVar(name string) string

RequiredVar is similar to Var but aborts the entity if the named variable was not supplied.

func (PreState) ServiceDeps 

func (s PreState) ServiceDeps() []string

ServiceDeps returns service dependencies declared in the currently running entity.

func (PreState) SoftwareDeps 

func (s PreState) SoftwareDeps() []string

SoftwareDeps returns software dependencies declared in the currently running entity.

func (PreState) TestName 

func (s PreState) TestName() string

TestName returns the name of the currently running test.

func (PreState) Var 

func (s PreState) Var(name string) (val string, ok bool)

Var returns the value for the named variable, which must have been registered via Vars. If a value was not supplied at runtime via the -var flag to "tast run", ok will be false.

type Precondition 

type Precondition interface {
	// Prepare is called immediately before starting each test that depends on the precondition.
	// The returned value will be made available to the test via State.PreValue.
	// To report an error, Prepare can call either s.Error/Errorf or s.Fatal/Fatalf.
	// If an error is reported, the test will not run, but the Precondition must be left
	// in a state where future calls to Prepare (and Close) can still succeed.
	Prepare(ctx context.Context, s *PreState) interface{}

	// Close is called immediately after completing the final test that depends on the precondition.
	// This method may be called without an earlier call to Prepare in rare cases (e.g. if
	// RuntimeConfig.PreTestFunc fails); preconditions must be able to handle this.
	Close(ctx context.Context, s *PreState)

	// String returns a short, underscore-separated name for the precondition.
	// "chrome_logged_in" and "arc_booted" are examples of good names for preconditions
	// defined by the "chrome" and "arc" packages, respectively.
	String() string

	// Timeout returns the amount of time dedicated to prepare and close the precondition.
	Timeout() time.Duration
}

Precondition represents a precondition that must be satisfied before a test is run.

type RPCHint 

type RPCHint struct {
	// contains filtered or unexported fields
}

RPCHint contains information needed to establish gRPC connections.

func NewRPCHint 

func NewRPCHint(localBundleDir string, testVars map[string]string) *RPCHint

NewRPCHint create a new RPCHint struct.

type Registry 

type Registry struct {
	// contains filtered or unexported fields
}

Registry holds tests and services.

func GlobalRegistry 

func GlobalRegistry() *Registry

GlobalRegistry returns a global registry containing tests registered by calls to AddTest.

func NewRegistry 

func NewRegistry(name string) *Registry

NewRegistry returns a new test registry.

func (*Registry) AddFixture 

func (r *Registry) AddFixture(f *Fixture, pkg string)

AddFixture adds f to the registry.

func (*Registry) AddFixtureInstance 

func (r *Registry) AddFixtureInstance(f *FixtureInstance)

AddFixtureInstance adds f to the registry. In contrast to AddFixture, AddFixtureInstance registers an instantiated fixture almost as-is. It just associates the fixture with this registry so that the fixture cannot be registered to other registries. AddFixtureInstance should be called only by unit tests. It must not be accessible by user code.

func (*Registry) AddService 

func (r *Registry) AddService(s *Service)

AddService adds s to the registry.

func (*Registry) AddTest 

func (r *Registry) AddTest(t *Test)

AddTest adds t to the registry.

func (*Registry) AddTestInstance 

func (r *Registry) AddTestInstance(t *TestInstance)

AddTestInstance adds t to the registry. In contrast to AddTest, AddTestInstance registers an instantiated test almost as-is. It just associates the test with this registry so that the test cannot be registered to other registries. AddTestInstance should be called only by unit tests. It must not be accessible by user code.

func (*Registry) AddVar 

func (r *Registry) AddVar(v Var)

AddVar adds global variables to the registry.

func (*Registry) AllFixtures 

func (r *Registry) AllFixtures() map[string]*FixtureInstance

AllFixtures returns copies of all registered fixtures.

func (*Registry) AllServices 

func (r *Registry) AllServices() []*Service

AllServices returns copies of all registered services.

func (*Registry) AllTests 

func (r *Registry) AllTests() []*TestInstance

AllTests returns copies of all registered tests.

func (*Registry) AllVars 

func (r *Registry) AllVars() []Var

AllVars returns copies of all registered all runtime variables.

func (*Registry) Errors 

func (r *Registry) Errors() []error

Errors returns errors generated by registration method calls.

func (*Registry) InitializeVars 

func (r *Registry) InitializeVars(values map[string]string) error

InitializeVars initializes all registered global variables.

func (*Registry) Name 

func (r *Registry) Name() string

Name returns the name of the registry.

func (*Registry) RecordError 

func (r *Registry) RecordError(err error)

RecordError records err as a registration error if it is not nil.

type RemoteData 

type RemoteData struct {
	// Meta contains information about how the tast process was run.
	Meta *Meta
	// RPCHint contains information needed to establish gRPC connections.
	RPCHint *RPCHint
	// DUT is an SSH connection shared among remote entities.
	DUT *dut.DUT
	// CompanionDUTs are other DUTs that can be used in remote test.
	CompanionDUTs map[string]*dut.DUT
}

RemoteData contains information relevant to remote entities.

type RuntimeConfig 

type RuntimeConfig struct {
	// DataDir is the directory in which the test's data files are located.
	DataDir string
	// OutDir is the directory to which the test will write output files.
	OutDir string
	// Vars contains names and values of out-of-band variables passed to tests at runtime.
	// Names must be registered in Test.Vars and values may be accessed using State.Var.
	Vars map[string]string
	// Features contains hardware features for all DUTs used in the test.
	Features map[string]*protocol.DUTFeatures
	// CloudStorage is a client to read files on Google Cloud Storage.
	CloudStorage *CloudStorage
	// RemoteData contains information relevant to remote tests.
	// This is nil for local tests.
	RemoteData *RemoteData
	// FixtValue is a value returned by a parent fixture.
	// It is nil if not available.
	FixtValue interface{}
	// FixtSerializedValue is a serialized value returned by a parent fixture.
	// It is nil if not available.
	FixtSerializedValue func() ([]byte, error)
	// FixtCtx is the context that lives as long as the fixture.
	// It can be accessed only from testing.FixtState.
	FixtCtx context.Context
	// PreCtx is the context that lives as long as the precondition.
	// It can be accessed only from testing.PreState.
	PreCtx context.Context
	// Purgeable is a list of file paths which are not used for now and thus
	// can be deleted if the disk space is low.
	Purgeable []string
	//MaxSysMsgLogSize is a size of flag for truncate log file.
	MaxSysMsgLogSize int64
}

RuntimeConfig contains details about how an individual test should be run.

type Service 

type Service struct {
	// Register is a function called by the framework to register a gRPC service
	// to grpc.Server. This should be a simple function that constructs a gRPC
	// service implementation and calls pb.Register*Server.
	Register func(srv *grpc.Server, s *ServiceState)
	// Vars contains the names of runtime variables used by the service.
	Vars []string
	// GuaranteeCompatibility indicates that the service needs to strictly adhere to
	// the backward and forward compatibility guarantees when evolving proto definition
	// and implementation.
	// Once the flag is marked as True, it cannot be change to False in subsequent
	// versions.
	// The service will be exposed to non-Tast test harness clients.
	GuaranteeCompatibility bool
}

Service contains information about a gRPC service exported for remote tests.

type ServiceRoot 

type ServiceRoot struct {
	// contains filtered or unexported fields
}

ServiceRoot is the root of service state data.

func NewServiceRoot 

func NewServiceRoot(svc *Service, vars map[string]string) *ServiceRoot

NewServiceRoot creates a new ServiceRoot object.

type ServiceState 

type ServiceState struct {
	// contains filtered or unexported fields
}

ServiceState holds state relevant to a gRPC service.

func NewServiceState 

func NewServiceState(ctx context.Context, root *ServiceRoot) *ServiceState

NewServiceState creates a new ServiceState.

func (*ServiceState) Log 

func (s *ServiceState) Log(args ...interface{})

Log formats its arguments using default formatting and logs them. Logs are sent to the currently connected remote bundle.

func (*ServiceState) Logf 

func (s *ServiceState) Logf(format string, args ...interface{})

Logf is similar to Log but formats its arguments using fmt.Sprintf. Logs are sent to the currently connected remote bundle.

func (*ServiceState) ServiceContext 

func (s *ServiceState) ServiceContext() context.Context

ServiceContext returns a service-scoped context. A service-scoped context is canceled on gRPC service shutdown, while a context passed to a gRPC method is canceled on completion of the gRPC method call. Therefore a service-scoped context can be used to run background operations that span across multiple gRPC calls (e.g. starting a background subprocess). A service-scoped context can also be used with testing.ContextLog to send logs to the currently connected remote bundle.

func (*ServiceState) Var 

func (s *ServiceState) Var(name string) (val string, ok bool)

Var returns the value for the named variable. The variable must be declared in the service definition with Vars. If a value was not supplied at runtime via the -var flag, false will be returned.

type State 

type State struct {
	// contains filtered or unexported fields
}

State holds state relevant to the execution of a single test.

Parts of its interface are patterned after Go's testing.T type.

State contains many pieces of data, and it's unclear which are actually being used when it's passed to a function. You should minimize the number of functions taking State as an argument. Instead you can pass State's derived values (e.g. s.DataPath("file.txt")) or ctx (to use with ContextLog or ContextOutDir etc.).

It is intended to be safe when called concurrently by multiple goroutines while a test is running.

func (State) CloudStorage 

func (s State) CloudStorage() *CloudStorage

CloudStorage returns a client for Google Cloud Storage.

func (State) CompanionDUT 

func (s State) CompanionDUT(role string) *dut.DUT

CompanionDUT returns a shared SSH connection for a companion DUT. It can only be called by remote entities.

func (State) DUT 

func (s State) DUT() *dut.DUT

DUT returns a shared SSH connection. It can only be called by remote entities.

func (State) DataFileSystem 

func (s State) DataFileSystem() *dataFS

DataFileSystem returns an http.FileSystem implementation that serves an entity's data files. 

srv := httptest.NewServer(http.FileServer(s.DataFileSystem()))
defer srv.Close()
resp, err := http.Get(srv.URL+"/data_file.html")

func (State) DataPath 

func (s State) DataPath(p string) string

DataPath returns the absolute path to use to access a data file previously registered via Data. It aborts the entity if the p was not declared.

func (State) Error 

func (s State) Error(args ...interface{})

Error formats its arguments using default formatting and marks the entity as having failed (using the arguments as a reason for the failure) while letting the entity continue execution.

func (State) Errorf 

func (s State) Errorf(format string, args ...interface{})

Errorf is similar to Error but formats its arguments using fmt.Sprintf.

func (State) Fatal 

func (s State) Fatal(args ...interface{})

Fatal is similar to Error but additionally immediately ends the entity.

func (State) Fatalf 

func (s State) Fatalf(format string, args ...interface{})

Fatalf is similar to Fatal but formats its arguments using fmt.Sprintf.

func (State) Features 

func (s State) Features(role string) *frameworkprotocol.DUTFeatures

Features returns the features of a DUT based on role name. For primary DUT, use "" as the role name.

func (*State) FixtFillValue 

func (s *State) FixtFillValue(v any) error

FixtFillValue stores the deserialized result in the value pointed to by v.

func (*State) FixtValue 

func (s *State) FixtValue() interface{}

FixtValue returns the fixture value if the test depends on a fixture in the same process. FixtValue returns nil otherwise.

func (State) HasError 

func (s State) HasError() bool

HasError reports whether the entity has already reported errors.

func (State) Log 

func (s State) Log(args ...interface{})

Log formats its arguments using default formatting and logs them.

func (State) Logf 

func (s State) Logf(format string, args ...interface{})

Logf is similar to Log but formats its arguments using fmt.Sprintf.

func (*State) Meta 

func (s *State) Meta() *Meta

Meta returns information about how the "tast" process used to initiate testing was run. It can only be called by remote tests in the "meta" category.

func (State) OutDir 

func (s State) OutDir() string

OutDir returns a directory into which the entity may place arbitrary files that should be included with the entity results.

func (*State) Param 

func (s *State) Param() interface{}

Param returns Val specified at the Param struct for the current test case.

func (*State) PreValue 

func (s *State) PreValue() interface{}

PreValue returns a value supplied by the test's precondition, which must have been declared via Test.Pre when the test was registered. Callers should cast the returned empty interface to the correct pointer type; see the relevant precondition's documentation for specifics. nil will be returned if the test did not declare a precondition.

func (State) RPCHint 

func (s State) RPCHint() *RPCHint

RPCHint returns information needed to establish gRPC connections. It can only be called by remote entities.

func (State) RequiredVar 

func (s State) RequiredVar(name string) string

RequiredVar is similar to Var but aborts the entity if the named variable was not supplied.

func (*State) Run 

func (s *State) Run(ctx context.Context, name string, run func(context.Context, *State)) bool

Run starts a new subtest with a unique name. Error messages are prepended with the subtest name during its execution. If Fatal/Fatalf is called from inside a subtest, only that subtest is stopped; its parent continues. Returns true if the subtest passed.

func (State) ServiceDeps 

func (s State) ServiceDeps() []string

ServiceDeps returns service dependencies declared in the currently running entity.

func (State) SoftwareDeps 

func (s State) SoftwareDeps() []string

SoftwareDeps returns software dependencies declared in the currently running entity.

func (State) TestName 

func (s State) TestName() string

TestName returns the name of the currently running test.

func (State) Var 

func (s State) Var(name string) (val string, ok bool)

Var returns the value for the named variable, which must have been registered via Vars. If a value was not supplied at runtime via the -var flag to "tast run", ok will be false.

type Test 

type Test struct {
	// Func is the function to be executed to perform the test.
	Func TestFunc

	// Desc is a short one-line description of the test.
	Desc string

	// Contacts is a list of email addresses of persons and groups who are familiar with the test.
	// At least one personal email address of an active committer should be specified so that we can
	// file bugs or ask for code reviews.
	Contacts []string

	// Attr contains freeform text attributes describing the test.
	// See https://chromium.googlesource.com/chromiumos/platform/tast/+/HEAD/docs/test_attributes.md
	// for commonly-used attributes.
	Attr []string

	// PrivateAttr contains freeform text private attributes describing the test.
	// This should not be used other than Tast and tests.
	// Note: this info is not retrievable in test results.
	PrivateAttr []string

	// SearchFlags contains key-value pairs describing the test.
	// This information will be available in the test results, and can be used
	// for custom test results filtering or any other mapping.
	SearchFlags []*protocol.StringPair

	// Data contains paths of data files needed by the test, relative to a "data" subdirectory within the
	// directory in which Func is located.
	Data []string

	// Vars contains the names of runtime variables used to pass out-of-band data to tests.
	// Values are supplied using "tast run -var=name=value", and tests can access values via State.Var.
	Vars []string

	// VarDeps serves similar purpose as Vars but lists runtime variables that
	// are required to run the test.
	// Whether test fails or skipped when runtime variables in VarDeps is
	// missing is controlled by the flag -maybemissingvars for the Tast CLI.
	//
	// Tests should access runtime variables in VarDeps via State.RequiredVar.
	VarDeps []string

	// SoftwareDeps lists software features that are required to run the test.
	// If any dependencies are not satisfied by the DUT, the test will be skipped.
	// See https://chromium.googlesource.com/chromiumos/platform/tast/+/HEAD/docs/test_dependencies.md
	// for more information about dependencies.
	SoftwareDeps []string

	// HardwareDeps describes hardware features and setup that are required to run the test.
	HardwareDeps hwdep.Deps

	// Pre contains a precondition that must be met before the test is run.
	Pre Precondition

	// Fixture is the name of the fixture the test depends on.
	Fixture string

	// Timeout contains the maximum duration for which Func may run before the test is aborted.
	// This should almost always be set. If not specified, a reasonable default will be used,
	// but tests should not depend on it.
	// This field is serialized as an integer nanosecond count.
	Timeout time.Duration

	// Params lists the Param structs for parameterized tests.
	Params []Param

	// ServiceDeps contains a list of RPC service names in local test bundles that this remote test
	// will access. This field is valid only for remote tests.
	ServiceDeps []string

	// LacrosStatus indicates whether lacros variants have been considered for this test or not.
	LacrosStatus LacrosMetadata

	// SoftwareDepsForAll lists software features of all DUTs that
	// are required to run the test.
	// It is a map of companion roles and software features.
	// The role for primary DUT should be "".
	// The primary DUT software dependency will be the union of
	// SoftwareDeps and SoftwareDepsForAll[""].
	// If any dependencies are not satisfied, the test will be skipped.
	SoftwareDepsForAll map[string][]string

	// HardwareDepsForAll describes hardware features and setup of all
	// DUTs that are required to run the test.
	// It is a map of companion roles and hardware features.
	// The role for primary DUT should be "".
	// The primary DUT hardware dependency will be the union of
	// HardwareDeps and HardwareDepsForAll[""].
	// If any dependencies are not satisfied, the test will be skipped.
	HardwareDepsForAll map[string]hwdep.Deps

	// TestBedDeps are used for defining test bed dependencies only, i.e., 'carrier:verizon'.
	// These are not used by tests themselves, but added to test metadata definitions used by
	// infra services.
	TestBedDeps []string

	// Requirements are used for linking test cases to requirements. These are not used by
	// tests themselves, but added to test metadata definitions used by infra services.
	Requirements []string

	// Bug component id for filing bugs against this test, i.e. 'b:1234'. This field is not
	// to be used by tests themselves, but added to test metadata definitions used by infra services.
	BugComponent string
}

Test describes a registration of one or more test instances.

Test can be passed to testing.AddTest to actually register test instances to the framework.

In the most basic form where Params field is empty, Test describes exactly one test instance. If Params is not empty, multiple test instances are generated on registration by merging each testing.Param to the base Test.

type TestEntityRoot 

type TestEntityRoot struct {
	// contains filtered or unexported fields
}

TestEntityRoot is the root of all State objects associated with a test. TestEntityRoot is very similar to EntityRoot, but it contains additional states and immutable test information. TestEntityRoot must be kept private to the framework.

func NewTestEntityRoot 

func NewTestEntityRoot(test *TestInstance, cfg *RuntimeConfig, out OutputStream, condition *EntityCondition) *TestEntityRoot

NewTestEntityRoot returns a new TestEntityRoot object.

func (*TestEntityRoot) EntityProto 

func (r *TestEntityRoot) EntityProto() *protocol.Entity

EntityProto returns the test being run as a protocol.Entity.

func (*TestEntityRoot) LogSink 

func (r *TestEntityRoot) LogSink() logging.Sink

LogSink returns a logging sink for the test entity.

func (*TestEntityRoot) NewContext 

func (r *TestEntityRoot) NewContext(ctx context.Context) context.Context

NewContext creates a new context associated with the entity.

func (*TestEntityRoot) NewPreState 

func (r *TestEntityRoot) NewPreState() *PreState

NewPreState creates a PreState for a precondition.

func (*TestEntityRoot) NewTestHookState 

func (r *TestEntityRoot) NewTestHookState() *TestHookState

NewTestHookState creates a TestHookState for a test hook.

func (*TestEntityRoot) NewTestState 

func (r *TestEntityRoot) NewTestState() *State

NewTestState creates a State for a test.

func (*TestEntityRoot) SetPreValue 

func (r *TestEntityRoot) SetPreValue(val interface{})

SetPreValue sets a precondition value available to the test.

type TestFunc 

type TestFunc func(context.Context, *State)

TestFunc is the code associated with a test.

type TestHookState 

type TestHookState struct {
	// contains filtered or unexported fields
}

TestHookState holds state relevant to the execution of a test hook.

This is a State for test hooks. See State's documentation for general guidance on how to treat TestHookState in test hooks.

func (TestHookState) CloudStorage 

func (s TestHookState) CloudStorage() *CloudStorage

CloudStorage returns a client for Google Cloud Storage.

func (TestHookState) CompanionDUT 

func (s TestHookState) CompanionDUT(role string) *dut.DUT

CompanionDUT returns a shared SSH connection for a companion DUT. It can only be called by remote entities.

func (*TestHookState) CompanionDUTRoles 

func (s *TestHookState) CompanionDUTRoles() []string

CompanionDUTRoles returns an alphabetically sorted array of companion DUT roles.

func (TestHookState) DUT 

func (s TestHookState) DUT() *dut.DUT

DUT returns a shared SSH connection. It can only be called by remote entities.

func (TestHookState) DataFileSystem 

func (s TestHookState) DataFileSystem() *dataFS

DataFileSystem returns an http.FileSystem implementation that serves an entity's data files. 

srv := httptest.NewServer(http.FileServer(s.DataFileSystem()))
defer srv.Close()
resp, err := http.Get(srv.URL+"/data_file.html")

func (TestHookState) DataPath 

func (s TestHookState) DataPath(p string) string

DataPath returns the absolute path to use to access a data file previously registered via Data. It aborts the entity if the p was not declared.

func (TestHookState) Error 

func (s TestHookState) Error(args ...interface{})

Error formats its arguments using default formatting and marks the entity as having failed (using the arguments as a reason for the failure) while letting the entity continue execution.

func (TestHookState) Errorf 

func (s TestHookState) Errorf(format string, args ...interface{})

Errorf is similar to Error but formats its arguments using fmt.Sprintf.

func (TestHookState) Fatal 

func (s TestHookState) Fatal(args ...interface{})

Fatal is similar to Error but additionally immediately ends the entity.

func (TestHookState) Fatalf 

func (s TestHookState) Fatalf(format string, args ...interface{})

Fatalf is similar to Fatal but formats its arguments using fmt.Sprintf.

func (TestHookState) Features 

func (s TestHookState) Features(role string) *frameworkprotocol.DUTFeatures

Features returns the features of a DUT based on role name. For primary DUT, use "" as the role name.

func (TestHookState) HasError 

func (s TestHookState) HasError() bool

HasError reports whether the entity has already reported errors.

func (TestHookState) Log 

func (s TestHookState) Log(args ...interface{})

Log formats its arguments using default formatting and logs them.

func (TestHookState) Logf 

func (s TestHookState) Logf(format string, args ...interface{})

Logf is similar to Log but formats its arguments using fmt.Sprintf.

func (*TestHookState) MaxSysMsgLogSize 

func (s *TestHookState) MaxSysMsgLogSize() int64

MaxSysMsgLogSize return the flag size of truncate log file.

func (TestHookState) OutDir 

func (s TestHookState) OutDir() string

OutDir returns a directory into which the entity may place arbitrary files that should be included with the entity results.

func (*TestHookState) Purgeable 

func (s *TestHookState) Purgeable() []string

Purgeable returns a list of paths of purgeable cache files. This list may contain external data files downloaded previously but unused in the next test, and the like. Test hooks can delete those files safely without disrupting test execution if the disk space is low. Some files might be already removed, so test hooks should ignore "file not found" errors. Some files might have hard links, so test hooks should not assume that deleting an 1GB file frees 1GB space.

func (TestHookState) RPCHint 

func (s TestHookState) RPCHint() *RPCHint

RPCHint returns information needed to establish gRPC connections. It can only be called by remote entities.

func (TestHookState) RequiredVar 

func (s TestHookState) RequiredVar(name string) string

RequiredVar is similar to Var but aborts the entity if the named variable was not supplied.

func (TestHookState) ServiceDeps 

func (s TestHookState) ServiceDeps() []string

ServiceDeps returns service dependencies declared in the currently running entity.

func (TestHookState) SoftwareDeps 

func (s TestHookState) SoftwareDeps() []string

SoftwareDeps returns software dependencies declared in the currently running entity.

func (TestHookState) TestName 

func (s TestHookState) TestName() string

TestName returns the name of the currently running test.

func (TestHookState) Var 

func (s TestHookState) Var(name string) (val string, ok bool)

Var returns the value for the named variable, which must have been registered via Vars. If a value was not supplied at runtime via the -var flag to "tast run", ok will be false.

type TestInstance 

type TestInstance struct {
	// Name specifies the test's name as "category.TestName".
	// The name is derived from Func's package and function name.
	// The category is the final component of the package.
	Name string

	// Pkg contains the Go package in which Func is located.
	Pkg string

	// ExitTimeout contains the maximum duration to wait for Func to exit after a timeout.
	// The context passed to Func has a deadline based on Timeout, but Tast waits for an additional ExitTimeout to elapse
	// before reporting that the test has timed out; this gives the test function time to return after it
	// sees that its context has expired before an additional error is added about the timeout.
	// This is exposed for unit tests and should almost always be omitted when defining tests;
	// a reasonable default will be used.
	// TODO(oka): Remove ExitTimeout using CustomGracePeriod in planner.Config .
	ExitTimeout time.Duration

	// Val contains the value inherited from the expanded Param struct for a parameterized test case.
	// This can be retrieved from testing.State.Param().
	Val interface{}

	Func         TestFunc
	Desc         string
	Contacts     []string
	Attr         []string
	PrivateAttr  []string
	SearchFlags  []*protocol.StringPair
	Data         []string
	Vars         []string
	VarDeps      []string
	SoftwareDeps map[string]dep.SoftwareDeps
	// HardwareDeps field is not in the protocol yet. When the scheduler in infra is
	// implemented, it is needed.
	HardwareDeps map[string]dep.HardwareDeps
	ServiceDeps  []string
	LacrosStatus LacrosMetadata
	Pre          Precondition
	Fixture      string
	Timeout      time.Duration

	// Bundle is the name of the test bundle this test belongs to.
	// This field is empty initially, and later set when the test is added
	// to testing.Registry.
	Bundle string

	// TestBedDeps, Requirements, Purpose, and BugComponent are only used
	// by infra and should not be used in tests.
	TestBedDeps  []string
	Requirements []string
	BugComponent string
}

TestInstance represents a test instance registered to the framework.

A test instance is the unit of "tests" exposed to outside of the framework. For example, in the command line of the "tast" command, users specify which tests to run by names of test instances. Single testing.AddTest call may register multiple test instances at once if testing.Test passed to the function has non-empty Params field.

func (*TestInstance) Constraints 

func (t *TestInstance) Constraints() *EntityConstraints

Constraints returns EntityConstraints for this test.

func (*TestInstance) Deps 

func (t *TestInstance) Deps() *dep.Deps

Deps dependencies of this test.

func (*TestInstance) EntityProto 

func (t *TestInstance) EntityProto() *protocol.Entity

EntityProto a protocol buffer message representation of TestInstance.

func (*TestInstance) Proto 

func (t *TestInstance) Proto() *api.TestCaseMetadata

Proto converts test metadata of TestInstance into a protobuf message.

func (*TestInstance) String 

func (t *TestInstance) String() string

type Var 

type Var interface {
	// Unmarshal convert a string to Var's value type and set it to Var.
	Unmarshal(data string) error

	// Name return the name of the variable.
	Name() string
}

Var define an interface for global runtime variable types.

type VarString 

type VarString struct {
	// contains filtered or unexported fields
}

VarString define a structure for global runtime variables of string type.

func NewVarString 

func NewVarString(name, defaultValue, desc string) *VarString

NewVarString creates a new VarString

func (*VarString) Name 

func (v *VarString) Name() string

Name returns the name of the variable.

func (*VarString) Unmarshal 

func (v *VarString) Unmarshal(data string) error

Unmarshal extract a string and set the value of variable type to the variable.

func (*VarString) Value 

func (v *VarString) Value() string

Value returns value of a variable and a flag to indicate whether the value is initialized.

Source Files

View all Source files

Directories

Path Synopsis
Package testfixture provides an implementation of testing.FixtureImpl to be used in unit tests.
 Package testfixture provides an implementation of testing.FixtureImpl to be used in unit tests.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.