job

package
v1.0.1 Latest Latest
Warning

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

 Go to latest Published: Aug 8, 2022 License: MIT Imports: 15 Imported by: 1

Documentation

Index

Constants

View Source 
const InternalTagPrefix = "_"

InternalTagPrefix denotes tags that can only be manipulated by the server.

View Source 
const JobDescriptorMajorVersion uint = 1

JobDescriptorMajorVersion, JobDescriptorMinorVersion are the current version of the job descriptor that the client must speaks to descripe jobs. It has two numbers to denote breaking and non-breaking changes

View Source 
const JobDescriptorMinorVersion uint = 0

Variables

View Source 
var CurrentPauseEventPayloadVersion = 1

Currently supported version of the pause state. Attempting to resume paused jobs with version other than this will fail.

View Source 
var EventJobCancellationFailed = event.Name("JobStateCancellationFailed")

EventJobCancellationFailed indicates that the cancellation was not completed correctly

View Source 
var EventJobCancelled = event.Name("JobStateCancelled")

EventJobCancelled indicates that a Job has been cancelled

View Source 
var EventJobCancelling = event.Name("JobStateCancelling")

EventJobCancelling indicates that a Job has received a cancellation request and the JobManager is waiting for JobRunner to return

View Source 
var EventJobCompleted = event.Name("JobStateCompleted")

EventJobCompleted indicates that a Job has completed

View Source 
var EventJobFailed = event.Name("JobStateFailed")

EventJobFailed indicates that a Job has failed

View Source 
var EventJobPauseFailed = event.Name("JobStatePauseFailed")

EventJobPauseFailed indicates that a Job pausing was not completed correctly

View Source 
var EventJobPaused = event.Name("JobStatePaused")

EventJobPaused indicates that a Job was paused

View Source 
var EventJobStarted = event.Name("JobStateStarted")

EventJobStarted indicates that a Job is beginning execution

View Source 
var JobCompletionEvents = []event.Name{
	EventJobCompleted,
	EventJobFailed,
	EventJobCancelled,
	EventJobCancellationFailed,
}

JobCompletionEvents gathers all event names that mark the end of a job

View Source 
var JobStateEvents = []event.Name{
	EventJobStarted,
	EventJobCompleted,
	EventJobFailed,
	EventJobPaused,
	EventJobPauseFailed,
	EventJobCancelling,
	EventJobCancelled,
	EventJobCancellationFailed,
}

JobStateEvents gathers all event names which track the state of a job

Functions

func AddTags 

func AddTags(tags []string, moreTags ...string) []string

AddTags adds one ore more tags to tags unless already present.

func CheckTags 

func CheckTags(tags []string, allowInternal bool) error

CheckTags validates the format of tags, only allowing [a-zA-Z0-9_-] and checking for dups.

func CurrentDescriptorVersion 

func CurrentDescriptorVersion() string

CurrentDescriptorVersion returns current JobDescriptor version as a string e.g "1.0"

func IsInternalTag 

func IsInternalTag(tag string) bool

IsInternalTag returns true if a tag is an internal tag.

func IsValidTag 

func IsValidTag(tag string, allowInternal bool) error

IsValidTag validates the format of tags, only allowing [a-zA-Z0-9_-].

Types

type Descriptor 

type Descriptor struct {
	JobName                     string
	Version                     string
	Tags                        []string
	Runs                        uint
	RunInterval                 xjson.Duration
	TestDescriptors             []*test.TestDescriptor
	Reporting                   Reporting
	TargetManagerAcquireTimeout *xjson.Duration // optional
	TargetManagerReleaseTimeout *xjson.Duration // optional
}

Descriptor models the deserialized version of the JSON text given as input to the job creation request.

func (*Descriptor) CheckVersion 

func (d *Descriptor) CheckVersion() error

CheckVersion checks the compatibility of the received descriptor version against the supported one

func (*Descriptor) Validate 

func (d *Descriptor) Validate() error

Validate performs sanity checks on the job descriptor

type ExtendedDescriptor 

type ExtendedDescriptor struct {
	Descriptor
	TestStepsDescriptors []test.TestStepsDescriptors
}

ExtendedDescriptor is a job descriptor which has been extended with the full description of the test obtained from the test fetcher (which might not be a literal embedded in the job descriptor itself). A TestStepDescriptors object represents the test steps of a single test, associated to the test name. As one job might consist in multiple tests, the extended descriptor needs to capture a list of TestStepDescriptors, one for each test.

type InfoFetcher 

type InfoFetcher interface {
	FetchJob(types.JobID) (*Job, error)
	FetchJobs([]types.JobID) ([]*Job, error)
	FetchJobIDsByServerID(serverID string) ([]types.JobID, error)
}

InfoFetcher defines how to fetch job information

type Job 

type Job struct {
	ID   types.JobID
	Name string
	// a freeform list of strings that the user can provide to tag a job, and
	// subsequently use to search and aggregate.
	Tags []string

	// How many times a job has to run. 0 means infinite.
	// A "run" is the execution of a sequence of tests. For example, setting
	// Runs to 2 will execute all the tests defined in `Tests` once, and then
	// will execute them again.
	Runs uint

	// RunInterval is the interval between multiple runs, if more than one, or
	// unlimited, are specified.
	RunInterval time.Duration

	// TargetManagerAcquireTimeout represents the maximum time that JobManager should wait for the execution of the Acquire function from the chosen TargetManager.
	TargetManagerAcquireTimeout time.Duration

	// TargetManagerReleaseTimeout represents the maximum time that JobManager should wait for the execution of the Release function from the chosen TargetManager.
	TargetManagerReleaseTimeout time.Duration

	// ExtendedDescriptor represents the descriptor submitted by the client that
	// resulted in the creation of this ConTest job.
	ExtendedDescriptor *ExtendedDescriptor

	// Tests represents the instantiated description of the tests
	Tests []*test.Test

	// RunReporterBundles and FinalReporterBundles wrap the reporter instances
	// chosen for the Job and its associated parameters, which have already
	// gone through validation
	RunReporterBundles   []*ReporterBundle
	FinalReporterBundles []*ReporterBundle
}

Job is used to run a type of test job on a given set of targets.

type JobReport 

type JobReport struct {
	JobID types.JobID
	// JobReport represents the report generated by the plugin selected in the job descriptor
	RunReports   [][]*Report
	FinalReports []*Report
}

JobReport represents the whole job report generated by ConTest.

type PauseEventPayload 

type PauseEventPayload struct {
	Version         int         `json:"V"`
	JobID           types.JobID `json:"J"`
	RunID           types.RunID `json:"R"`
	TestID          int         `json:"T,omitempty"`
	TestAttempt     uint32      `json:"TA"`
	NextTestAttempt *time.Time  `json:"NTA,omitempty"`
	// If we are sleeping before the run, this will specify when the run should begin.
	StartAt *time.Time `json:"S,omitempty"`
	// Otherwise, if test execution is in progress targets and runner state will be populated.
	Targets         []*target.Target `json:"TT,omitempty"`
	TestRunnerState json.RawMessage  `json:"TRS,omitempty"`
}

PauseEventPayload is the payload of the JobStatePaused event. It is persisted in the database and used to resume jobs.

func (*PauseEventPayload) String 

func (pp *PauseEventPayload) String() string

type Report 

type Report struct {
	JobID        types.JobID
	RunID        types.RunID `json:"RunID,omitempty"` // 0 for a final report
	ReporterName string
	ReportTime   time.Time
	Success      bool
	Data         interface{}
}

Report wraps the information of a run report or a final report.

func (*Report) ToJSON 

func (r *Report) ToJSON() ([]byte, error)

ToJSON marshals the report into JSON, disabling HTML escaping

type Reporter 

type Reporter interface {
	ValidateRunParameters([]byte) (interface{}, error)
	ValidateFinalParameters([]byte) (interface{}, error)

	Name() string

	RunReport(ctx xcontext.Context, parameters interface{}, runStatus *RunStatus, ev testevent.Fetcher) (bool, interface{}, error)
	FinalReport(ctx xcontext.Context, parameters interface{}, runStatuses []RunStatus, ev testevent.Fetcher) (bool, interface{}, error)
}

Reporter is an interface used to implement logic which calculates the result of a Job. The result is conveyed via a JobReport object.

type ReporterBundle 

type ReporterBundle struct {
	Reporter   Reporter
	Parameters interface{}
}

ReporterBundle bundles the selected Reporter together with its parameters based on the content of the job descriptor

type ReporterConfig 

type ReporterConfig struct {
	Name       string
	Parameters json.RawMessage
}

ReporterConfig is the configuration of a specific reporter, either a run reporter or a final reporter.

type ReporterFactory 

type ReporterFactory func() Reporter

ReporterFactory is a type representing a function which builds a Reporter object

type ReporterLoader 

type ReporterLoader func() (string, ReporterFactory)

ReporterLoader is a type representing a function which returns all the needed things to be able to load a Reporter object

type Reporting 

type Reporting struct {
	RunReporters   []ReporterConfig
	FinalReporters []ReporterConfig
}

Reporting is the configuration section that determines how to report the results. It is divided in run reporting and final reporting. The run reporters are called when each test run is completed, while the final reporters are called once at the end of the whole set of runs is completed. The final reporters are optional. If the job is continuous (e.g. run indefinitely), the final reporters are only called if the job is interrupted.

type Request 

type Request struct {
	JobID       types.JobID
	JobName     string
	Requestor   string
	ServerID    string
	RequestTime time.Time

	// JobDescriptor represents the raw descriptor as submitted by the user.
	JobDescriptor string

	// ExtendedDescriptor represents the deserialized job description extended
	// with with the full description of the test steps obtained from the test
	// fetcher. Since the descriptions of the test steps might not be inlined in
	// the descriptor itself, upon receiving a job request, job manager will fetch
	// the desciption and build extended descriptor accordingly. The extended
	// descriptor is then used upon requesting a resume without having a dependency
	// on the test fetcher.
	ExtendedDescriptor *ExtendedDescriptor
}

Request represents an incoming Job request which should be persisted in storage

type RunCoordinates 

type RunCoordinates struct {
	JobID types.JobID
	RunID types.RunID
}

RunCoordinates collects information to identify the run for which we want to rebuild the status

type RunStatus 

type RunStatus struct {
	RunCoordinates
	StartTime    time.Time
	TestStatuses []TestStatus
}

RunStatus bundles together all TestStatus for a specific run within the job

type State 

type State int
const (
	JobStateUnknown            State = iota
	JobStateStarted                  // 1
	JobStateCompleted                // 2
	JobStateFailed                   // 3
	JobStatePaused                   // 4
	JobStatePauseFailed              // 5
	JobStateCancelling               // 6
	JobStateCancelled                // 7
	JobStateCancellationFailed       // 8
)

func EventNameToJobState 

func EventNameToJobState(ev event.Name) (State, error)

func (State) String 

func (js State) String() string

type Status 

type Status struct {
	// Name is the name of the job.
	Name string

	// State represents the last recorded state of a job
	State string

	// StateErrMsg is an optional error message associated to the job state
	StateErrMsg string

	// StartTime indicates when the job started. A value of 0 indicates "not
	// started yet"
	StartTime time.Time

	// EndTime indicates when the job ended.
	EndTime *time.Time

	// RunStatus [deprecated since 28jun2021] is the status of the last run of the job, if it exists
	RunStatus *RunStatus

	// RunStatuses represents the status of all runs for a given job
	RunStatuses []RunStatus

	// Job report information
	JobReport *JobReport
}

Status contains information about a job's current status which is conveyed via the API when answering Status requests

type TargetStatus 

type TargetStatus struct {
	TestStepCoordinates
	Target  *target.Target
	InTime  time.Time
	OutTime time.Time
	Error   string
	// these are events that have an associated target. For events
	// that are not associated to a target, see TestStepStatus.Events .
	Events []testevent.Event
}

TargetStatus represents the status of a Target within a TestStep

type TestCoordinates 

type TestCoordinates struct {
	RunCoordinates
	TestName string
}

TestCoordinates collects information to identify the test for which we want to rebuild the status

type TestStatus 

type TestStatus struct {
	TestCoordinates
	TestStepStatuses []TestStepStatus
	TargetStatuses   []TargetStatus
}

TestStatus bundles together all TestStepStatus for a specific Test within the run

type TestStepCoordinates 

type TestStepCoordinates struct {
	TestCoordinates
	TestStepName  string
	TestStepLabel string
}

TestStepCoordinates collects information to identify the test step for which we want to rebuild the status

type TestStepStatus 

type TestStepStatus struct {
	TestStepCoordinates
	// these are events that have no target associated. For events
	// associated to a target, see TargetStatus.TargetEvents .
	Events         []testevent.Event
	TargetStatuses []TargetStatus
}

TestStepStatus bundles together all the TargetStatus for a specific TestStep (represented via its name and label)

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.