td

package
v0.0.0-...-b24f37d Latest Latest
Warning

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

 Go to latest Published: Nov 27, 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)

RunTestSteps runs testing steps inside the given context.

func RunTestStepsWithContext 

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

RunTestStepsWithContext is the same as RunTestSteps but uses 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 StartTestRunWithContext 

func StartTestRunWithContext(t sktest.TestingT, ctx context.Context) *TestingRun

StartTestRunWithContext is like StartTestRun but uses the given Context.

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.

Source Files

View all Source files

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.