api

Documentation

Index

• func EnumerateOverridableFields(typ reflect.Type) (out []string)
• func ValidateInstances(sl validator.StructLevel)
• type Build
• type BuildInput
• type BuildOutput
• type Builder
• type CollectionInput
• type Composition
  • func (c Composition) PickGroups(indices ...int) (Composition, error)
  • func (c *Composition) ValidateForBuild() error
  • func (c *Composition) ValidateForRun() error
• type Dependencies
  • func (d Dependencies) AsMap() map[string]string
• type Dependency
• type Directories
• type Engine
• type Global
• type Group
  • func (g Group) CalculatedInstanceCount() uint
• type Instances
• type Metadata
• type Parameter
• type PlaceholderRunStrategy
• type Run
• type RunGroup
• type RunInput
• type RunOutput
• type Runner
• type TestCase
  • func (tc *TestCase) Describe(w io.Writer)
• type TestCaseInstances
• type TestCensus
• type TestPlanDefaults
• type TestPlanDefinition
  • func (tp *TestPlanDefinition) Describe(w io.Writer)
  • func (tp *TestPlanDefinition) TestCaseByName(name string) (seq int, tc *TestCase, ok bool)

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 {
	// Dependencies specifies any upstream dependency overrides to apply to this
	// build.
	Dependencies Dependencies `toml:"dependencies" json:"dependencies"`
}

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
	// 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, output io.Writer) (*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
}

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, io.Writer) ([]*BuildOutput, error)
	DoRun(context.Context, *Composition, io.Writer) (*RunOutput, error)
	DoCollectOutputs(ctx context.Context, runner string, runID string, w io.Writer) 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 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, outputWriter io.Writer) (*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, io.Writer) 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 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.