testing

Documentation

Overview

Package testing provides public API for tests.

Package testing provides public API for tests.

Index

• func AddFixture(f *Fixture)
• func AddService(s *Service)
• func AddTest(t *Test)
• func ContextLog(ctx context.Context, args ...interface{})
• func ContextLogf(ctx context.Context, format string, args ...interface{})
• func ContextOutDir(ctx context.Context) (dir string, ok bool)
• func ContextSoftwareDeps(ctx context.Context) ([]string, bool)
• func NewTestGlobRegexp(g string) (*regexp.Regexp, error)
• func Poll(ctx context.Context, f func(context.Context) error, opts *PollOptions) error
• func PollBreak(err error) error
• func RegistrationErrors() []error
• func Sleep(ctx context.Context, d time.Duration) error
• type CloudStorage
• type FixtState
• type FixtTestState
• type Fixture
• type FixtureImpl
• type Logger
  • func ContextLogger(ctx context.Context) (*Logger, bool)
  • func (l *Logger) Print(args ...interface{})
  • func (l *Logger) Printf(format string, args ...interface{})
• type Meta
• type Param
• type PollOptions
• type PreState
• type Precondition
• type RPCHint
• type Service
• type ServiceState
• type State
• type Test
• type TestHookState
• type TestInstance

Functions

func AddFixture

func AddFixture(f *Fixture)

AddFixture adds fixture f to the global registry.

func AddService

func AddService(s *Service)

AddService adds service s to the global registry. This should be called only once in a service main file's init().

func AddTest

func AddTest(t *Test)

AddTest adds test t to the global registry. This should be called only once in a test main file's init(), and it should be the top level statement of the init()'s body. The argument of AddTest() in the case should be a pointer to a composite literal of testing.Test.

func ContextLog

func ContextLog(ctx context.Context, args ...interface{})

ContextLog formats its arguments using default formatting and logs them via ctx. It is intended to be used for informational logging by packages providing support for tests. If testing.State is available, just call State.Log or State.Logf instead.

func ContextLogf

func ContextLogf(ctx context.Context, format string, args ...interface{})

ContextLogf is similar to ContextLog but formats its arguments using fmt.Sprintf.

func ContextOutDir

func ContextOutDir(ctx context.Context) (dir string, ok bool)

ContextOutDir is similar to OutDir but takes context instead. It is intended to be used by packages providing support for tests that need to write files.

func ContextSoftwareDeps

func ContextSoftwareDeps(ctx context.Context) ([]string, bool)

ContextSoftwareDeps is similar to SoftwareDeps but takes context instead. It is intended to be used by packages providing support for tests that want to make sure tests declare proper dependencies.

func NewTestGlobRegexp

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

NewTestGlobRegexp returns a compiled regular expression corresponding to g, a glob for matching test names.

DEPRECATED: Tests should not use this function.

func Poll

func Poll(ctx context.Context, f func(context.Context) error, opts *PollOptions) error

Poll runs f repeatedly until f returns nil and then itself returns nil. If ctx returns an error before then or opts.Timeout is reached, the last error returned by f is returned. f should use the context passed to it, as it may have an adjusted deadline if opts.Timeout is set. If ctx's deadline has already been reached, f will not be invoked. If opts is nil, reasonable defaults are used.

Polling often results in increased load and slower execution (since there's a delay between when something happens and when the next polling cycle notices it). It should only be used as a last resort when there's no other way to watch for an event. The preferred approach is to watch for events in select{} statements. Goroutines can be used to provide notifications over channels. If an error wrapped by PollBreak is returned, then it immediately terminates the polling, and returns the unwrapped error.

func PollBreak

func PollBreak(err error) error

PollBreak creates an error wrapping err that may be returned from a function passed to Poll to terminate polling immediately. For example:

err := testing.Poll(ctx, func(ctx context.Context) error {
  if err := mustSucceed(ctx); err != nil {
    return testing.PollBreak(err)
  }
  ...
})

func RegistrationErrors

func RegistrationErrors() []error

RegistrationErrors returns errors generated by calls to AddTest.

func Sleep

func Sleep(ctx context.Context, d time.Duration) error

Sleep pauses the current goroutine for d or until ctx expires.

Please consider using testing.Poll instead. Sleeping without polling for a condition is discouraged, since it makes tests flakier (when the sleep duration isn't long enough) or slower (when the duration is too long).

Types

type CloudStorage

type CloudStorage = testing.CloudStorage

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

type FixtState

type FixtState = testing.FixtState

FixtState holds state relevant to the execution of a fixture.

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

type FixtTestState

type FixtTestState = testing.FixtTestState

FixtTestState holds state relevant to the execution of test hooks in a fixture.

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

type Fixture

type Fixture = testing.Fixture

Fixture describes a fixture registered to the framework.

type FixtureImpl

type FixtureImpl = testing.FixtureImpl

FixtureImpl is an interface fixtures should implement.

type Logger

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

Logger allows test helpers to log messages when no context.Context or testing.State is available.

func ContextLogger

func ContextLogger(ctx context.Context) (*Logger, bool)

ContextLogger returns Logger from a context.

func (*Logger) Print

func (l *Logger) Print(args ...interface{})

Print formats its arguments using default formatting and logs them.

func (*Logger) Printf

func (l *Logger) Printf(format string, args ...interface{})

Printf is similar to Print but formats its arguments using fmt.Sprintf.

type Meta

type Meta = testing.Meta

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 Param

type Param = testing.Param

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 PollOptions

type PollOptions = testingutil.PollOptions

PollOptions may be passed to Poll to configure its behavior.

type PreState

type PreState = testing.PreState

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.

type Precondition

type Precondition = testing.Precondition

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

type RPCHint

type RPCHint = testing.RPCHint

RPCHint contains information needed to establish gRPC connections.

type Service

type Service = testing.Service

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

type ServiceState

type ServiceState = testing.ServiceState

ServiceState holds state relevant to a gRPC service.

type State

type State = testing.State

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.

type Test

type Test = testing.Test

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 TestHookState

type TestHookState = testing.TestHookState

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.

type TestInstance

type TestInstance = testing.TestInstance

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.