execution

Documentation

Overview

Package execution contains most of the components that schedule, execute and control individual k6 tests.

Index

• func AbortTestRun(ctx context.Context, err error) bool
• func GetCancelReasonIfTestAborted(ctx context.Context) error
• func NewTestRunContext(ctx context.Context, logger logrus.FieldLogger) (newCtx context.Context, abortTest func(reason error))
• func SignalAndWait(c Controller, eventID string) error
• func SignalErrorOrWait(c Controller, eventID string, err error) error
• type Controller
• type Scheduler
  • func NewScheduler(trs *lib.TestRunState, controller Controller) (*Scheduler, error)
  • func (e *Scheduler) GetExecutionPlan() []lib.ExecutionStep
  • func (e *Scheduler) GetExecutorConfigs() []lib.ExecutorConfig
  • func (e *Scheduler) GetExecutors() []lib.Executor
  • func (e *Scheduler) GetInitProgressBar() *pb.ProgressBar
  • func (e *Scheduler) GetState() *lib.ExecutionState
  • func (e *Scheduler) Init(runCtx context.Context, samplesOut chan<- metrics.SampleContainer) (stopVUEmission func(), initErr error)
  • func (e *Scheduler) Run(globalCtx, runCtx context.Context, samplesOut chan<- metrics.SampleContainer) (runErr error)
  • func (e *Scheduler) SetPaused(pause bool) error

Functions

func AbortTestRun

func AbortTestRun(ctx context.Context, err error) bool

AbortTestRun will cancel the test run context with the given reason if the provided context is actually a TestRuncontext or a child of one.

func GetCancelReasonIfTestAborted

func GetCancelReasonIfTestAborted(ctx context.Context) error

GetCancelReasonIfTestAborted returns a reason the Context was cancelled, if it was aborted with these functions. It will return nil if ctx is not an TestRunContext (or its children) or if it was never aborted.

func NewTestRunContext

func NewTestRunContext(
	ctx context.Context, logger logrus.FieldLogger,
) (newCtx context.Context, abortTest func(reason error))

NewTestRunContext returns context.Context that can be aborted by calling the returned TestAbortFunc or by calling CancelTestRunContext() on the returned context or a sub-context of it. Use this to initialize the context that will be passed to the ExecutionScheduler, so `execution.test.abort()` and the REST API test stopping both work.

func SignalAndWait

func SignalAndWait(c Controller, eventID string) error

SignalAndWait implements a rendezvous point / barrier, a way for all instances to reach the same execution point and wait for each other, before they all ~simultaneously continue with the execution.

It subscribes for the given event ID, signals that the current instance has reached it without an error, and then waits until all other instances have reached it or until there is an error in one of them.

func SignalErrorOrWait

func SignalErrorOrWait(c Controller, eventID string, err error) error

SignalErrorOrWait is a helper method that either immediately signals the given error and returns it, or it signals nominal completion and waits for all other instances to do the same (or signal an error themselves).

Types

type Controller

type Controller interface {
	// GetOrCreateData requests the data chunk with the given ID, if it already
	// exists. If it doesn't (i.e. this was the first time this function was
	// called with that ID), the given callback is called and its result and
	// error are saved for the ID and returned for all other calls with it.
	//
	// This is an atomic and single-flight function, so any calls to it while the callback is
	// being executed the same ID will wait for the first call to finish
	// and receive its result.
	//
	// TODO: split apart into `Once()`, `SetData(), `GetData()` and implement
	// the GetOrCreateData() behavior in a helper like the ones below?
	GetOrCreateData(ID string, callback func() ([]byte, error)) ([]byte, error)

	// Signal is used to notify that the current instance has reached the given
	// event ID, or that it has had an error.
	Signal(eventID string, err error) error

	// Subscribe creates a listener for the specified event ID and returns a
	// callback that can wait until all other instances have reached it.
	Subscribe(eventID string) (wait func() error)
}

Controller implementations are used to control the k6 execution of a test or test suite, either locally or in a distributed environment.

type Scheduler

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

A Scheduler is in charge of most of the test execution - initializing VUs and executors, running setup() and teardown(), and actually starting the executors for the different scenarios at the appropriate times.

func NewScheduler

func NewScheduler(trs *lib.TestRunState, controller Controller) (*Scheduler, error)

NewScheduler creates and returns a new Scheduler instance, without initializing it beyond the bare minimum. Specifically, it creates the needed executor instances and a lot of state placeholders, but it doesn't initialize the executors and it doesn't initialize or run VUs.

func (*Scheduler) GetExecutionPlan

func (e *Scheduler) GetExecutionPlan() []lib.ExecutionStep

GetExecutionPlan is a helper method so users of the local execution scheduler don't have to calculate the execution plan again.

func (*Scheduler) GetExecutorConfigs

func (e *Scheduler) GetExecutorConfigs() []lib.ExecutorConfig

GetExecutorConfigs returns the slice of all executor configs, sorted by their (startTime, name) in an ascending order.

func (*Scheduler) GetExecutors

func (e *Scheduler) GetExecutors() []lib.Executor

GetExecutors returns the slice of configured executor instances which have work, sorted by their (startTime, name) in an ascending order.

func (*Scheduler) GetInitProgressBar

func (e *Scheduler) GetInitProgressBar() *pb.ProgressBar

GetInitProgressBar returns the progress bar associated with the Init function. After the Init is done, it is "hijacked" to display real-time execution statistics as a text bar.

func (*Scheduler) GetState

func (e *Scheduler) GetState() *lib.ExecutionState

GetState returns a pointer to the execution state struct for the execution scheduler. It's guaranteed to be initialized and present, though see the documentation in lib/execution.go for caveats about its usage. The most important one is that none of the methods beyond the pause-related ones should be used for synchronization.

func (*Scheduler) Init

func (e *Scheduler) Init(
	runCtx context.Context, samplesOut chan<- metrics.SampleContainer,
) (stopVUEmission func(), initErr error)

Init concurrently initializes all of the planned VUs and then sequentially initializes all of the configured executors. It also starts the measurement and emission of the `vus` and `vus_max` metrics.

func (*Scheduler) Run

func (e *Scheduler) Run(globalCtx, runCtx context.Context, samplesOut chan<- metrics.SampleContainer) (runErr error)

Run the Scheduler, funneling all generated metric samples through the supplied out channel.

func (*Scheduler) SetPaused

func (e *Scheduler) SetPaused(pause bool) error

SetPaused pauses the test, or start/resumes it. To check if a test is paused, use GetState().IsPaused().

Currently, any executor, so any test, can be started in a paused state. This will cause k6 to initialize all needed VUs, but it won't actually start the test. Later, the test can be started for real by resuming/unpausing it from the REST API.

After a test is actually started, it may become impossible to pause it again. That is signaled by having SetPaused(true) return an error. The likely cause is that some of the executors for the test don't support pausing after the test has been started.

IMPORTANT: Currently only the externally controlled executor can be paused and resumed multiple times in the middle of the test execution! Even then, "pausing" is a bit misleading, since k6 won't pause in the middle of the currently executing iterations. It will allow the currently in-progress iterations to finish, and it just won't start any new ones nor will it increment the value returned by GetCurrentTestRunDuration().