control

Documentation

Overview

Package control writes and reads control messages describing the state of a test run.

Control messages are JSON-marshaled and used for communication from test executables to the main tast binary. A typical sequence is as follows:

RunStart (run started)
	RunLog (run logged a message)
	EntityStart (first test started)
		EntityLog (first test logged a message)
	EntityEnd (first test ended)
	EntityStart (second test started)
		EntityLog (second test logged a message)
		EntityError (second test encountered an error)
		EntityError (second test encountered another error)
		EntityLog (second test logged another message)
	EntityEnd (second test ended)
RunEnd (run ended)

Control messages of different types are unmarshaled into a single messageUnion struct. To be able to infer a message's type, each message struct must contain a Time field with a message-type-prefixed JSON name (e.g. "runStartTime" for RunStart.Time), and all other fields must be similarly namespaced.

Index

• type EntityEnd
• type EntityError
• type EntityLog
• type EntityStart
• type Heartbeat
• type HeartbeatWriter
  • func NewHeartbeatWriter(mw *MessageWriter, d time.Duration) *HeartbeatWriter
  • func (w *HeartbeatWriter) Stop()
• type MessageReader
  • func NewMessageReader(r io.Reader) *MessageReader
  • func (mr *MessageReader) More() bool
  • func (mr *MessageReader) ReadMessage() (Msg, error)
• type MessageWriter
  • func NewMessageWriter(w io.Writer) *MessageWriter
  • func (mw *MessageWriter) WriteMessage(msg Msg) error
• type Msg
• type RunEnd
• type RunError
• type RunLog
• type RunStart

Types

type EntityEnd

type EntityEnd struct {
	// Time is the device-local time at which the entity ended.
	Time time.Time `json:"testEndTime"`
	// Name is the name of the entity, matching the earlier EntityStart.Test.Name.
	Name string `json:"testEndName"`
	// DeprecatedMissingSoftwareDeps contains software dependencies declared by the test that were
	// not present on the DUT. If non-empty, the test was skipped.
	// DEPRECATED: This field is no longer filled by newer bundles.
	DeprecatedMissingSoftwareDeps []string `json:"testEndMissingSoftwareDeps"`
	// SkipReasons contains messages describing why the test was skipped.
	// If non-empty, the test was skipped.
	// In the case of non-test entities, this field is always empty.
	SkipReasons []string `json:"testEndHardwareDepsUnsatisfiedReasons"`
	// TimingLog contains entity-reported timing information to be incorporated into the main timing.json file.
	TimingLog *timing.Log `json:"testEndTimingLog"`
}

EntityEnd describes the end of an individual entity.

type EntityError

type EntityError struct {
	// Time is the device-local time at which the error occurred.
	Time time.Time `json:"testErrorTime"`
	// Error describes the error that occurred.
	Error testing.Error `json:"testErrorError"`
	// Name is the name of the entity, matching the earlier EntityStart.Test.Name.
	Name string `json:"testErrorName"`
}

EntityError contains an error produced by an entity.

type EntityLog

type EntityLog struct {
	// Time is the device-local time at which the message was logged.
	Time time.Time `json:"testLogTime"`
	// Text is the actual message.
	Text string `json:"testLogText"`
	// Name is the name of the entity, matching the earlier EntityStart.Test.Name.
	Name string `json:"testLogName"`
}

EntityLog contains an informative logging message produced by an entity.

type EntityStart

type EntityStart struct {
	// Time is the device-local time at which the entity started.
	Time time.Time `json:"testStartTime"`
	// Info contains details about the entity.
	Info testing.EntityInfo `json:"testStartTest"`
	// OutDir is a directory path where output files for the entity is written.
	// OutDir can be empty if the entity is being skipped.
	// When set, OutDir is a direct subdirectory of bundle.RunTestsArgs.OutDir.
	OutDir string `json:"testStartOutDir"`
}

EntityStart describes the start of an individual entity.

type Heartbeat

type Heartbeat struct {
	// Time is the device-local time at which this message was generated.
	Time time.Time `json:"heartbeatTime"`
}

Heartbeat is sent periodically to assert that the bundle is alive.

type HeartbeatWriter

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

HeartbeatWriter writes heartbeat messages periodically to MessageWriter.

func NewHeartbeatWriter

func NewHeartbeatWriter(mw *MessageWriter, d time.Duration) *HeartbeatWriter

NewHeartbeatWriter constructs a new HeartbeatWriter for mw. d is the interval at which heartbeat messages are written. if d is non-positive, no heartbeat message will be written. In any case, Stop must be called after use to stop the background goroutine.

func (*HeartbeatWriter) Stop

func (w *HeartbeatWriter) Stop()

Stop stops the background goroutine to write heartbeat messages. Once this method returns, heartbeat messages are no longer written. Be aware that this method may block if the writer is blocking. It is safe to call Stop multiple times.

type MessageReader

type MessageReader json.Decoder

MessageReader is used by the tast executable to interpret output from tests.

func NewMessageReader

func NewMessageReader(r io.Reader) *MessageReader

NewMessageReader returns a new MessageReader for reading from r.

func (*MessageReader) More

func (mr *MessageReader) More() bool

More returns true if more messages are available.

func (*MessageReader) ReadMessage

func (mr *MessageReader) ReadMessage() (Msg, error)

ReadMessage reads and returns the next message.

type MessageWriter

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

MessageWriter is used by executables containing tests to write messages describing the state of testing. It is safe to call its methods concurrently from multiple goroutines.

func NewMessageWriter

func NewMessageWriter(w io.Writer) *MessageWriter

NewMessageWriter returns a new MessageWriter for writing to w.

func (*MessageWriter) WriteMessage

func (mw *MessageWriter) WriteMessage(msg Msg) error

WriteMessage writes msg.

type Msg

type Msg interface {
	// contains filtered or unexported methods
}

Msg is an interface implemented by all message types.

type RunEnd

type RunEnd struct {
	// Time is the device-local time at which the run ended.
	Time time.Time `json:"runEndTime"`
	// OutDir is the base directory under which tests wrote output files.
	// DEPRECATED: Client should always set OutDir in the request.
	// TODO(crbug.com/1000549): Remove this field after 20191201.
	OutDir string `json:"runEndOutDir"`
}

RunEnd describes the completion of a run.

type RunError

type RunError struct {
	// Time is the device-local time at which the error occurred.
	Time time.Time `json:"runErrorTime"`
	// Error describes the error that occurred.
	Error testing.Error `json:"runErrorError"`
	// Status is the exit status code of the test runner if it is run directly.
	Status int `json:"runErrorStatus"`
}

RunError describes a fatal, high-level error encountered during the run. This may be encountered at any time (including before RunStart) and indicates that the run has been aborted.

type RunLog

type RunLog struct {
	// Time is the device-local time at which the message was logged.
	Time time.Time `json:"runLogTime"`
	// Text is the actual message.
	Text string `json:"runLogText"`
}

RunLog contains an informative, high-level logging message produced by a run.

type RunStart

type RunStart struct {
	// Time is the device-local time at which the run started.
	Time time.Time `json:"runStartTime"`
	// TestNames contains the names of tests to run, in the order in which they'll be executed.
	// Note that some of these tests may later be skipped (see EntityEnd).
	TestNames []string `json:"runStartTestNames"`
	// NumTests is the number of tests that will be run.
	// TODO(derat): Delete this after 20190715; the tast command now uses TestNames instead: https://crbug.com/889119
	NumTests int `json:"runStartNumTests"`
}

RunStart describes the start of a run (consisting of one or more tests).