lib

package
v0.33.0 Latest Latest
Warning

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

 Go to latest Published: Apr 29, 2021 License: AGPL-3.0 Imports: 39 Imported by: 0

Documentation

Overview

Package lib is a kitchen sink of... basically anything that doesn't belong in a specific part of the codebase, ranging from utility functions to universal types to core interfaces.

Some of the things in lib do not actually belong in lib, and need to be moved into either submodules, or separate modules like core. Other things are in files that are far too long, or that do not actually make sense.

Feel free to move these things.

Package lib contains most interfaces and base structs of k6.

Index

Constants

View Source 
const DefaultScenarioName = "default"

DefaultScenarioName is used as the default key/ID of the scenario config entries that were created due to the use of the shortcut execution control options (i.e. duration+vus, iterations+vus, or stages)

View Source 
const GroupSeparator = "::"

Separator for group IDs.

View Source 
const MaxRetriesGetPlannedVU = 5

MaxRetriesGetPlannedVU how many times we should wait for MaxTimeToWaitForPlannedVU before we actually return an error.

View Source 
const MaxTimeToWaitForPlannedVU = 400 * time.Millisecond

MaxTimeToWaitForPlannedVU specifies the maximum allowable time for an executor to wait for a planned VU to be retrieved from the ExecutionState.PlannedVUs buffer. If it's exceeded, k6 will emit a warning log message, since it either means that there's a bug in the k6 scheduling code, or that the machine is overloaded and the scheduling code suffers from delays.

Critically, exceeding this time *doesn't* result in an aborted test or any test errors, and the executor will continue to try and borrow the VU (potentially resulting in further warnings). We likely should emit a k6 metric about it in the future. TODO: emit a metric every time this is exceeded?

Variables

View Source 
var DefaultSummaryTrendStats = []string{"avg", "min", "med", "max", "p(90)", "p(95)"}

DefaultSummaryTrendStats are the default trend columns shown in the test summary output nolint: gochecknoglobals

View Source 
var ErrNameContainsGroupSeparator = errors.New("group and check names may not contain '::'")

Error emitted if you attempt to instantiate a Group or Check that contains the separator.

View Source 
var SupportedTLSCipherSuites = map[string]uint16{

	"TLS_RSA_WITH_RC4_128_SHA":                tls.TLS_RSA_WITH_RC4_128_SHA,
	"TLS_RSA_WITH_3DES_EDE_CBC_SHA":           tls.TLS_RSA_WITH_3DES_EDE_CBC_SHA,
	"TLS_RSA_WITH_AES_128_CBC_SHA":            tls.TLS_RSA_WITH_AES_128_CBC_SHA,
	"TLS_RSA_WITH_AES_256_CBC_SHA":            tls.TLS_RSA_WITH_AES_256_CBC_SHA,
	"TLS_RSA_WITH_AES_128_CBC_SHA256":         tls.TLS_RSA_WITH_AES_128_CBC_SHA256,
	"TLS_RSA_WITH_AES_128_GCM_SHA256":         tls.TLS_RSA_WITH_AES_128_GCM_SHA256,
	"TLS_RSA_WITH_AES_256_GCM_SHA384":         tls.TLS_RSA_WITH_AES_256_GCM_SHA384,
	"TLS_ECDHE_ECDSA_WITH_RC4_128_SHA":        tls.TLS_ECDHE_ECDSA_WITH_RC4_128_SHA,
	"TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA":    tls.TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,
	"TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA":    tls.TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,
	"TLS_ECDHE_RSA_WITH_RC4_128_SHA":          tls.TLS_ECDHE_RSA_WITH_RC4_128_SHA,
	"TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA":     tls.TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,
	"TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA":      tls.TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,
	"TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA":      tls.TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,
	"TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256":   tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
	"TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256": tls.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
	"TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384":   tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
	"TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384": tls.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
	"TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256": tls.TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,
	"TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305":    tls.TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,
	"TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305":  tls.TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,
	"TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256":   tls.TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,

	"TLS_AES_128_GCM_SHA256":       tls.TLS_AES_128_GCM_SHA256,
	"TLS_AES_256_GCM_SHA384":       tls.TLS_AES_256_GCM_SHA384,
	"TLS_CHACHA20_POLY1305_SHA256": tls.TLS_CHACHA20_POLY1305_SHA256,
}

SupportedTLSCipherSuites is string-to-constant map of available TLS cipher suites. nolint: gochecknoglobals

View Source 
var SupportedTLSCipherSuitesToString = map[uint16]string{
	tls.TLS_RSA_WITH_RC4_128_SHA:                "TLS_RSA_WITH_RC4_128_SHA",
	tls.TLS_RSA_WITH_3DES_EDE_CBC_SHA:           "TLS_RSA_WITH_3DES_EDE_CBC_SHA",
	tls.TLS_RSA_WITH_AES_128_CBC_SHA:            "TLS_RSA_WITH_AES_128_CBC_SHA",
	tls.TLS_RSA_WITH_AES_256_CBC_SHA:            "TLS_RSA_WITH_AES_256_CBC_SHA",
	tls.TLS_RSA_WITH_AES_128_CBC_SHA256:         "TLS_RSA_WITH_AES_128_CBC_SHA256",
	tls.TLS_RSA_WITH_AES_128_GCM_SHA256:         "TLS_RSA_WITH_AES_128_GCM_SHA256",
	tls.TLS_RSA_WITH_AES_256_GCM_SHA384:         "TLS_RSA_WITH_AES_256_GCM_SHA384",
	tls.TLS_ECDHE_ECDSA_WITH_RC4_128_SHA:        "TLS_ECDHE_ECDSA_WITH_RC4_128_SHA",
	tls.TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA:    "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA",
	tls.TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA:    "TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA",
	tls.TLS_ECDHE_RSA_WITH_RC4_128_SHA:          "TLS_ECDHE_RSA_WITH_RC4_128_SHA",
	tls.TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA:     "TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA",
	tls.TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA:      "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA",
	tls.TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA:      "TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA",
	tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256:   "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
	tls.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256: "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
	tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384:   "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
	tls.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384: "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384",
	tls.TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256: "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256",
	tls.TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305:    "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305",
	tls.TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305:  "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305",
	tls.TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256:   "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256",
	tls.TLS_AES_128_GCM_SHA256:                  "TLS_AES_128_GCM_SHA256",
	tls.TLS_AES_256_GCM_SHA384:                  "TLS_AES_256_GCM_SHA384",
	tls.TLS_CHACHA20_POLY1305_SHA256:            "TLS_CHACHA20_POLY1305_SHA256",
}

SupportedTLSCipherSuitesToString is constant-to-string map of available TLS cipher suites. nolint: gochecknoglobals

View Source 
var SupportedTLSVersions = map[string]TLSVersion{
	"tls1.0": tls.VersionTLS10,
	"tls1.1": tls.VersionTLS11,
	"tls1.2": tls.VersionTLS12,
	"tls1.3": tls.VersionTLS13,
}

SupportedTLSVersions is string-to-constant map of available TLS versions. nolint: gochecknoglobals

View Source 
var SupportedTLSVersionsToString = map[TLSVersion]string{
	tls.VersionTLS10: "tls1.0",
	tls.VersionTLS11: "tls1.1",
	tls.VersionTLS12: "tls1.2",
	tls.VersionTLS13: "tls1.3",
}

SupportedTLSVersionsToString is constant-to-string map of available TLS versions. nolint: gochecknoglobals

Functions

func Clampf added in v0.5.0 

func Clampf(val, min, max float64) float64

Clampf returns the given value, "clamped" to the range [min, max].

func ConcatErrors added in v0.27.0 

func ConcatErrors(errors []error, separator string) string

ConcatErrors is a a helper function for joining error messages into a single string.

TODO: use Go 2.0/xerrors style errors so we don't loose error type information and metadata.

func GetEndOffset added in v0.27.0 

func GetEndOffset(steps []ExecutionStep) (lastStepOffset time.Duration, isFinal bool)

GetEndOffset returns the time offset of the last step of the execution plan, and whether that step is a final one, i.e. whether the number of planned or unplanned is 0.

func GetMaxPlannedVUs added in v0.27.0 

func GetMaxPlannedVUs(steps []ExecutionStep) (result uint64)

GetMaxPlannedVUs returns the maximum number of planned VUs at any stage of the execution plan.

func GetMaxPossibleVUs added in v0.27.0 

func GetMaxPossibleVUs(steps []ExecutionStep) (result uint64)

GetMaxPossibleVUs returns the maximum number of planned + unplanned (i.e. initialized mid-test) VUs at any stage of the execution plan. Unplanned VUs are possible in some executors, like the arrival-rate ones, as a way to have a low number of pre-allocated VUs, but be able to initialize new ones in the middle of the test, if needed. For example, if the remote system starts responding very slowly and all of the pre-allocated VUs are waiting for it.

IMPORTANT 1: Getting planned and unplanned VUs separately for the whole duration of a test can often lead to mistakes. That's why this function is called GetMaxPossibleVUs() and why there is no GetMaxUnplannedVUs() function.

As an example, imagine that you have an executor with MaxPlannedVUs=20 and MaxUnplannedVUs=0, followed immediately after by another executor with MaxPlannedVUs=10 and MaxUnplannedVUs=10. The MaxPlannedVUs number for the whole test is 20, and MaxUnplannedVUs is 10, but since those executors won't run concurrently, MaxVUs for the whole test is not 30, rather it's 20, since 20 VUs will be sufficient to run the whole test.

IMPORTANT 2: this has one very important exception. The externally controlled executor doesn't use the MaxUnplannedVUs (i.e. this function will return 0), since their initialization and usage is directly controlled by the user and is effectively bounded only by the resources of the machine k6 is running on.

func Lerp 

func Lerp(x, y int64, t float64) int64

Lerp is a linear interpolation between two values x and y, returning the value at the point t, where t is a fraction in the range [0.0 - 1.0].

func Max added in v0.17.0 

func Max(a, b int64) int64

Returns the maximum value of a and b.

func Min added in v0.17.0 

func Min(a, b int64) int64

Returns the minimum value of a and b.

func NormalizeAndAnonymizePath added in v0.21.0 

func NormalizeAndAnonymizePath(path string) string

NormalizeAndAnonymizePath Normalizes (to use a / path separator) and anonymizes a file path, by scrubbing usernames from home directories.

func RegisterExecutorConfigType added in v0.27.0 

func RegisterExecutorConfigType(configType string, constructor ExecutorConfigConstructor)

RegisterExecutorConfigType adds the supplied ExecutorConfigConstructor as the constructor for its type in the configConstructors map, in a thread-safe manner

func SplitKV added in v0.8.2 

func SplitKV(s string) (key, value string)

Splits a string in the form "key=value".

func StrictJSONUnmarshal added in v0.27.0 

func StrictJSONUnmarshal(data []byte, v interface{}) error

StrictJSONUnmarshal decodes a JSON in a strict manner, emitting an error if there are unknown fields or unexpected data

func WithState added in v0.24.0 

func WithState(ctx context.Context, state *State) context.Context

Types

type ActiveVU added in v0.27.0 

type ActiveVU interface {
	// Run the configured exported function in the VU once. The only
	// way to interrupt the execution is to cancel the context given
	// to InitializedVU.Activate()
	RunOnce() error
}

ActiveVU represents an actively running virtual user.

type Archive added in v0.15.0 

type Archive struct {
	// The runner to use, eg. "js".
	Type string `json:"type"`

	// Options to use.
	Options Options `json:"options"`

	// TODO: rewrite the encoding, decoding of json to use another type with only the fields it
	// needs in order to remove Filename and Pwd from this
	// Filename and contents of the main file being executed.
	Filename    string   `json:"filename"` // only for json
	FilenameURL *url.URL `json:"-"`
	Data        []byte   `json:"-"`

	// Working directory for resolving relative paths.
	Pwd    string   `json:"pwd"` // only for json
	PwdURL *url.URL `json:"-"`

	Filesystems map[string]afero.Fs `json:"-"`

	// Environment variables
	Env map[string]string `json:"env"`

	CompatibilityMode string `json:"compatibilityMode"`

	K6Version string `json:"k6version"`
	Goos      string `json:"goos"`
}

An Archive is a rollup of all resources and options needed to reproduce a test identically elsewhere.

func ReadArchive added in v0.15.0 

func ReadArchive(in io.Reader) (*Archive, error)

ReadArchive reads an archive created by Archive.Write from a reader.

func (*Archive) Write added in v0.15.0 

func (arc *Archive) Write(out io.Writer) error

Write serialises the archive to a writer.

The format should be treated as opaque; currently it is simply a TAR rollup, but this may change. If it does change, ReadArchive must be able to handle all previous formats as well as the current one.

type Check 

type Check struct {
	// Arbitrary name of the check.
	Name string `json:"name"`

	// A Check belongs to a Group, which may belong to other groups. The Path describes
	// the hierarchy of these groups, with the segments delimited by '::'.
	// As an example: a check "My Check" within a group "Inner" within a group "Outer"
	// would have a Path of "::Outer::Inner::My Check". The empty first item is the root group,
	// which is always named "".
	Group *Group `json:"-"`
	Path  string `json:"path"`

	// A check's ID is a hash of the Path. It is deterministic between different k6
	// instances of the same version, but should be treated as opaque - the hash function
	// or length may change.
	ID string `json:"id"`

	// Counters for how many times this check has passed and failed respectively.
	Passes int64 `json:"passes"`
	Fails  int64 `json:"fails"`
}

A Check stores a series of successful or failing tests against a value.

For more information, refer to the js/modules/k6.K6.Check() function.

func NewCheck 

func NewCheck(name string, group *Group) (*Check, error)

Creates a new check with the given name and parent group. The group may not be nil.

type Collector added in v0.8.3 

type Collector interface {
	// Init is called between the collector's creation and the call to Run().
	// You should do any lengthy setup here rather than in New.
	Init() error

	// Run is called in a goroutine and starts the collector. Should commit samples to the backend
	// at regular intervals and when the context is terminated.
	Run(ctx context.Context)

	// Collect receives a set of samples. This method is never called concurrently, and only while
	// the context for Run() is valid, but should defer as much work as possible to Run().
	Collect(samples []stats.SampleContainer)

	// Optionally return a link that is shown to the user.
	Link() string
}

A Collector abstracts the process of funneling samples to an external storage backend, such as an InfluxDB instance.

type CompatibilityMode added in v0.27.0 

type CompatibilityMode uint8

CompatibilityMode specifies the JS compatibility mode nolint:lll 

const (
	// CompatibilityModeExtended achieves ES6+ compatibility with Babel and core.js
	CompatibilityModeExtended CompatibilityMode = iota + 1
	// CompatibilityModeBase is standard goja ES5.1+
	CompatibilityModeBase
)

func CompatibilityModeString added in v0.27.0 

func CompatibilityModeString(s string) (CompatibilityMode, error)

CompatibilityModeString retrieves an enum value from the enum constants string name. Throws an error if the param is not part of the enum.

func CompatibilityModeValues added in v0.27.0 

func CompatibilityModeValues() []CompatibilityMode

CompatibilityModeValues returns all values of the enum

func ValidateCompatibilityMode added in v0.26.0 

func ValidateCompatibilityMode(val string) (cm CompatibilityMode, err error)

ValidateCompatibilityMode checks if the provided val is a valid compatibility mode

func (CompatibilityMode) IsACompatibilityMode added in v0.27.0 

func (i CompatibilityMode) IsACompatibilityMode() bool

IsACompatibilityMode returns "true" if the value is listed in the enum definition. "false" otherwise

func (CompatibilityMode) String added in v0.27.0 

func (i CompatibilityMode) String() string

type DialContexter added in v0.24.0 

type DialContexter interface {
	DialContext(ctx context.Context, network, addr string) (net.Conn, error)
}

DialContexter is an interface that can dial with a context

type ExecutionScheduler added in v0.27.0 

type ExecutionScheduler interface {
	// Returns the wrapped runner. May return nil if not applicable, eg.
	// if we're remote controlling a test running on another machine.
	GetRunner() Runner

	// Return the ExecutionState instance from which different statistics for the
	// current state of the runner could be retrieved.
	GetState() *ExecutionState

	// Return the instances of the configured executors
	GetExecutors() []Executor

	// Init initializes all executors, including all of their needed VUs.
	Init(ctx context.Context, samplesOut chan<- stats.SampleContainer) error

	// Run the ExecutionScheduler, funneling the generated metric samples
	// through the supplied out channel.
	Run(globalCtx, runCtx context.Context, samplesOut chan<- stats.SampleContainer) error

	// Pause a test, or start/resume 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 denoted 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().
	SetPaused(paused bool) error
}

An ExecutionScheduler is in charge of initializing executors and using them to initialize and schedule VUs created by a wrapped Runner. It decouples how a swarm of VUs is controlled from the details of how or even where they're scheduled.

The core/local execution scheduler schedules VUs on the local machine, but the same interface may be implemented to control a test running on a cluster or in the cloud.

TODO: flesh out the interface after actually having more than one implementation...

type ExecutionSegment added in v0.27.0 

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

ExecutionSegment represents a (start, end] partition of the total execution work for a specific test. For example, if we want the split the execution of a test in 2 different parts, we can split it in two segments (0, 0.5] and (0,5, 1].

We use rational numbers so it's easier to verify the correctness and easier to reason about portions of indivisible things, like VUs. This way, we can easily split a test in thirds (i.e. (0, 1/3], (1/3, 2/3], (2/3, 1]), without fearing that we'll lose a VU along the way...

The most important part is that if work is split between multiple k6 instances, each k6 instance can precisely and reproducibly calculate its share of the work, just by knowing its own segment. There won't be a need to schedule the execution from a master node, or to even know how many other k6 instances are running!

func NewExecutionSegment added in v0.27.0 

func NewExecutionSegment(from, to *big.Rat) (*ExecutionSegment, error)

NewExecutionSegment validates the supplied arguments (basically, that 0 <= from < to <= 1) and either returns an error, or it returns a fully-initialized and usable execution segment.

func NewExecutionSegmentFromString added in v0.27.0 

func NewExecutionSegmentFromString(toStr string) (result *ExecutionSegment, err error)

NewExecutionSegmentFromString validates the supplied string value and returns the newly created ExecutionSegment or and error from it.

We are able to parse both single percentage/float/fraction values, and actual (from: to] segments. For the single values, we just treat them as the beginning segment - thus the execution segment can be used as a shortcut for quickly running an arbitrarily scaled-down version of a test.

The parsing logic is that values with a colon, i.e. ':', are full segments: 

`1/2:3/4`, `0.5:0.75`, `50%:75%`, and even `2/4:75%` should be (1/2, 3/4]

And values without a colon are the end of a first segment: 

`20%`, `0.2`,  and `1/5` should be converted to (0, 1/5]

empty values should probably be treated as "1", i.e. the whole execution

func (*ExecutionSegment) CopyScaleRat added in v0.27.0 

func (es *ExecutionSegment) CopyScaleRat(value *big.Rat) *big.Rat

CopyScaleRat scales rational numbers without changing them - creates a new bit.Rat object and uses it for the calculation.

func (*ExecutionSegment) Equal added in v0.27.0 

func (es *ExecutionSegment) Equal(other *ExecutionSegment) bool

Equal returns true only if the two execution segments have the same from and to values.

func (*ExecutionSegment) FloatLength added in v0.27.0 

func (es *ExecutionSegment) FloatLength() float64

FloatLength is a helper method for getting some more human-readable information about the execution segment.

func (*ExecutionSegment) InPlaceScaleRat added in v0.27.0 

func (es *ExecutionSegment) InPlaceScaleRat(value *big.Rat) *big.Rat

InPlaceScaleRat scales rational numbers in-place - it changes the passed argument (and also returns it, to allow for chaining, like many other big.Rat methods).

func (*ExecutionSegment) MarshalText added in v0.27.0 

func (es *ExecutionSegment) MarshalText() ([]byte, error)

MarshalText implements the encoding.TextMarshaler interface, so is used for text and JSON encoding of the execution segment.

func (*ExecutionSegment) Scale added in v0.27.0 

func (es *ExecutionSegment) Scale(value int64) int64

Scale proportionally scales the supplied value, according to the execution segment's position and size of the work.

func (*ExecutionSegment) Split added in v0.27.0 

func (es *ExecutionSegment) Split(numParts int64) ([]*ExecutionSegment, error)

Split evenly divides the execution segment into the specified number of equal consecutive execution sub-segments.

func (*ExecutionSegment) String added in v0.27.0 

func (es *ExecutionSegment) String() string

func (*ExecutionSegment) SubSegment added in v0.27.0 

func (es *ExecutionSegment) SubSegment(child *ExecutionSegment) *ExecutionSegment

SubSegment returns a new execution sub-segment - if a is (1/2:1] and b is (0:1/2], then a.SubSegment(b) will return a new segment (1/2, 3/4].

The basic formula for c = a.SubSegment(b) is: 

c.from = a.from + b.from * (a.to - a.from)
c.to = c.from + (b.to - b.from) * (a.to - a.from)

func (*ExecutionSegment) UnmarshalText added in v0.27.0 

func (es *ExecutionSegment) UnmarshalText(text []byte) (err error)

UnmarshalText implements the encoding.TextUnmarshaler interface, so that execution segments can be specified as CLI flags, environment variables, and JSON strings. It is a wrapper for the NewExecutionFromString() constructor.

type ExecutionSegmentSequence added in v0.27.0 

type ExecutionSegmentSequence []*ExecutionSegment

ExecutionSegmentSequence represents an ordered chain of execution segments, where the end of one segment is the beginning of the next. It can serialized as a comma-separated string of rational numbers "r1,r2,r3,...,rn", which represents the sequence (r1, r2], (r2, r3], (r3, r4], ..., (r{n-1}, rn]. The empty value should be treated as if there is a single (0, 1] segment.

func GetFilledExecutionSegmentSequence added in v0.27.0 

func GetFilledExecutionSegmentSequence(
	sequence *ExecutionSegmentSequence, fallback *ExecutionSegment,
) (result ExecutionSegmentSequence)

GetFilledExecutionSegmentSequence makes sure we don't have any gaps in the given execution segment sequence, or a nil one. It makes sure that the whole 0-1 range is filled.

func NewExecutionSegmentSequence added in v0.27.0 

func NewExecutionSegmentSequence(segments ...*ExecutionSegment) (ExecutionSegmentSequence, error)

NewExecutionSegmentSequence validates the that the supplied execution segments are non-overlapping and without gaps. It will return a new execution segment sequence if that is true, and an error if it's not.

func NewExecutionSegmentSequenceFromString added in v0.27.0 

func NewExecutionSegmentSequenceFromString(strSeq string) (ExecutionSegmentSequence, error)

NewExecutionSegmentSequenceFromString parses strings of the format "r1,r2,r3,...,rn", which represents the sequences like (r1, r2], (r2, r3], (r3, r4], ..., (r{n-1}, rn].

func (ExecutionSegmentSequence) FindSegmentPosition added in v0.27.0 

func (ess ExecutionSegmentSequence) FindSegmentPosition(segment *ExecutionSegment) (int, error)

FindSegmentPosition returns the index of the supplied execution segment in the sequence, or an error if the segment isn't present. This shouldn't be used on a nil or empty sequence, it's best to use this method on the result of GetFilledExecutionSegmentSequence().

func (ExecutionSegmentSequence) IsFull added in v0.27.0 

func (ess ExecutionSegmentSequence) IsFull() bool

IsFull returns whether the sequences is full, that is, whether it starts at 0 and ends at 1. Use GetFilledExecutionSegmentSequence() to get a full sequence.

func (ExecutionSegmentSequence) LCD added in v0.27.0 

func (ess ExecutionSegmentSequence) LCD() int64

LCD calculates the lowest common denominator of the sequence. https://en.wikipedia.org/wiki/Least_common_multiple#Using_the_greatest_common_divisor

func (ExecutionSegmentSequence) MarshalText added in v0.27.0 

func (ess ExecutionSegmentSequence) MarshalText() ([]byte, error)

MarshalText implements the encoding.TextMarshaler interface, so is used for text and JSON encoding of the execution segment sequences.

func (ExecutionSegmentSequence) String added in v0.27.0 

func (ess ExecutionSegmentSequence) String() string

String just implements the fmt.Stringer interface, encoding the sequence of segments as "start1,end1,end2,end3,...,endn".

func (*ExecutionSegmentSequence) UnmarshalText added in v0.27.0 

func (ess *ExecutionSegmentSequence) UnmarshalText(text []byte) (err error)

UnmarshalText implements the encoding.TextUnmarshaler interface, so that execution segment sequences can be specified as CLI flags, environment variables, and JSON strings.

type ExecutionSegmentSequenceWrapper added in v0.27.0 

type ExecutionSegmentSequenceWrapper struct {
	ExecutionSegmentSequence // a filled-out segment sequence
	// contains filtered or unexported fields
}

ExecutionSegmentSequenceWrapper is a caching layer on top of the execution segment sequence that allows us to make fast and useful calculations, after a somewhat slow initialization.

func NewExecutionSegmentSequenceWrapper added in v0.27.0 

func NewExecutionSegmentSequenceWrapper(ess ExecutionSegmentSequence) *ExecutionSegmentSequenceWrapper

NewExecutionSegmentSequenceWrapper expects a filled-out execution segment sequence. It pre-calculates the initial caches of and returns a new ExecutionSegmentSequenceWrapper, but doesn't calculate the striped offsets.

func (*ExecutionSegmentSequenceWrapper) GetNewExecutionSegmentSequenceFromValue added in v0.27.0 

func (essw *ExecutionSegmentSequenceWrapper) GetNewExecutionSegmentSequenceFromValue(value int64, trackedIndex int) (
	newSequence *ExecutionSegmentSequenceWrapper, newIndex int, err error,
)

GetNewExecutionSegmentSequenceFromValue uses the value provided, splits it between all the segments, using the striping offsets in the sequence, generating a new segment sequence. It then returns a new ExecutionSegmentSequenceWrapper, with the new sequence and segments, such that each new segment in the new sequence has length `Scale(value)/value` while keeping the order.

Additionally, the position of a given segment index can be tracked (since empty segments are removed), so that you can reconstruct an ExecutionTuple, if required. If the segment with the trackedIndex is not part of the new sequence, or if a new sequence cannot be generated (for example, for 0 values), an error will be returned.

func (*ExecutionSegmentSequenceWrapper) GetStripedOffsets added in v0.27.0 

func (essw *ExecutionSegmentSequenceWrapper) GetStripedOffsets(segmentIndex int) (int64, []int64, int64)

GetStripedOffsets returns the stripped offsets for the given segment the returned values are as follows in order:

  • start: the first value that is for the segment
  • offsets: a list of offsets from the previous value for the segment. This are only the offsets to from the start to the next start if we chunk the elements we are going to strip into lcd sized chunks
  • lcd: the LCD of the lengths of all segments in the sequence. This is also the number of elements after which the algorithm starts to loop and give the same values

func (*ExecutionSegmentSequenceWrapper) GetTuple added in v0.27.0 

func (essw *ExecutionSegmentSequenceWrapper) GetTuple(segmentIndex int) *ExecutionTuple

GetTuple returns an ExecutionTuple for the specified segment index.

func (*ExecutionSegmentSequenceWrapper) LCD added in v0.27.0 

func (essw *ExecutionSegmentSequenceWrapper) LCD() int64

LCD returns the (cached) least common denominator of the sequence - no need to calculate it again, since we did it in the constructor.

func (*ExecutionSegmentSequenceWrapper) ScaleInt64 added in v0.27.0 

func (essw *ExecutionSegmentSequenceWrapper) ScaleInt64(segmentIndex int, value int64) int64

ScaleInt64 scales the provided value for the given segment.

type ExecutionState added in v0.27.0 

type ExecutionState struct {
	// A copy of the options, so the different executors have access to them.
	// They will need to access things like the current execution segment, the
	// per-run metrics tags, etc.
	//
	// Obviously, they are not meant to be changed... They should be a constant
	// during the execution of a single test, but we can't easily enforce that
	// via the Go type system...
	Options Options

	ExecutionTuple *ExecutionTuple // TODO Rename, possibly move
	// contains filtered or unexported fields
}

ExecutionState contains a few different things:

  • Some convenience items, that are needed by all executors, like the execution segment and the unique VU ID generator. By keeping those here, we can just pass the ExecutionState to the different executors, instead of individually passing them each item.
  • Mutable counters that different executors modify and other parts of k6 can read, e.g. for the vus and vus_max metrics k6 emits every second.
  • Pausing controls and statistics.

The counters and timestamps here are primarily meant to be used for information extraction and avoidance of ID collisions. Using many of the counters here for synchronization between VUs could result in HIDDEN data races, because the Go data race detector can't detect any data races involving atomics...

The only functionality intended for synchronization is the one revolving around pausing, and uninitializedUnplannedVUs for restricting the number of unplanned VUs being initialized.

func NewExecutionState added in v0.27.0 

func NewExecutionState(options Options, et *ExecutionTuple, maxPlannedVUs, maxPossibleVUs uint64) *ExecutionState

NewExecutionState initializes all of the pointers in the ExecutionState with zeros. It also makes sure that the initial state is unpaused, by setting resumeNotify to an already closed channel.

func (*ExecutionState) AddFullIterations added in v0.27.0 

func (es *ExecutionState) AddFullIterations(count uint64) uint64

AddFullIterations increments the number of full (i.e uninterrupted) iterations by the provided amount.

IMPORTANT: for UI/information purposes only, don't use for synchronization.

func (*ExecutionState) AddInitializedVU added in v0.27.0 

func (es *ExecutionState) AddInitializedVU(vu InitializedVU)

AddInitializedVU is a helper function that adds VUs into the buffer and increases the initialized VUs counter.

func (*ExecutionState) AddInterruptedIterations added in v0.27.0 

func (es *ExecutionState) AddInterruptedIterations(count uint64) uint64

AddInterruptedIterations increments the number of partial (i.e interrupted) iterations by the provided amount.

IMPORTANT: for UI/information purposes only, don't use for synchronization.

func (*ExecutionState) GetCurrentExecutionStatus added in v0.27.0 

func (es *ExecutionState) GetCurrentExecutionStatus() ExecutionStatus

GetCurrentExecutionStatus returns the current execution status. Don't use this for synchronization unless you've made the k6 behavior somewhat predictable with options like --paused or --linger.

func (*ExecutionState) GetCurrentTestRunDuration added in v0.27.0 

func (es *ExecutionState) GetCurrentTestRunDuration() time.Duration

GetCurrentTestRunDuration returns the duration for which the test has already ran. If the test hasn't started yet, that's 0. If it has started, but has been paused midway through, it will return the time up until the pause time. And if it's currently running, it will return the time since the start time.

IMPORTANT: for UI/information purposes only, don't use for synchronization.

func (*ExecutionState) GetCurrentlyActiveVUsCount added in v0.27.0 

func (es *ExecutionState) GetCurrentlyActiveVUsCount() int64

GetCurrentlyActiveVUsCount returns the number of VUs that are currently executing the test script. This also includes any VUs that are in the process of gracefully winding down.

IMPORTANT: for UI/information purposes only, don't use for synchronization.

func (*ExecutionState) GetFullIterationCount added in v0.27.0 

func (es *ExecutionState) GetFullIterationCount() uint64

GetFullIterationCount returns the total of full (i.e uninterrupted) iterations that have been completed so far.

IMPORTANT: for UI/information purposes only, don't use for synchronization.

func (*ExecutionState) GetInitializedVUsCount added in v0.27.0 

func (es *ExecutionState) GetInitializedVUsCount() int64

GetInitializedVUsCount returns the total number of currently initialized VUs.

Important: this doesn't include any temporary/service VUs that are destroyed after they are used. These are created for the initial retrieval of the exported script options and for the execution of setup() and teardown()

IMPORTANT: for UI/information purposes only, don't use for synchronization.

func (*ExecutionState) GetPartialIterationCount added in v0.27.0 

func (es *ExecutionState) GetPartialIterationCount() uint64

GetPartialIterationCount returns the total of partial (i.e interrupted) iterations that have been completed so far.

IMPORTANT: for UI/information purposes only, don't use for synchronization.

func (*ExecutionState) GetPlannedVU added in v0.27.0 

func (es *ExecutionState) GetPlannedVU(logger *logrus.Entry, modifyActiveVUCount bool) (InitializedVU, error)

GetPlannedVU tries to get a pre-initialized VU from the buffer channel. This shouldn't fail and should generally be an instantaneous action, but if it doesn't happen for MaxTimeToWaitForPlannedVU (for example, because the system is overloaded), a warning will be printed. If we reach that timeout more than MaxRetriesGetPlannedVU number of times, this function will return an error, since we either have a bug with some executor, or the machine is very, very overloaded.

If modifyActiveVUCount is true, the method would also increment the counter for active VUs. In most cases, that's the desired behavior, but some executors might have to retrieve their reserved VUs without using them immediately - for example, the externally-controlled executor when the configured maxVUs number is greater than the configured starting VUs.

func (*ExecutionState) GetUniqueVUIdentifier added in v0.27.0 

func (es *ExecutionState) GetUniqueVUIdentifier() uint64

GetUniqueVUIdentifier returns an auto-incrementing unique VU ID, used for __VU. It starts from 1 (for backwards compatibility...)

func (*ExecutionState) GetUnplannedVU added in v0.27.0 

func (es *ExecutionState) GetUnplannedVU(ctx context.Context, logger *logrus.Entry) (InitializedVU, error)

GetUnplannedVU checks if any unplanned VUs remain to be initialized, and if they do, it initializes one and returns it. If all unplanned VUs have already been initialized, it returns one from the global vus buffer, but doesn't automatically increment the active VUs counter in either case.

IMPORTANT: GetUnplannedVU() doesn't do any checking if the requesting executor is actually allowed to have the VU at this particular time. Executors are trusted to correctly declare their needs (via their GetExecutionRequirements() methods) and then to never ask for more VUs than they have specified in those requirements.

func (*ExecutionState) HasEnded added in v0.27.0 

func (es *ExecutionState) HasEnded() bool

HasEnded returns true if the test has finished executing. It will return false until MarkEnded() is called.

func (*ExecutionState) HasStarted added in v0.27.0 

func (es *ExecutionState) HasStarted() bool

HasStarted returns true if the test has actually started executing. It will return false while a test is in the init phase, or if it has been initially paused. But if will return true if a test is paused midway through its execution (see above for details regarding the feasibility of that pausing for normal executors).

func (*ExecutionState) InitializeNewVU added in v0.27.0 

func (es *ExecutionState) InitializeNewVU(ctx context.Context, logger *logrus.Entry) (InitializedVU, error)

InitializeNewVU creates and returns a brand new VU, updating the relevant tracking counters.

func (*ExecutionState) IsPaused added in v0.27.0 

func (es *ExecutionState) IsPaused() bool

IsPaused quickly returns whether the test is currently paused, by reading the atomic currentPauseTime timestamp

func (*ExecutionState) MarkEnded added in v0.27.0 

func (es *ExecutionState) MarkEnded()

MarkEnded saves the current timestamp as the test end time.

CAUTION: Calling MarkEnded() a second time for the same execution state will result in a panic!

func (*ExecutionState) MarkStarted added in v0.27.0 

func (es *ExecutionState) MarkStarted()

MarkStarted saves the current timestamp as the test start time.

CAUTION: Calling MarkStarted() a second time for the same execution state will result in a panic!

func (*ExecutionState) ModCurrentlyActiveVUsCount added in v0.27.0 

func (es *ExecutionState) ModCurrentlyActiveVUsCount(mod int64) int64

ModCurrentlyActiveVUsCount changes the total number of currently active VUs.

IMPORTANT: for UI/information purposes only, don't use for synchronization.

func (*ExecutionState) ModInitializedVUsCount added in v0.27.0 

func (es *ExecutionState) ModInitializedVUsCount(mod int64) int64

ModInitializedVUsCount changes the total number of currently initialized VUs.

IMPORTANT: for UI/information purposes only, don't use for synchronization.

func (*ExecutionState) Pause added in v0.27.0 

func (es *ExecutionState) Pause() error

Pause pauses the current execution. It acquires the lock, writes the current timestamp in currentPauseTime, and makes a new channel for resumeNotify. Pause can return an error if the test was already paused.

func (*ExecutionState) Resume added in v0.27.0 

func (es *ExecutionState) Resume() error

Resume unpauses the test execution. Unless the test wasn't yet started, it calculates the duration between now and the old currentPauseTime and adds it to Resume will emit an error if the test wasn't paused.

func (*ExecutionState) ResumeNotify added in v0.27.0 

func (es *ExecutionState) ResumeNotify() <-chan struct{}

ResumeNotify returns a channel which will be closed (i.e. could be read from) as soon as the test execution is resumed.

Since tests would likely be paused only rarely, unless you directly need to be notified via a channel that the test isn't paused or that it has resumed, it's probably a good idea to first use the IsPaused() method, since it will be much faster.

And, since tests won't be paused most of the time, it's probably better to check for that like this: 

if executionState.IsPaused() {
    <-executionState.ResumeNotify()
}

func (*ExecutionState) ReturnVU added in v0.27.0 

func (es *ExecutionState) ReturnVU(vu InitializedVU, wasActive bool)

ReturnVU is a helper function that puts VUs back into the buffer and decreases the active VUs counter.

func (*ExecutionState) SetExecutionStatus added in v0.27.0 

func (es *ExecutionState) SetExecutionStatus(newStatus ExecutionStatus) (oldStatus ExecutionStatus)

SetExecutionStatus changes the current execution status to the supplied value and returns the current value.

func (*ExecutionState) SetInitVUFunc added in v0.27.0 

func (es *ExecutionState) SetInitVUFunc(initVUFunc InitVUFunc)

SetInitVUFunc is called by the execution scheduler's init function, and it's used for setting the "constructor" function used for the initializing unplanned VUs.

TODO: figure out a better dependency injection method?

type ExecutionStatus added in v0.27.0 

type ExecutionStatus uint32

ExecutionStatus is similar to RunStatus, but more fine grained and concerns only local execution. 

const (
	ExecutionStatusCreated ExecutionStatus = iota
	ExecutionStatusInitVUs
	ExecutionStatusInitExecutors
	ExecutionStatusInitDone
	ExecutionStatusPausedBeforeRun
	ExecutionStatusStarted
	ExecutionStatusSetup
	ExecutionStatusRunning
	ExecutionStatusTeardown
	ExecutionStatusEnded
)

Possible execution status values

func ExecutionStatusString added in v0.27.0 

func ExecutionStatusString(s string) (ExecutionStatus, error)

ExecutionStatusString retrieves an enum value from the enum constants string name. Throws an error if the param is not part of the enum.

func ExecutionStatusValues added in v0.27.0 

func ExecutionStatusValues() []ExecutionStatus

ExecutionStatusValues returns all values of the enum

func (ExecutionStatus) IsAExecutionStatus added in v0.27.0 

func (i ExecutionStatus) IsAExecutionStatus() bool

IsAExecutionStatus returns "true" if the value is listed in the enum definition. "false" otherwise

func (ExecutionStatus) String added in v0.27.0 

func (i ExecutionStatus) String() string

type ExecutionStep added in v0.27.0 

type ExecutionStep struct {
	TimeOffset      time.Duration
	PlannedVUs      uint64
	MaxUnplannedVUs uint64
}

ExecutionStep is used by different executors to specify the planned number of VUs they will need at a particular time. The times are relative to their StartTime, i.e. they don't take into account the specific starting time of the executor, as that will be considered by the external execution executor separately.

A slice [{t1, v1}, {t2, v2}, {t3, v3}, ..., {tn, vn}] of execution steps means that an executor will need 0 VUs until t1, it will need v1 number of VUs from time t1 until t2, need v2 number of VUs from time t2 to t3, and so on. t1 is usually 0, tn is usually the same as GetMaxDuration() and vn is usually 0.

Keep in mind that t(i) may be exactly equal to t(i+i), when there's an abrupt transition in the number of VUs required by an executor. For example, the ramping-vus executor may have 0-duration stages, or it may scale up VUs in its last stage right until the end. These immediate transitions cannot be ignored, since the gracefulStop/gracefulRampDown options potentially allow any started iterations to finish.

[]ExecutionStep is also used by the ScenarioConfigs, to represent the amount of needed VUs among all executors, during the whole execution of a test script. In that context, each executor's StartTime is accounted for and included in the offsets.

type ExecutionTuple added in v0.27.0 

type ExecutionTuple struct {
	Sequence     *ExecutionSegmentSequenceWrapper
	Segment      *ExecutionSegment
	SegmentIndex int
}

ExecutionTuple is the combination of an ExecutionSegmentSequence(Wrapper) and a specific ExecutionSegment from it. It gives easy access to the efficient scaling and striping algorithms for that specific segment, since the results are cached in the sequence wrapper.

func NewExecutionTuple added in v0.27.0 

func NewExecutionTuple(segment *ExecutionSegment, sequence *ExecutionSegmentSequence) (*ExecutionTuple, error)

NewExecutionTuple returns a new ExecutionTuple for the provided segment and sequence.

TODO: don't return a pointer?

func (*ExecutionTuple) GetNewExecutionTupleFromValue added in v0.27.0 

func (et *ExecutionTuple) GetNewExecutionTupleFromValue(value int64) (*ExecutionTuple, error)

GetNewExecutionTupleFromValue re-segments the sequence, based on the given value (see GetNewExecutionSegmentSequenceFromValue() above), and either returns the new tuple, or an error if the current segment isn't present in the new sequence.

func (*ExecutionTuple) GetStripedOffsets added in v0.27.0 

func (et *ExecutionTuple) GetStripedOffsets() (int64, []int64, int64)

GetStripedOffsets returns the striped offsets for our execution segment.

func (*ExecutionTuple) ScaleInt64 added in v0.27.0 

func (et *ExecutionTuple) ScaleInt64(value int64) int64

ScaleInt64 scales the provided value for our execution segment.

func (*ExecutionTuple) String added in v0.27.0 

func (et *ExecutionTuple) String() string

type Executor added in v0.17.0 

type Executor interface {
	GetConfig() ExecutorConfig
	GetProgress() *pb.ProgressBar
	GetLogger() *logrus.Entry

	Init(ctx context.Context) error
	Run(ctx context.Context, engineOut chan<- stats.SampleContainer) error
}

Executor is the interface all executors should implement

type ExecutorConfig added in v0.27.0 

type ExecutorConfig interface {
	Validate() []error

	GetName() string
	GetType() string
	GetStartTime() time.Duration
	GetGracefulStop() time.Duration

	// This is used to validate whether a particular script can run in the cloud
	// or, in the future, in the native k6 distributed execution. Currently only
	// the externally-controlled executor should return false.
	IsDistributable() bool

	GetEnv() map[string]string
	// Allows us to get the non-default function the executor should run, if it
	// has been specified.
	//
	// TODO: use interface{} so plain http requests can be specified?
	GetExec() string
	GetTags() map[string]string

	// Calculates the VU requirements in different stages of the executor's
	// execution, including any extensions caused by waiting for iterations to
	// finish with graceful stops or ramp-downs.
	GetExecutionRequirements(*ExecutionTuple) []ExecutionStep

	// Return a human-readable description of the executor
	GetDescription(*ExecutionTuple) string

	NewExecutor(*ExecutionState, *logrus.Entry) (Executor, error)

	// HasWork reports whether there is any work for the executor to do with a given segment.
	HasWork(*ExecutionTuple) bool
}

ExecutorConfig is an interface that should be implemented by all executor config types

func GetParsedExecutorConfig added in v0.27.0 

func GetParsedExecutorConfig(name, configType string, rawJSON []byte) (result ExecutorConfig, err error)

GetParsedExecutorConfig returns a struct instance corresponding to the supplied config type. It will be fully initialized - with both the default values of the type, as well as with whatever the user had specified in the JSON

type ExecutorConfigConstructor added in v0.27.0 

type ExecutorConfigConstructor func(name string, rawJSON []byte) (ExecutorConfig, error)

ExecutorConfigConstructor is a simple function that returns a concrete Config instance with the specified name and all default values correctly initialized

type Group 

type Group struct {
	// Arbitrary name of the group.
	Name string `json:"name"`

	// A group may belong to another group, which may belong to another group, etc. The Path
	// describes the hierarchy leading down to this group, with the segments delimited by '::'.
	// As an example: a group "Inner" inside a group named "Outer" would have a path of
	// "::Outer::Inner". The empty first item is the root group, which is always named "".
	Parent *Group `json:"-"`
	Path   string `json:"path"`

	// A group's ID is a hash of the Path. It is deterministic between different k6
	// instances of the same version, but should be treated as opaque - the hash function
	// or length may change.
	ID string `json:"id"`

	// Groups and checks that are children of this group.
	Groups        map[string]*Group `json:"groups"`
	OrderedGroups []*Group          `json:"-"`

	Checks        map[string]*Check `json:"checks"`
	OrderedChecks []*Check          `json:"-"`
	// contains filtered or unexported fields
}

A Group is an organisational block, that samples and checks may be tagged with.

For more information, refer to the js/modules/k6.K6.Group() function.

func NewGroup 

func NewGroup(name string, parent *Group) (*Group, error)

Creates a new group with the given name and parent group.

The root group must be created with the name "" and parent set to nil; this is the only case where a nil parent or empty name is allowed.

func (*Group) Check 

func (g *Group) Check(name string) (*Check, error)

Check creates a child check belonging to this group. This is safe to call from multiple goroutines simultaneously.

func (*Group) Group 

func (g *Group) Group(name string) (*Group, error)

Group creates a child group belonging to this group. This is safe to call from multiple goroutines simultaneously.

type HostAddress added in v0.32.0 

type HostAddress net.TCPAddr

HostAddress stores information about IP and port for a host.

func NewHostAddress added in v0.32.0 

func NewHostAddress(ip net.IP, portString string) (*HostAddress, error)

NewHostAddress creates a pointer to a new address with an IP object.

func (*HostAddress) MarshalText added in v0.32.0 

func (h *HostAddress) MarshalText() ([]byte, error)

MarshalText implements the encoding.TextMarshaler interface. The encoding is the same as returned by String, with one exception: When len(ip) is zero, it returns an empty slice.

func (*HostAddress) String added in v0.32.0 

func (h *HostAddress) String() string

String converts a HostAddress into a string.

func (*HostAddress) UnmarshalText added in v0.32.0 

func (h *HostAddress) UnmarshalText(text []byte) error

UnmarshalText implements the encoding.TextUnmarshaler interface. The IP address is expected in a form accepted by ParseIP.

type IPNet added in v0.25.0 

type IPNet struct {
	net.IPNet
}

IPNet is a wrapper around net.IPNet for JSON unmarshalling

func ParseCIDR added in v0.25.0 

func ParseCIDR(s string) (*IPNet, error)

ParseCIDR creates an IPNet out of a CIDR string

func (*IPNet) UnmarshalText added in v0.25.0 

func (ipnet *IPNet) UnmarshalText(b []byte) error

UnmarshalText populates the IPNet from the given CIDR

type InitVUFunc added in v0.27.0 

type InitVUFunc func(context.Context, *logrus.Entry) (InitializedVU, error)

InitVUFunc is just a shorthand so we don't have to type the function signature every time.

type InitializedVU added in v0.27.0 

type InitializedVU interface {
	// Fully activate the VU so it will be able to run code
	Activate(*VUActivationParams) ActiveVU

	// GetID returns the unique VU ID
	GetID() int64
}

InitializedVU represents a virtual user ready for work. It needs to be activated (i.e. given a context) before it can actually be used. Activation also requires a callback function, which will be called when the supplied context is done. That way, VUs can be returned to a pool and reused.

type LiveUpdatableExecutor added in v0.27.0 

type LiveUpdatableExecutor interface {
	UpdateConfig(ctx context.Context, newConfig interface{}) error
}

LiveUpdatableExecutor should be implemented for the executors whose configuration can be modified in the middle of the test execution. Currently, only the manual execution executor implements it.

type MultiSlotLimiter added in v0.26.0 

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

MultiSlotLimiter can restrict the concurrent execution of different groups of tasks to the given `slots` limit. Each group is represented with a string ID.

func NewMultiSlotLimiter added in v0.26.0 

func NewMultiSlotLimiter(slots int) *MultiSlotLimiter

NewMultiSlotLimiter initializes and returns a new MultiSlotLimiter with the given slot count TODO: move to lib and use something better than a mutex? sync.Map perhaps?

func (*MultiSlotLimiter) Slot added in v0.26.0 

func (l *MultiSlotLimiter) Slot(s string) SlotLimiter

Slot is used to retrieve the corresponding slot to the given string ID. If no slot with that ID exists, it creates it and saves it for future use. It is safe to call this method concurrently.

type Options 

type Options struct {
	// Should the test start in a paused state?
	Paused null.Bool `json:"paused" envconfig:"K6_PAUSED"`

	// Initial values for VUs, max VUs, duration cap, iteration cap, and stages.
	// See the Runner or Executor interfaces for more information.
	VUs        null.Int           `json:"vus" envconfig:"K6_VUS"`
	Duration   types.NullDuration `json:"duration" envconfig:"K6_DURATION"`
	Iterations null.Int           `json:"iterations" envconfig:"K6_ITERATIONS"`
	Stages     []Stage            `json:"stages" envconfig:"K6_STAGES"`

	// TODO: remove the `ignored:"true"` from the field tags, it's there so that
	// the envconfig library will ignore those fields.
	//
	// We should support specifying execution segments via environment
	// variables, but we currently can't, because envconfig has this nasty bug
	// (among others): https://github.com/kelseyhightower/envconfig/issues/113
	Scenarios                ScenarioConfigs           `json:"scenarios,omitempty" ignored:"true"`
	ExecutionSegment         *ExecutionSegment         `json:"executionSegment" ignored:"true"`
	ExecutionSegmentSequence *ExecutionSegmentSequence `json:"executionSegmentSequence" ignored:"true"`

	// Timeouts for the setup() and teardown() functions
	NoSetup         null.Bool          `json:"noSetup" envconfig:"NO_SETUP"`
	SetupTimeout    types.NullDuration `json:"setupTimeout" envconfig:"K6_SETUP_TIMEOUT"`
	NoTeardown      null.Bool          `json:"noTeardown" envconfig:"NO_TEARDOWN"`
	TeardownTimeout types.NullDuration `json:"teardownTimeout" envconfig:"K6_TEARDOWN_TIMEOUT"`

	// Limit HTTP requests per second.
	RPS null.Int `json:"rps" envconfig:"K6_RPS"`

	// DNS handling configuration.
	DNS types.DNSConfig `json:"dns" envconfig:"K6_DNS"`

	// How many HTTP redirects do we follow?
	MaxRedirects null.Int `json:"maxRedirects" envconfig:"K6_MAX_REDIRECTS"`

	// Default User Agent string for HTTP requests.
	UserAgent null.String `json:"userAgent" envconfig:"K6_USER_AGENT"`

	// How many batch requests are allowed in parallel, in total and per host?
	Batch        null.Int `json:"batch" envconfig:"K6_BATCH"`
	BatchPerHost null.Int `json:"batchPerHost" envconfig:"K6_BATCH_PER_HOST"`

	// Should all HTTP requests and responses be logged (excluding body)?
	HTTPDebug null.String `json:"httpDebug" envconfig:"K6_HTTP_DEBUG"`

	// Accept invalid or untrusted TLS certificates.
	InsecureSkipTLSVerify null.Bool `json:"insecureSkipTLSVerify" envconfig:"K6_INSECURE_SKIP_TLS_VERIFY"`

	// Specify TLS versions and cipher suites, and present client certificates.
	TLSCipherSuites *TLSCipherSuites `json:"tlsCipherSuites" envconfig:"K6_TLS_CIPHER_SUITES"`
	TLSVersion      *TLSVersions     `json:"tlsVersion" ignored:"true"`
	TLSAuth         []*TLSAuth       `json:"tlsAuth" envconfig:"K6_TLSAUTH"`

	// Throw warnings (eg. failed HTTP requests) as errors instead of simply logging them.
	Throw null.Bool `json:"throw" envconfig:"K6_THROW"`

	// Define thresholds; these take the form of 'metric=["snippet1", "snippet2"]'.
	// To create a threshold on a derived metric based on tag queries ("submetrics"), create a
	// metric on a nonexistent metric named 'real_metric{tagA:valueA,tagB:valueB}'.
	Thresholds map[string]stats.Thresholds `json:"thresholds" envconfig:"K6_THRESHOLDS"`

	// Blacklist IP ranges that tests may not contact. Mainly useful in hosted setups.
	BlacklistIPs []*IPNet `json:"blacklistIPs" envconfig:"K6_BLACKLIST_IPS"`

	// Block hostname patterns that tests may not contact.
	BlockedHostnames types.NullHostnameTrie `json:"blockHostnames" envconfig:"K6_BLOCK_HOSTNAMES"`

	// Hosts overrides dns entries for given hosts
	Hosts map[string]*HostAddress `json:"hosts" envconfig:"K6_HOSTS"`

	// Disable keep-alive connections
	NoConnectionReuse null.Bool `json:"noConnectionReuse" envconfig:"K6_NO_CONNECTION_REUSE"`

	// Do not reuse connections between VU iterations. This gives more realistic results (depending
	// on what you're looking for), but you need to raise various kernel limits or you'll get
	// errors about running out of file handles or sockets, or being unable to bind addresses.
	NoVUConnectionReuse null.Bool `json:"noVUConnectionReuse" envconfig:"K6_NO_VU_CONNECTION_REUSE"`

	// MinIterationDuration can be used to force VUs to pause between iterations if a specific
	// iteration is shorter than the specified value.
	MinIterationDuration types.NullDuration `json:"minIterationDuration" envconfig:"K6_MIN_ITERATION_DURATION"`

	// These values are for third party collectors' benefit.
	// Can't be set through env vars.
	External map[string]json.RawMessage `json:"ext" ignored:"true"`

	// Summary trend stats for trend metrics (response times) in CLI output
	SummaryTrendStats []string `json:"summaryTrendStats" envconfig:"K6_SUMMARY_TREND_STATS"`

	// Summary time unit for summary metrics (response times) in CLI output
	SummaryTimeUnit null.String `json:"summaryTimeUnit" envconfig:"K6_SUMMARY_TIME_UNIT"`

	// Which system tags to include with metrics ("method", "vu" etc.)
	// Use pointer for identifying whether user provide any tag or not.
	SystemTags *stats.SystemTagSet `json:"systemTags" envconfig:"K6_SYSTEM_TAGS"`

	// Tags to be applied to all samples for this running
	RunTags *stats.SampleTags `json:"tags" envconfig:"K6_TAGS"`

	// Buffer size of the channel for metric samples; 0 means unbuffered
	MetricSamplesBufferSize null.Int `json:"metricSamplesBufferSize" envconfig:"K6_METRIC_SAMPLES_BUFFER_SIZE"`

	// Do not reset cookies after a VU iteration
	NoCookiesReset null.Bool `json:"noCookiesReset" envconfig:"K6_NO_COOKIES_RESET"`

	// Discard Http Responses Body
	DiscardResponseBodies null.Bool `json:"discardResponseBodies" envconfig:"K6_DISCARD_RESPONSE_BODIES"`

	// Redirect console logging to a file
	ConsoleOutput null.String `json:"-" envconfig:"K6_CONSOLE_OUTPUT"`

	// Specify client IP ranges and/or CIDR from which VUs will make requests
	LocalIPs types.NullIPPool `json:"-" envconfig:"K6_LOCAL_IPS"`
}

func (Options) Apply 

func (o Options) Apply(opts Options) Options

Returns the result of overwriting any fields with any that are set on the argument.

Example: 

a := Options{VUs: null.IntFrom(10), VUsMax: null.IntFrom(10)}
b := Options{VUs: null.IntFrom(5)}
a.Apply(b) // Options{VUs: null.IntFrom(5), VUsMax: null.IntFrom(10)}

func (Options) ForEachSpecified added in v0.24.0 

func (o Options) ForEachSpecified(structTag string, callback func(key string, value interface{}))

ForEachSpecified enumerates all struct fields and calls the supplied function with each element that is valid. It panics for any unfamiliar or unexpected fields, so make sure new fields in Options are accounted for.

func (Options) Validate added in v0.24.0 

func (o Options) Validate() []error

Validate checks if all of the specified options make sense

type PausableExecutor added in v0.27.0 

type PausableExecutor interface {
	SetPaused(bool) error
}

PausableExecutor should be implemented by the executors that can be paused and resumed in the middle of the test execution. Currently, only the externally controlled executor implements it.

type RunStatus added in v0.22.0 

type RunStatus int

RunStatus values can be used by k6 to denote how a script run ends and by the cloud executor and collector so that k6 knows the current status of a particular script run. 

const (
	RunStatusCreated            RunStatus = -2
	RunStatusValidated          RunStatus = -1
	RunStatusQueued             RunStatus = 0
	RunStatusInitializing       RunStatus = 1
	RunStatusRunning            RunStatus = 2
	RunStatusFinished           RunStatus = 3
	RunStatusTimedOut           RunStatus = 4
	RunStatusAbortedUser        RunStatus = 5
	RunStatusAbortedSystem      RunStatus = 6
	RunStatusAbortedScriptError RunStatus = 7
	RunStatusAbortedThreshold   RunStatus = 8
)

Possible run status values; iota isn't used intentionally

type Runner 

type Runner interface {
	// Creates an Archive of the runner. There should be a corresponding NewFromArchive() function
	// that will restore the runner from the archive.
	MakeArchive() *Archive

	// Spawns a new VU. It's fine to make this function rather heavy, if it means a performance
	// improvement at runtime. Remember, this is called once per VU and normally only at the start
	// of a test - RunOnce() may be called hundreds of thousands of times, and must be fast.
	NewVU(id int64, out chan<- stats.SampleContainer) (InitializedVU, error)

	// Runs pre-test setup, if applicable.
	Setup(ctx context.Context, out chan<- stats.SampleContainer) error

	// Returns json representation of the setup data if setup() is specified and run, nil otherwise
	GetSetupData() []byte

	// Saves the externally supplied setup data as json in the runner
	SetSetupData([]byte)

	// Runs post-test teardown, if applicable.
	Teardown(ctx context.Context, out chan<- stats.SampleContainer) error

	// Returns the default (root) Group.
	GetDefaultGroup() *Group

	// Get and set options. The initial value will be whatever the script specifies (for JS,
	// `export let options = {}`); cmd/run.go will mix this in with CLI-, config- and env-provided
	// values and write it back to the runner.
	GetOptions() Options
	SetOptions(opts Options) error

	// Returns whether the given name is an exported and executable
	// function in the script.
	IsExecutable(string) bool

	HandleSummary(context.Context, *Summary) (map[string]io.Reader, error)
}

A Runner is a factory for VUs. It should precompute as much as possible upon creation (parse ASTs, load files into memory, etc.), so that spawning VUs becomes as fast as possible. The Runner doesn't actually *do* anything in itself, the ExecutionScheduler is responsible for wrapping and scheduling these VUs for execution.

TODO: Rename this to something more obvious? This name made sense a very long time ago.

type RuntimeOptions added in v0.20.0 

type RuntimeOptions struct {
	// Whether to pass the actual system environment variables to the JS runtime
	IncludeSystemEnvVars null.Bool `json:"includeSystemEnvVars"`

	// JS compatibility mode: "extended" (Goja+Babel+core.js) or "base" (plain Goja)
	//
	// TODO: when we resolve https://github.com/joshcarp/k6/issues/883, we probably
	// should use the CompatibilityMode type directly... but by then, we'd need to have
	// some way of knowing if the value has been set by the user or if we're using the
	// default one, so we can handle `k6 run --compatibility-mode=base es6_extended_archive.tar`
	CompatibilityMode null.String `json:"compatibilityMode"`

	// Environment variables passed onto the runner
	Env map[string]string `json:"env"`

	NoThresholds  null.Bool   `json:"noThresholds"`
	NoSummary     null.Bool   `json:"noSummary"`
	SummaryExport null.String `json:"summaryExport"`
}

RuntimeOptions are settings passed onto the goja JS runtime

type ScenarioConfigs added in v0.27.0 

type ScenarioConfigs map[string]ExecutorConfig

ScenarioConfigs can contain mixed executor config types

func (ScenarioConfigs) GetFullExecutionRequirements added in v0.27.0 

func (scs ScenarioConfigs) GetFullExecutionRequirements(et *ExecutionTuple) []ExecutionStep

GetFullExecutionRequirements combines the execution requirements from all of the configured executors. It takes into account their start times and their individual VU requirements and calculates the total VU requirements for each moment in the test execution.

func (ScenarioConfigs) GetSortedConfigs added in v0.27.0 

func (scs ScenarioConfigs) GetSortedConfigs() []ExecutorConfig

GetSortedConfigs returns a slice with the executor configurations, sorted in a consistent and predictable manner. It is useful when we want or have to avoid using maps with string keys (and tons of string lookups in them) and avoid the unpredictable iterations over Go maps. Slices allow us constant-time lookups and ordered iterations.

The configs in the returned slice will be sorted by their start times in an ascending order, and alphabetically by their names (which are unique) if there are ties.

func (*ScenarioConfigs) UnmarshalJSON added in v0.27.0 

func (scs *ScenarioConfigs) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface in a two-step manner, creating the correct type of configs based on the `type` property.

func (ScenarioConfigs) Validate added in v0.27.0 

func (scs ScenarioConfigs) Validate() (errors []error)

Validate checks if all of the specified executor options make sense

type SlotLimiter added in v0.26.0 

type SlotLimiter chan struct{}

SlotLimiter can restrict the concurrent execution of tasks to the given `slots` limit

func NewSlotLimiter added in v0.26.0 

func NewSlotLimiter(slots int) SlotLimiter

NewSlotLimiter initializes and returns a new SlotLimiter with the given slot count

func (SlotLimiter) Begin added in v0.26.0 

func (sl SlotLimiter) Begin()

Begin uses up a slot to denote the start of a task exeuction. It's a noop if the number of slots is 0, and if no slots are available, it blocks and waits.

func (SlotLimiter) End added in v0.26.0 

func (sl SlotLimiter) End()

End restores a slot and should be called at the end of a taks execution, preferably from a defer statement right after Begin()

type Stage 

type Stage StageFields

A Stage defines a step in a test's timeline.

func (Stage) MarshalJSON added in v0.18.0 

func (s Stage) MarshalJSON() ([]byte, error)

func (*Stage) UnmarshalJSON added in v0.9.2 

func (s *Stage) UnmarshalJSON(b []byte) error

For some reason, implementing UnmarshalText makes encoding/json treat the type as a string.

func (*Stage) UnmarshalText added in v0.18.0 

func (s *Stage) UnmarshalText(b []byte) error

type StageFields added in v0.18.0 

type StageFields struct {
	// Duration of the stage.
	Duration types.NullDuration `json:"duration"`

	// If Valid, the VU count will be linearly interpolated towards this value.
	Target null.Int `json:"target"`
}

StageFields defines the fields used for a Stage; this is a dumb hack to make the JSON code cleaner. pls fix.

type State added in v0.24.0 

type State struct {
	// Global options.
	Options Options

	// Logger. Avoid using the global logger.
	// TODO change to logrus.FieldLogger when there is time to fix all the tests
	Logger *logrus.Logger

	// Current group; all emitted metrics are tagged with this.
	Group *Group

	// Networking equipment.
	Transport http.RoundTripper
	Dialer    DialContexter
	CookieJar *cookiejar.Jar
	TLSConfig *tls.Config

	// Rate limits.
	RPSLimit *rate.Limiter

	// Sample channel, possibly buffered
	Samples chan<- stats.SampleContainer

	// Buffer pool; use instead of allocating fresh buffers when possible.
	// TODO: maybe use https://golang.org/pkg/sync/#Pool ?
	BPool *bpool.BufferPool

	Vu, Iteration int64
	Tags          map[string]string
}

State provides the volatile state for a VU.

func GetState added in v0.24.0 

func GetState(ctx context.Context) *State

func (*State) CloneTags added in v0.27.0 

func (s *State) CloneTags() map[string]string

CloneTags makes a copy of the tags map and returns it.

type Summary added in v0.32.0 

type Summary struct {
	Metrics         map[string]*stats.Metric
	RootGroup       *Group
	TestRunDuration time.Duration // TODO: use lib.ExecutionState-based interface instead?
}

Summary contains all of the data the summary handler gets.

type TLSAuth added in v0.17.2 

type TLSAuth struct {
	TLSAuthFields
	// contains filtered or unexported fields
}

Defines a TLS client certificate to present to certain hosts.

func (*TLSAuth) Certificate added in v0.17.2 

func (c *TLSAuth) Certificate() (*tls.Certificate, error)

func (*TLSAuth) UnmarshalJSON added in v0.17.2 

func (c *TLSAuth) UnmarshalJSON(data []byte) error

type TLSAuthFields added in v0.17.2 

type TLSAuthFields struct {
	// Certificate and key as a PEM-encoded string, including "-----BEGIN CERTIFICATE-----".
	Cert string `json:"cert"`
	Key  string `json:"key"`

	// Domains to present the certificate to. May contain wildcards, eg. "*.example.com".
	Domains []string `json:"domains"`
}

Fields for TLSAuth. Unmarshalling hack.

type TLSCipherSuites added in v0.17.0 

type TLSCipherSuites []uint16

A list of TLS cipher suites. Marshals and unmarshals from a list of names, eg. "TLS_ECDHE_RSA_WITH_RC4_128_SHA".

func (*TLSCipherSuites) MarshalJSON added in v0.32.0 

func (s *TLSCipherSuites) MarshalJSON() ([]byte, error)

MarshalJSON will return the JSON representation according to supported TLS cipher suites

func (*TLSCipherSuites) UnmarshalJSON added in v0.17.0 

func (s *TLSCipherSuites) UnmarshalJSON(data []byte) error

type TLSVersion added in v0.17.0 

type TLSVersion int

Describes a TLS version. Serialised to/from JSON as a string, eg. "tls1.2".

func (TLSVersion) MarshalJSON added in v0.19.0 

func (v TLSVersion) MarshalJSON() ([]byte, error)

func (*TLSVersion) UnmarshalJSON added in v0.17.0 

func (v *TLSVersion) UnmarshalJSON(data []byte) error

type TLSVersions added in v0.19.0 

type TLSVersions TLSVersionsFields

Describes a set (min/max) of TLS versions.

func (*TLSVersions) UnmarshalJSON added in v0.19.0 

func (v *TLSVersions) UnmarshalJSON(data []byte) error

type TLSVersionsFields added in v0.19.0 

type TLSVersionsFields struct {
	Min TLSVersion `json:"min" ignored:"true"` // Minimum allowed version, 0 = any.
	Max TLSVersion `json:"max" ignored:"true"` // Maximum allowed version, 0 = any.
}

Fields for TLSVersions. Unmarshalling hack.

type TimeoutError added in v0.24.0 

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

TimeoutError is used when somethings timeouts

func NewTimeoutError added in v0.24.0 

func NewTimeoutError(place string, d time.Duration) TimeoutError

NewTimeoutError returns a new TimeoutError reporting that timeout has happened at the given place and given duration.

func (TimeoutError) Error added in v0.24.0 

func (t TimeoutError) Error() string

Error implements error interface.

func (TimeoutError) Hint added in v0.26.0 

func (t TimeoutError) Hint() string

Hint returns a hint message for logging with given stage.

func (TimeoutError) Place added in v0.26.0 

func (t TimeoutError) Place() string

Place returns the place where timeout occurred.

func (TimeoutError) String added in v0.24.0 

func (t TimeoutError) String() string

String returns timeout error in human readable format.

type VUActivationParams added in v0.27.0 

type VUActivationParams struct {
	RunContext         context.Context
	DeactivateCallback func(InitializedVU)
	Env, Tags          map[string]string
	Exec, Scenario     string
}

VUActivationParams are supplied by each executor when it retrieves a VU from the buffer pool and activates it for use.

Source Files

View all Source files

Directories

Path Synopsis
httpext
httpmultibin
Package httpmultibin is indended only for use in tests, do not import in production code!
 Package httpmultibin is indended only for use in tests, do not import in production code!
minirunner
mockoutput
mockresolver

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.