td

package
v0.0.0-...-13f153f Latest Latest
Warning

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

Go to latest
Published: May 3, 2024 License: BSD-3-Clause Imports: 32 Imported by: 22

Documentation

Index

Constants

View Source
const (
	MsgType_RunStarted    MessageType = "RUN_STARTED"
	MsgType_StepStarted   MessageType = "STEP_STARTED"
	MsgType_StepFinished  MessageType = "STEP_FINISHED"
	MsgType_StepData      MessageType = "STEP_DATA"
	MsgType_StepFailed    MessageType = "STEP_FAILED"
	MsgType_StepException MessageType = "STEP_EXCEPTION"

	DataType_Log          DataType = "log"
	DataType_Text         DataType = "text"
	DataType_Command      DataType = "command"
	DataType_HttpRequest  DataType = "httpRequest"
	DataType_HttpResponse DataType = "httpResponse"
)
View Source
const (
	// SeverityDebug is the lowest, most verbose log severity, containing
	// messages only needed for detailed debugging.
	SeverityDebug = Severity(logging.Debug)
	// SeverityInfo is the base severity level for normal, informational
	// messages.
	SeverityInfo = Severity(logging.Info)
	// SeverityWarning indicates higher-priority messages which may indicate a
	// problem of some kind.
	SeverityWarning = Severity(logging.Warning)
	// SeverityError indicates high-priority messages which report actual
	// errors.
	SeverityError = Severity(logging.Error)
)
View Source
const (
	// PubsubTopicLogs is the PubSub topic name for task driver logs.
	PubsubTopicLogs = "task-driver-logs"

	// StepIDRoot is the fixed ID of the root step.
	StepIDRoot = "root"

	// EnvVarWrappedStepID indicates that a task driver is nested inside of
	// another, with the given step ID as its parent.
	EnvVarWrappedStepID = "TASK_DRIVER_WRAPPED_STEP_ID"
)

Variables

View Source
var (
	// BaseEnv is the basic set of environment variables provided to all steps.
	BaseEnv = []string{
		"CHROME_HEADLESS=1",
		"GIT_USER_AGENT=git/1.9.1",
	}
)

Functions

func Do

func Do(ctx context.Context, props *StepProperties, fn func(context.Context) error) error

Do is a convenience function which runs the given function as a Step. It handles creation of the sub-step and calling EndStep() for you.

func EndRun

func EndRun(ctx context.Context)

EndRun performs any cleanup work for the run. Should be deferred in main().

func EndStep

func EndStep(ctx context.Context)

EndStep marks the Step as finished. This is intended to be used in a defer, eg.

ctx = td.StartStep(ctx)
defer td.EndStep(ctx)

If a panic is recovered in EndStep, the step is marked as failed and the panic is re-raised.

func FailStep

func FailStep(ctx context.Context, err error) error

FailStep marks the step as failed, with the given error. Returns the assed-in error for convenience, so that the caller can do things like:

if err := doSomething(); err != nil {
	return FailStep(ctx, err)
}

func Fatal

func Fatal(ctx context.Context, err error)

Fatal is a substitute for sklog.Fatal which logs an error and panics. sklog.Fatal does not panic but calls os.Exit, which prevents the Task Driver from properly reporting errors.

func Fatalf

func Fatalf(ctx context.Context, format string, a ...interface{})

Fatalf is a substitute for sklog.Fatalf which logs an error and panics. sklog.Fatalf does not panic but calls os.Exit, which prevents the Task Driver from properly reporting errors.

func GetEnv

func GetEnv(ctx context.Context) []string

GetEnv returns the Environment variables.

func HttpClient

func HttpClient(ctx context.Context, c *http.Client) *http.Client

HttpClient returns an http.Client which wraps the given http.Client to record data about the requests it sends.

func InfraError

func InfraError(err error) error

InfraError wraps the given error, indicating that it is an infrastructure- related error. If the given error is already an InfraError, returns it as-is.

func IsInfraError

func IsInfraError(err error) bool

IsInfraError returns true if the given error is an infrastructure error.

func MergeEnv

func MergeEnv(base, other []string) []string

MergeEnv merges the second env into the base, returning a new env with the original unchanged. Variables in the second env override those in the base, except for PATH, which is merged. If PATH defined by the second env contains %(PATH)s, then the result is the PATH from the second env with PATH from the first env inserted in place of %(PATH)s. Otherwise, the PATH from the second env overrides PATH from the first. Note that setting PATH to the empty string in the second env will cause PATH to be empty in the result!

func MustGetAbsolutePathOfFlag

func MustGetAbsolutePathOfFlag(ctx context.Context, nonEmptyPath, flag string) string

MustGetAbsolutePathOfFlag returns the absolute path to the specified path or exits with an error indicating that the given flag must be specified.

func NewLogStream

func NewLogStream(ctx context.Context, name string, severity Severity) io.Writer

NewLogStream creates an io.Writer that will act as a log stream for this Step. Callers probably want to use a higher-level method instead.

func StartRun

func StartRun(projectId, taskId, taskName, output *string, local *bool) context.Context

StartRun begins a new test automation run, panicking if any setup fails.

func StartRunWithErr

func StartRunWithErr(projectId, taskId, taskName, output *string, local *bool) (context.Context, error)

StartRunWithErr begins a new test automation run, returning any error which occurs.

func StartStep

func StartStep(ctx context.Context, props *StepProperties) context.Context

StartStep creates a new Step.

func StepData

func StepData(ctx context.Context, typ DataType, d interface{})

StepData attaches the given StepData to this Step.

func StepText

func StepText(ctx context.Context, label, value string)

StepText displays the provided text with the label in the Step's UI. The text will be escaped and URLs in it will be linkified.

func WithEnv

func WithEnv(ctx context.Context, env []string) context.Context

Set the given environment on the Context. Steps which use the Context will inherit the environment variables. Merges with any previous calls to WithEnv.

func WithExecRunFn

func WithExecRunFn(ctx context.Context, run func(context.Context, *exec.Command) error) context.Context

WithExecRunFn allows the Run function to be overridden for testing.

func WithRetries

func WithRetries(ctx context.Context, attempts int, fn func(ctx context.Context) error) error

WithRetries runs the given function until it succeeds or the given number of attempts is exhausted, returning the last error or nil if the function completed successfully.

Types

type CloudLoggingReceiver

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

CloudLoggingReceiver is a Receiver which sends step metadata and logs to Cloud Logging.

func NewCloudLoggingReceiver

func NewCloudLoggingReceiver(logger *logging.Logger) (*CloudLoggingReceiver, error)

NewCloudLoggingReceiver returns a CloudLoggingReceiver instance. This initializes Cloud Logging for the entire test run.

func (*CloudLoggingReceiver) Close

func (r *CloudLoggingReceiver) Close() error

Close implements Receiver.

func (*CloudLoggingReceiver) HandleMessage

func (r *CloudLoggingReceiver) HandleMessage(m *Message) error

HandleMessage implements Receiver.

func (*CloudLoggingReceiver) LogStream

func (r *CloudLoggingReceiver) LogStream(stepId, logId string, severity Severity) (io.Writer, error)

LogStream implements Receiver.

type Context

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

type DataType

type DataType string

DataType indicates the type of a piece of data attached to a step.

type DebugReceiver

type DebugReceiver struct{}

DebugReceiver just dumps the messages straight to the log (stdout/stderr, not to Cloud Logging).

func (*DebugReceiver) Close

func (r *DebugReceiver) Close() error

Close implements Receiver.

func (*DebugReceiver) HandleMessage

func (r *DebugReceiver) HandleMessage(m *Message) error

HandleMessage implements Receiver.

func (*DebugReceiver) LogStream

func (r *DebugReceiver) LogStream(stepId, logId string, severity Severity) (io.Writer, error)

LogStream implements Receiver.

type ExecData

type ExecData struct {
	Cmd []string `json:"command"`
	Dir string   `json:"dir"`
	Env []string `json:"env,omitempty"`
}

ExecData is extra Step data generated when executing commands through the exec package.

type FileStream

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

FileStream is a struct used for streaming logs from a file, eg. when a test program writes verbose logs to a file. Intended to be used like this:

fs := s.NewFileStream("verbose")
defer util.Close(fs)
_, err := s.RunCwd(".", myTestProg, "--verbose", fs.FilePath())

func NewFileStream

func NewFileStream(ctx context.Context, name string, severity Severity) (*FileStream, error)

NewFileStream creates a log stream which uses an intermediate file, eg. for writing from a test program.

func (*FileStream) Close

func (fs *FileStream) Close() error

Close the FileStream, cleaning up its resources and deleting the log file.

func (*FileStream) FilePath

func (fs *FileStream) FilePath() string

FilePath returns the path to the logfile used by this FileStream.

type HttpRequestData

type HttpRequestData struct {
	Method string   `json:"method,omitempty"`
	URL    *url.URL `json:"url,omitempty"`
}

HttpRequestData is Step data describing an http.Request. Notably, it does not include the request body or headers, to avoid leaking auth tokens or other sensitive information.

type HttpResponseData

type HttpResponseData struct {
	StatusCode int `json:"status,omitempty"`
}

HttpResponseData is Step data describing an http.Response. Notably, it does not include the response body, to avoid leaking sensitive information.

type LogData

type LogData struct {
	Name     string `json:"name"`
	Id       string `json:"id"`
	Severity string `json:"severity"`
	Log      string `json:"log,omitempty"`
}

LogData is extra Step data generated for log streams.

type Message

type Message struct {
	// ID is the unique identifier for this message. This is required for every
	// Message.
	ID string `json:"id"`

	// Index is a monotonically increasing index of the message within the
	// Task. Deprecated.
	Index int `json:"index"`

	// StepId indicates the ID for the step. This is required for every
	// Message except MSG_TYPE_RUN_STARTED.
	StepId string `json:"stepId,omitempty"`

	// TaskId indicates the ID of this task. This is required for every
	// Message.
	TaskId string `json:"taskId"`

	// Timestamp is the time at which the Message was created. This is
	// required for every Message.
	Timestamp time.Time `json:"timestamp"`

	// Type indicates the type of message, which dictates which fields must
	// be filled.
	Type MessageType `json:"type"`

	// Run is the metadata about the overall Task Driver run. Required for
	// MSG_TYPE_RUN_STARTED.
	Run *RunProperties `json:"run,omitempty"`

	// Step is the metadata about the step at creation time. Required for
	// MSG_TYPE_STEP_STARTED.
	Step *StepProperties `json:"step,omitempty"`

	// Error is any error which might have occurred. Required for
	// MSG_TYPE_STEP_FAILED and MSG_TYPE_STEP_EXCEPTION.
	Error string `json:"error,omitempty"`

	// Data is arbitrary additional data about the step. Required for
	// MSG_TYPE_STEP_DATA.
	Data interface{} `json:"data,omitempty"`

	// DataType describes the contents of Data. Required for
	// MSG_TYPE_STEP_DATA.
	DataType DataType `json:"dataType,omitempty"`
}

Message is a struct used to send step metadata to Receivers.

func (*Message) Validate

func (m *Message) Validate() error

Return an error if the Message is not valid.

type MessageType

type MessageType string

MessageType indicates the type of a Message.

type MultiReceiver

type MultiReceiver []Receiver

MultiReceiver is a Receiver which multiplexes messages to multiple Receivers.

func (MultiReceiver) Close

func (r MultiReceiver) Close() error

Close implements Receiver.

func (MultiReceiver) HandleMessage

func (r MultiReceiver) HandleMessage(m *Message) error

HandleMessage implements Receiver.

func (MultiReceiver) LogStream

func (r MultiReceiver) LogStream(stepId, logId string, severity Severity) (io.Writer, error)

LogStream implements Receiver.

type Receiver

type Receiver interface {
	// Handle the given message.
	HandleMessage(*Message) error
	LogStream(stepId string, logId string, severity Severity) (io.Writer, error)
	Close() error
}

Receiver is an interface used to implement arbitrary receivers of step metadata, as steps are run.

type ReportReceiver

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

ReportReceiver collects all messages and generates a report when requested.

func (*ReportReceiver) Close

func (r *ReportReceiver) Close() error

Close implements Receiver.

func (*ReportReceiver) HandleMessage

func (r *ReportReceiver) HandleMessage(m *Message) error

HandleMessage implements Receiver.

func (*ReportReceiver) LogStream

func (r *ReportReceiver) LogStream(stepId, logId string, _ Severity) (io.Writer, error)

LogStream implements Receiver.

type RunProperties

type RunProperties struct {
	Local          bool   `json:"local"`
	SwarmingBot    string `json:"swarmingBot,omitempty"`
	SwarmingServer string `json:"swarmingServer,omitempty"`
	SwarmingTask   string `json:"swarmingTask,omitempty"`
}

RunProperties are properties for a single run of a Task Driver.

func (*RunProperties) Copy

func (p *RunProperties) Copy() *RunProperties

Copy returns a copy of the RunProperties.

func (*RunProperties) Validate

func (p *RunProperties) Validate() error

Validate implements util.Validator.

type Severity

type Severity int

Severity indicates the importance of a LogStream, with greater values indicating greater severity. Valid values include Debug, Info, Warning, and Error.

func (Severity) String

func (s Severity) String() string

String returns the name of s.

type StepProperties

type StepProperties struct {
	// ID of the step. This is set by the framework and should not be set
	// by callers.
	Id string `json:"id"`

	// Name of the step.
	Name string `json:"name"`

	// If true, this step is marked as infrastructure-specific.
	IsInfra bool `json:"isInfra"`

	// All subprocesses spawned for this step will inherit these environment
	// variables.
	Environ []string `json:"environment,omitempty" go2ts:"ignorenil"`

	// Parent step ID. This is set by the framework and should not be set
	// by callers.
	Parent string `json:"parent,omitempty"`
}

StepProperties are basic properties of a step.

func Props

func Props(name string) *StepProperties

Props sets the name of the step. It returns a StepProperties instance which can be further modified by the caller.

func (*StepProperties) Copy

func (p *StepProperties) Copy() *StepProperties

Copy returns a deep copy of the StepProperties.

func (*StepProperties) Env

func (p *StepProperties) Env(env []string) *StepProperties

Env applies the given environment variables to all commands run within this step. Note that this does NOT apply the variables to the environment of this process, just of subprocesses spawned using the context.

func (*StepProperties) Infra

func (p *StepProperties) Infra() *StepProperties

Infra marks the step as infrastructure-specific.

func (*StepProperties) Validate

func (p *StepProperties) Validate() error

Return an error if the StepProperties are not valid.

type StepReport

type StepReport struct {
	*StepProperties
	Data       []interface{} `json:"data,omitempty"`
	Errors     []string      `json:"errors,omitempty"`
	Exceptions []string      `json:"exceptions,omitempty"`
	Logs       map[string]*bytes.Buffer
	Result     StepResult    `json:"result,omitempty"`
	Steps      []*StepReport `json:"steps,omitempty"`
}

StepReport is a struct used to collect information about a given step.

func RunTestSteps

func RunTestSteps(t sktest.TestingT, expectPanic bool, fn func(context.Context) error) (rv *StepReport)

Run testing steps inside the given context.

func (*StepReport) Recurse

func (s *StepReport) Recurse(fn func(*StepReport) bool) bool

Recurse through all steps, running the given function. If the function returns false, recursion stops.

type StepResult

type StepResult string

StepResult represents the result of a Step.

const (
	// StepResultSuccess indicates that the step finished successfully.
	StepResultSuccess StepResult = "SUCCESS"
	// StepResultFailure indicates that the step failed.
	StepResultFailure StepResult = "FAILURE"
	// StepResultException indicates that the step failed in an exceptional way,
	// eg. it timed out or was interrupted.
	StepResultException StepResult = "EXCEPTION"

	// PathPlaceholder is a placeholder for any existing value of PATH,
	// used when merging environments to avoid overriding the PATH
	// altogether.
	PathPlaceholder = "%(PATH)s"
)

type TestingRun

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

func StartTestRun

func StartTestRun(t sktest.TestingT) *TestingRun

StartTestRun returns a root-level Step to be used for testing. This is an alternative so that we don't need to call Init() in testing.

func (*TestingRun) Cleanup

func (r *TestingRun) Cleanup()

Cleanup the TestingRun.

func (*TestingRun) Dir

func (r *TestingRun) Dir() string

Return the temporary dir used for this TestingRun.

func (*TestingRun) EndRun

func (r *TestingRun) EndRun(expectPanic bool, err *error) *StepReport

Finish the test Step and return its results.

func (*TestingRun) Root

func (r *TestingRun) Root() context.Context

Return the root-level Step.

type TextData

type TextData struct {
	Label string `json:"label"`
	Value string `json:"value"`
}

TextData is extra Step data for displaying a text in a step. The provided text will be escaped and URLs in it will be linkified.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL