Menu
Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.
Open source
RSS
JavaScript API
The list of k6 modules natively supported in your k6 scripts.
Init context
Before the k6 starts the test logic, code in the init context prepares the script. A few functions are available only in init context. For details about the runtime, refer to the Test lifecycle.
| Function | Description |
|---|---|
| open( filePath, [mode] ) | Opens a file and reads all the contents into memory. |
k6
The k6 module contains k6-specific functionality.
| Function | Description |
|---|---|
| check(val, sets, [tags]) | Runs one or more checks on a value and generates a pass/fail result but does not throw errors or otherwise interrupt execution upon failure. |
| fail([err]) | Throws an error, failing and aborting the current VU script iteration immediately. |
| group(name, fn) | Runs code inside a group. Used to organize results in a test. |
| randomSeed(int) | Set seed to get a reproducible pseudo-random number using Math.random. |
| sleep(t) | Suspends VU execution for the specified duration. |
k6/crypto
The k6/crypto module provides common hashing functionality available in the GoLang crypto package.
| Function | Description |
|---|---|
| createHash(algorithm) | Create a Hasher object, allowing the user to add data to hash multiple times, and extract hash digests along the way. |
| createHMAC(algorithm, secret) | Create an HMAC hashing object, allowing the user to add data to hash multiple times, and extract hash digests along the way. |
| hmac(algorithm, secret, data, outputEncoding) | Use HMAC to sign an input string. |
| md4(input, outputEncoding) | Use MD4 to hash an input string. |
| md5(input, outputEncoding) | Use MD5 to hash an input string. |
| randomBytes(int) | Return an array with a number of cryptographically random bytes. |
| ripemd160(input, outputEncoding) | Use RIPEMD-160 to hash an input string. |
| sha1(input, outputEncoding) | Use SHA-1 to hash an input string. |
| sha256(input, outputEncoding) | Use SHA-256 to hash an input string. |
| sha384(input, outputEncoding) | Use SHA-384 to hash an input string. |
| sha512(input, outputEncoding) | Use SHA-512 to hash an input string. |
| sha512_224(input, outputEncoding) | Use SHA-512/224 to hash an input string. |
| sha512_256(input, outputEncoding) | Use SHA-512/256 to hash an input string. |
| Class | Description |
|---|---|
| Hasher | Object returned by crypto.createHash(). It allows adding more data to be hashed and to extract digests along the way. |
k6/data
The data module provides helpers to work with data.
| Class/Method | Description |
|---|---|
| SharedArray | read-only array like structure that shares memory between VUs |
k6/encoding
The encoding module provides base64 encoding/decoding as defined by RFC4648.
| Function | Description |
|---|---|
| b64decode(input, [encoding], [format]) | Base64 decode a string. |
| b64encode(input, [encoding]) | Base64 encode a string. |
k6/execution
k6/execution provides the capability to get information about the current test execution state inside the test script. You can read in your script the execution state during the test execution and change your script logic based on the current state.
The k6/execution module provides the test execution information with the following properties:
instance
The instance object provides information associated with the load generator instance. You can think of it as the current running k6 process, which will likely be a single process if you are running k6 on your local machine. When running a cloud/distributed test with multiple load generator instances, the values of the following properties can differ across instances.
| Property | Type | Description |
|---|---|---|
| iterationsInterrupted | integer | The number of prematurely interrupted iterations in the current instance. |
| iterationsCompleted | integer | The number of completed iterations in the current instance. |
| vusActive | integer | The number of active VUs. |
| vusInitialized | integer | The number of currently initialized VUs. |
| currentTestRunDuration | float | The time passed from the start of the current test run in milliseconds. |
scenario
Meta information and execution details about the current running scenario.
| Property | Type | Description |
|---|---|---|
| name | string | The assigned name of the running scenario. |
| executor | string | The name of the running Executor type. |
| startTime | integer | The Unix timestamp in milliseconds when the scenario started. |
| progress | float | Percentage in a 0 to 1 interval of the scenario progress. |
| iterationInInstance | integer | The unique and zero-based sequential number of the current iteration in the scenario, across the current instance. |
| iterationInTest | integer | The unique and zero-based sequential number of the current iteration in the scenario. It is unique in all k6 execution modes - in local, cloud and distributed/segmented test runs. However, while every instance will get non-overlapping index values in cloud/distributed tests, they might iterate over them at different speeds, so the values won’t be sequential across them. |
test
Control the test execution.
| Property | Type | Description |
|---|---|---|
| abort([String]) | function | It aborts the test run with the exit code 108, and an optional string parameter can provide an error message. Aborting the test will not prevent the teardown() execution. |
| options | Object | It returns an object with all the test options as properties. The options’ values are consolidated following the order of precedence and derived if shortcuts have been used. It returns null for properties where the relative option hasn’t been defined. |
vu
Meta information and execution details about the current vu.
| Property | Type | Description |
|---|---|---|
| iterationInInstance | integer | The identifier of the iteration in the current instance for this VU. This is only unique for current VU and this instance (if multiple instances). This keeps being aggregated if a given VU is reused between multiple scenarios. |
| iterationInScenario | integer | The identifier of the iteration in the current scenario for this VU. This is only unique for current VU and scenario it is currently executing. |
| idInInstance | integer | The identifier of the VU across the instance. Not unique across multiple instances. |
| idInTest | integer | The globally unique (across the whole test run) identifier of the VU. |
k6/experimental
| Modules | Description |
|---|---|
| browser | Provides browser-level APIs to interact with browsers and collect frontend performance metrics as part of your k6 tests. |
| redis | Functionality to interact with Redis. |
| timers | setTimeout, clearTimeout, setInterval, clearInterval |
| tracing | Support for instrumenting HTTP requests with tracing information. |
| webcrypto | Implements the WebCrypto API. |
| websockets | Implements the browser’s WebSocket API. |
| grpc | Extends k6/net/grpc with the streaming capabilities. |
| fs | Provides a memory-efficient way to handle file interactions within your test scripts. |
k6/html
The k6/html module contains functionality for HTML parsing.
| Function | Description |
|---|---|
| parseHTML(src) | Parse an HTML string and populate a Selection object. |
| Class | Description |
|---|---|
| Element | An HTML DOM element as returned by the Selection API. |
| Selection | A jQuery-like API for accessing HTML DOM elements. |
k6/http
The k6/http module contains functionality for performing HTTP transactions.
| Function | Description |
|---|---|
| batch( requests ) | Issue multiple HTTP requests in parallel (like e.g. browsers tend to do). |
| cookieJar() | Get active HTTP Cookie jar. |
| del( url, [body], [params] ) | Issue an HTTP DELETE request. |
| file( data, [filename], [contentType] ) | Create a file object that is used for building multi-part requests. |
| get( url, [params] ) | Issue an HTTP GET request. |
| head( url, [params] ) | Issue an HTTP HEAD request. |
| options( url, [body], [params] ) | Issue an HTTP OPTIONS request. |
| patch( url, [body], [params] ) | Issue an HTTP PATCH request. |
| post( url, [body], [params] ) | Issue an HTTP POST request. |
| put( url, [body], [params] ) | Issue an HTTP PUT request. |
| request( method, url, [body], [params] ) | Issue any type of HTTP request. |
| asyncRequest( method, url, [body], [params] ) | Issue any type of HTTP request asynchronously. |
| setResponseCallback(expectedStatuses) | Sets a response callback to mark responses as expected. |
| url`url` | Creates a URL with a name tag. Read more on URL Grouping. |
| expectedStatuses( statusCodes ) | Create a callback for setResponseCallback that checks status codes. |
| Class | Description |
|---|---|
| CookieJar | Used for storing cookies, set by the server and/or added by the client. |
| FileData | Used for wrapping data representing a file when doing multipart requests (file uploads). |
| Params | Used for setting various HTTP request-specific parameters such as headers, cookies, etc. |
| Response | Returned by the http.* methods that generate HTTP requests. |
k6/metrics
The metrics module provides functionality to create custom metrics of various types. All metrics (both the built-in metrics and the custom ones) have a type.
You can optionally tag all values added to a custom metric, which can be useful when analysing the test results.
| Metric type | Description |
|---|---|
| Counter | A metric that cumulatively sums added values. |
| Gauge | A metric that stores the min, max and last values added to it. |
| Rate | A metric that tracks the percentage of added values that are non-zero. |
| Trend | A metric that calculates statistics on the added values (min, max, average, and percentiles). |
k6/net/grpc
Note
A module with streaming support exists.
The new k6/experimental/grpc module extends k6/net/grpc to support gRPC streaming. We recommend using the new module.
The k6/net/grpc module provides a gRPC client for Remote Procedure Calls (RPC) over HTTP/2.
| Class/Method | Description |
|---|---|
| Client | gRPC client used for making RPC calls to a gRPC Server. |
| Client.load(importPaths, …protoFiles) | Loads and parses the given protocol buffer definitions to be made available for RPC requests. |
| Client.connect(address [,params]) | Connects to a given gRPC service. |
| Client.invoke(url, request [,params]) | Makes an unary RPC for the given service/method and returns a Response. |
| Client.close() | Close the connection to the gRPC service. |
| Params | RPC Request specific options. |
| Response | Returned by RPC requests. |
| Constants | Define constants to distinguish between gRPC Response statuses. |
k6/ws
The ws module provides a WebSocket client implementing the WebSocket protocol.
| Function | Description |
|---|---|
| connect( url, params, callback ) | Create a WebSocket connection, and provides a Socket client to interact with the service. The method blocks the test finalization until the connection is closed. |
| Class/Method | Description |
|---|---|
| Params | Used for setting various WebSocket connection parameters such as headers, cookie jar, compression, etc. |
| Socket | WebSocket client used to interact with a WS connection. |
| Socket.close() | Close the WebSocket connection. |
| Socket.on(event, callback) | Set up an event listener on the connection for any of the following events: - open - binaryMessage - message - ping - pong - close - error. |
| Socket.ping() | Send a ping. |
| Socket.send(data) | Send string data. |
| Socket.sendBinary(data) | Send binary data. |
| Socket.setInterval(callback, interval) | Call a function repeatedly at certain intervals, while the connection is open. |
| Socket.setTimeout(callback, period) | Call a function with a delay, if the connection is open. |
Error codes
The following specific error codes are currently defined:
- 1000: A generic error that isn’t any of the ones listed below.
- 1010: A non-TCP network error - this is a place holder there is no error currently known to trigger it.
- 1020: An invalid URL was specified.
- 1050: The HTTP request has timed out.
- 1100: A generic DNS error that isn’t any of the ones listed below.
- 1101: No IP for the provided host was found.
- 1110: Blacklisted IP was resolved or a connection to such was tried to be established.
- 1111: Blacklisted hostname using The Block Hostnames option.
- 1200: A generic TCP error that isn’t any of the ones listed below.
- 1201: A “broken pipe” on write - the other side has likely closed the connection.
- 1202: An unknown TCP error - We got an error that we don’t recognize but it is from the operating system and has
errnoset on it. The message inerrorincludes the operation(write,read) and the errno, the OS, and the original message of the error. - 1210: General TCP dial error.
- 1211: Dial timeout error - the timeout for the dial was reached.
- 1212: Dial connection refused - the connection was refused by the other party on dial.
- 1213: Dial unknown error.
- 1220: Reset by peer - the connection was reset by the other party, most likely a server.
- 1300: General TLS error
- 1310: Unknown authority - the certificate issuer is unknown.
- 1311: The certificate doesn’t match the hostname.
- 1400 to 1499: error codes that correspond to the HTTP 4xx status codes for client errors
- 1500 to 1599: error codes that correspond to the HTTP 5xx status codes for server errors
- 1600: A generic HTTP/2 error that isn’t any of the ones listed below.
- 1610: A general HTTP/2 GoAway error.
- 1611 to 1629: HTTP/2 GoAway errors with the value of the specific HTTP/2 error code added to 1611.
- 1630: A general HTTP/2 stream error.
- 1631 to 1649: HTTP/2 stream errors with the value of the specific HTTP/2 error code added to 1631.
- 1650: A general HTTP/2 connection error.
- 1651 to 1669: HTTP/2 connection errors with the value of the specific HTTP/2 error code added to 1651.
- 1701: Decompression error.
Read more about Error codes.
Was this page helpful?
Related resources from Grafana Labs
4 Dec
Performance testing and observability in Grafana Cloud
In this webinar, learn how Grafana Cloud k6 offers you the best developer experience for performance testing.
60 min
User-centered observability: load testing, real user monitoring, and synthetics
Learn how to use load testing, synthetic monitoring, and real user monitoring (RUM) to understand end users' experience of your apps. Watch on demand.