api

package
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: Apr 9, 2020 License: Apache-2.0, MIT Imports: 12 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// HealthcheckStatusOK indicates success in a healthcheck or a fix.
	HealthcheckStatusOK = HealthcheckStatus("ok")
	// HealthcheckStatusFailed indicates the outcome of a healthcheck or an
	// attempted fix was negative.
	HealthcheckStatusFailed = HealthcheckStatus("failed")
	// HealthcheckStatusAborted indicates an internal error during the execution
	// of a healthcheck or a fix.
	HealthcheckStatusAborted = HealthcheckStatus("aborted")
	// HealthcheckStatusOmitted indicates that a healthcheck or a fix was not
	// carried out due to previous errors.
	HealthcheckStatusOmitted = HealthcheckStatus("omitted")
	// HealthcheckStatusUnnecessary indicates that a check or fix was not
	// needed.
	HealthcheckStatusUnnecessary = HealthcheckStatus("unnecessary")
)

Functions

func EnumerateOverridableFields 

func EnumerateOverridableFields(typ reflect.Type) (out []string)

EnumerateOverridableFields returns the fields from a struct type that can be overridden, i.e. they bear the `overridable="yes"` tag, and they have an explicitly defined toml key.

TODO: can move this to an `enumerable` type that we embed in the configuration type itself, e.g.: 

v := GoBuildStrategy{}
v.EnumerateOverridableFields()

func ValidateInstances 

func ValidateInstances(sl validator.StructLevel)

ValidateInstances validates that either count or percentage is provided, but not both.

Types

type Build 

type Build struct {
	// Selectors specifies any source selection strings to be sent to the
	// builder. In the case of go builders, this field maps to build tags.
	Selectors []string

	// Dependencies specifies any upstream dependency overrides to apply to this
	// build.
	Dependencies Dependencies `toml:"dependencies" json:"dependencies"`
}

func (Build) BuildKey added in v0.4.0 

func (b Build) BuildKey() string

BuildKey returns a composite key that identifies this build, suitable for deduplication.

type BuildInput 

type BuildInput struct {
	// BuildID is a unique ID for this build.
	BuildID string
	// EnvConfig is the env configuration of the engine. Not a pointer to force
	// a copy.
	EnvConfig config.EnvConfig
	// Directories providers accessors to directories managed by the runtime.
	Directories Directories
	// TestPlan is the metadata of the test plan being built.
	TestPlan *TestPlanDefinition
	// Selectors specifies any source selection strings to be sent to the
	// builder. In the case of go builders, this field maps to build tags.
	Selectors []string
	// Dependencies are the versions of upstream dependencies we want to build
	// against. For a go build, this could be e.g.:
	//  github.com/ipfs/go-ipfs=v0.4.22
	//  github.com/libp2p/go-libp2p=v0.2.8
	Dependencies map[string]string
	// BuildConfig is the configuration of the build job sourced from the test
	// plan manifest, coalesced with any user-provided overrides.
	BuildConfig interface{}
}

BuildInput encapsulates the input options for building a test plan.

type BuildOutput 

type BuildOutput struct {
	// BuilderID is the ID of the builder used.
	BuilderID string
	// ArtifactPath can be the docker image ID, a file location, etc. of the
	// resulting artifact. It is builder-dependent.
	ArtifactPath string
	// Dependencies is a map of modules (as keys) to versions (as values),
	// containing the collapsed transitive upstream dependency set of this
	// build.
	Dependencies map[string]string
}

BuildOutput encapsulates the output from a build action.

type Builder 

type Builder interface {
	// ID returns the canonical identifier for this builder.
	ID() string

	// Build performs a build.
	Build(ctx context.Context, input *BuildInput, ow *rpc.OutputWriter) (*BuildOutput, error)

	// ConfigType returns the configuration type of this builder.
	ConfigType() reflect.Type
}

Builder is the interface to be implemented by all builders. A builder takes a test plan and builds it into executable form against a set of upstream dependencies, so it can be scheduled by a runner.

type CollectionInput 

type CollectionInput struct {
	// EnvConfig is the env configuration of the engine. Not a pointer to force
	// a copy.
	EnvConfig config.EnvConfig
	RunID     string
	RunnerID  string

	// RunnerConfig is the configuration of the runner sourced from the test
	// plan manifest, coalesced with any user-provided overrides.
	RunnerConfig interface{}
}

type Composition 

type Composition struct {
	// Metadata expresses optional metadata about this composition.
	Metadata Metadata `toml:"metadata" json:"metadata"`

	// Global defines the general parameters for this composition.
	Global Global `toml:"global" json:"global"`

	// Groups enumerates the instances groups that participate in this
	// composition.
	Groups []Group `toml:"groups" json:"groups" validate:"unique=ID"`
}

func (Composition) PickGroups 

func (c Composition) PickGroups(indices ...int) (Composition, error)

PickGroups clones this composition, retaining only the specified groups.

func (*Composition) ValidateForBuild 

func (c *Composition) ValidateForBuild() error

ValidateForBuild validates that this Composition is correct for a build.

func (*Composition) ValidateForRun 

func (c *Composition) ValidateForRun() error

ValidateForRun validates that this Composition is correct for a run.

type Dependencies 

type Dependencies []Dependency

func (Dependencies) AsMap 

func (d Dependencies) AsMap() map[string]string

type Dependency 

type Dependency struct {
	// Module is the module name/path for the import to be overridden.
	Module string `toml:"module" json:"module" validate:"required"`

	// Version is the override version.
	Version string `toml:"version" json:"version" validate:"required"`
}

type Directories 

type Directories interface {
	SourceDir() string
	WorkDir() string
}

Directories providers accessors to directories managed by the testground runtime (engine).

type Engine 

type Engine interface {
	TestCensus() TestCensus

	BuilderByName(name string) (Builder, bool)
	RunnerByName(name string) (Runner, bool)

	ListBuilders() map[string]Builder
	ListRunners() map[string]Runner

	DoBuild(context.Context, *Composition, *rpc.OutputWriter) ([]*BuildOutput, error)
	DoRun(context.Context, *Composition, *rpc.OutputWriter) (*RunOutput, error)
	DoCollectOutputs(ctx context.Context, runner string, runID string, ow *rpc.OutputWriter) error
	DoTerminate(ctx context.Context, runner string, ow *rpc.OutputWriter) error
	DoHealthcheck(ctx context.Context, runner string, fix bool, ow *rpc.OutputWriter) (*HealthcheckReport, error)

	EnvConfig() config.EnvConfig
	Context() context.Context
}

type Global 

type Global struct {
	// Plan is the test plan we want to run.
	Plan string `toml:"plan" json:"plan" validate:"required"`

	// Case is the test case we want to run.
	Case string `toml:"case" json:"case" validate:"required"`

	// TotalInstances defines the total number of instances that participate in
	// this composition; it is the sum of all instances in all groups.
	TotalInstances uint `toml:"total_instances" json:"total_instances" validate:"required,gte=0"`

	// Builder is the builder we're using.
	Builder string `toml:"builder" json:"builder" validate:"required"`

	// BuildConfig specifies the build configuration for this run.
	BuildConfig map[string]interface{} `toml:"build_config" json:"build_config"`

	// Runner is the runner we're using.
	Runner string `toml:"runner" json:"runner" validate:"required"`

	// RunConfig specifies the run configuration for this run.
	RunConfig map[string]interface{} `toml:"run_config" json:"run_config"`
}

type Group 

type Group struct {
	// ID is the unique ID of this group.
	ID string `toml:"id" json:"id"`

	// Instances defines the number of instances that belong to this group.
	Instances Instances `toml:"instances" json:"instances"`

	// Build specifies the build configuration for this group.
	Build Build `toml:"build" json:"build"`

	// Run specifies the run configuration for this group.
	Run Run `toml:"run" json:"run"`
	// contains filtered or unexported fields
}

func (Group) CalculatedInstanceCount 

func (g Group) CalculatedInstanceCount() uint

CalculatedInstanceCount returns the actual number of instances in this group.

Validate MUST be called for this field to be available.

type HealthcheckItem added in v0.2.0 

type HealthcheckItem struct {
	// Name is a short name describing this item.
	Name string
	// Status is the status of this check/fix.
	Status HealthcheckStatus
	// Message optionally contains any human-readable messages to be presented
	// to the user.
	Message string
}

HealthcheckItem represents an entry in a HealthcheckReport. It is used to convey the result of checks and fixes.

type HealthcheckReport added in v0.2.0 

type HealthcheckReport struct {
	// Checks enumerates the outcomes of the health checks.
	Checks []HealthcheckItem

	// Fixes enumerates the outcomes of the fixes applied during fix, if a
	// fix was requested.
	Fixes []HealthcheckItem
}

func (*HealthcheckReport) ChecksSucceeded added in v0.2.0 

func (hr *HealthcheckReport) ChecksSucceeded() bool

func (*HealthcheckReport) FixesSucceeded added in v0.2.0 

func (hr *HealthcheckReport) FixesSucceeded() bool

func (*HealthcheckReport) String added in v0.2.0 

func (hr *HealthcheckReport) String() string

type HealthcheckStatus added in v0.2.0 

type HealthcheckStatus string

HealthcheckStatus is an enum that represents

type Healthchecker added in v0.2.0 

type Healthchecker interface {
	Healthcheck(ctx context.Context, engine Engine, ow *rpc.OutputWriter, fix bool) (*HealthcheckReport, error)
}

Healthchecker is the interface to be implemented by a runner or builder that supports healthchecks and fixes.

type Instances 

type Instances struct {
	// Count specifies the exact number of instances that belong to a group.
	//
	// Specifying a count is mutually exclusive with specifying a percentage.
	Count uint `toml:"count" json:"count"`

	// Percentage indicates the number of instances belonging to a group as a
	// proportion of the total instance count.
	//
	// Specifying a percentage is mutually exclusive with specifying a count.
	Percentage float64 `toml:"percentage" json:"percentage"`
}

type Metadata 

type Metadata struct {
	// Name is the name of this composition.
	Name string `toml:"name" json:"name"`

	// Author is the author of this composition.
	Author string `toml:"author" json:"author"`
}

type Parameter 

type Parameter struct {
	Type        string
	Description string `toml:"desc"`
	Unit        string
	Default     interface{}
}

Parameter is metadata about a test case parameter..

type PlaceholderRunStrategy 

type PlaceholderRunStrategy struct {
	Enabled bool
}

type Run 

type Run struct {
	// Artifact specifies the build artifact to use for this run.
	Artifact string `toml:"artifact" json:"artifact"`

	// TestParams specify the test parameters to pass down to instances of this
	// group.
	TestParams map[string]string `toml:"test_params" json:"test_params"`
}

type RunGroup 

type RunGroup struct {
	// ID is the id of the instance group this run pertains to.
	ID string

	// Instances is the number of instances to run with this configuration.
	Instances int

	// ArtifactPath can be a docker image ID or an executable path; it's
	// runner-dependent.
	ArtifactPath string

	// Parameters are the runtime parameters to the test case.
	Parameters map[string]string
}

type RunInput 

type RunInput struct {
	// RunID is the run id assigned to this job by the Engine.
	RunID string

	// EnvConfig is the env configuration of the engine. Not a pointer to force
	// a copy.
	EnvConfig config.EnvConfig

	// RunnerConfig is the configuration of the runner sourced from the test
	// plan manifest, coalesced with any user-provided overrides.
	RunnerConfig interface{}

	// Directories providers accessors to directories managed by the runtime.
	Directories Directories

	// TestPlan is the definition of the test plan containing the test case to
	// run.
	TestPlan *TestPlanDefinition

	// Seq is the test case seq number to run.
	Seq int

	// TotalInstances is the total number of instances participating in this test case.
	TotalInstances int

	// Groups enumerates the groups participating in this run.
	Groups []RunGroup
}

RunInput encapsulates the input options for running a test plan.

type RunOutput 

type RunOutput struct {
	// RunnerID is the ID of the runner used.
	RunID string
}

type Runner 

type Runner interface {
	// ID returns the canonical identifier for this runner.
	ID() string

	// Run runs a test case.
	Run(ctx context.Context, job *RunInput, ow *rpc.OutputWriter) (*RunOutput, error)

	// ConfigType returns the configuration type of this runner.
	ConfigType() reflect.Type

	// CompatibleBuilders returns the IDs of the builders whose artifacts this
	// runner can work with.
	CompatibleBuilders() []string

	// CollectOutputs gathers the outputs from a run, and produces a zip file
	// with the contents, writing it to the specified io.Writer.
	CollectOutputs(context.Context, *CollectionInput, *rpc.OutputWriter) error
}

Runner is the interface to be implemented by all runners. A runner takes a test plan in executable form and schedules a run of a particular test case within it.

TODO cardinality: do we want to be able to run multiple test cases within a test plan in a single call?

type Terminatable added in v0.2.0 

type Terminatable interface {
	TerminateAll(context.Context, *rpc.OutputWriter) error
}

Terminatable is the interface to be implemented by a runner that can be terminated.

type TestCase 

type TestCase struct {
	Name      string
	Instances TestCaseInstances
	// Parameters are parameters passed to this test case at runtime.
	Parameters map[string]Parameter `toml:"params"`
	// Roles are roles that instances of this test case can assume.
	Roles []string
}

TestCase represents a configuration for a test case known by the system.

func (*TestCase) Describe 

func (tc *TestCase) Describe(w io.Writer)

type TestCaseInstances 

type TestCaseInstances struct {
	Minimum int `toml:"min"`
	Maximum int `toml:"max"`
	Default int `toml:"default"`
}

TestCaseInstances expresses how many instances this test case can run.

type TestCensus 

type TestCensus interface {
	EnrollTestPlan(tp *TestPlanDefinition) error
	PlanByName(name string) *TestPlanDefinition
	ListPlans() (tp []*TestPlanDefinition)
}

type TestPlanDefaults 

type TestPlanDefaults struct {
	Builder string
	Runner  string
}

TestPlanDefaults represents the builder and runner defaults for a certain test case.

type TestPlanDefinition 

type TestPlanDefinition struct {
	Name            string
	SourcePath      string                      `toml:"source_path"`
	BuildStrategies map[string]config.ConfigMap `toml:"build_strategies"`
	RunStrategies   map[string]config.ConfigMap `toml:"run_strategies"`
	TestCases       []*TestCase                 `toml:"testcases"`
	Defaults        TestPlanDefaults
}

TestPlanDefinition represents a test plan known by the system. Its name must be unique within a test census.

func (*TestPlanDefinition) Describe 

func (tp *TestPlanDefinition) Describe(w io.Writer)

func (*TestPlanDefinition) TestCaseByName 

func (tp *TestPlanDefinition) TestCaseByName(name string) (seq int, tc *TestCase, ok bool)

TestCaseByName returns a test case by name.

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.