title | excerpt |
---|---|
Cloud tests from the CLI |
How to run cloud tests from the k6 CLI. |
Running tests within the web app is helpful when getting a feel for the tool or building a proof of concept. However, many users will find great flexibility when using k6 to trigger cloud tests from the command line.
Reasons for triggering cloud tests from the k6 CLI include:
- Storing test scripts in local version control.
- Modularization of scripts for collaboration and easier maintenance.
- Preference to work in your local environment.
- Integrating testing in CI/CD pipelines.
-
First, you need to have a k6 Cloud account. If you don't have one, sign up here and get 50 cloud tests with the Free Trial.
-
Install k6 using the instructions here.
-
Authenticate to k6 Cloud from the CLI. Log in using your username and password or your API token.
$ k6 login cloud
$ k6 login cloud --token <YOUR_K6_CLOUD_API_TOKEN>
k6 login
stores your API Token in a local config file to authenticate to k6 Cloud when running cloud commands. -
Run your test in the cloud.
$ k6 cloud script.js
# Note the difference in specifying the `K6_CLOUD_TOKEN` environment variable # using the `docker run -e` option. $ docker run -i -e K6_CLOUD_TOKEN=<API_TOKEN> loadimpact/k6 cloud - <script.js # When passing the script via stdin there is no way for the containerized k6 process # to get the script filename, which is required for cloud execution. To solve this issue: # a) specify the `options.ext.loadimpact.name` property in the script: # export let options = { # ext: { # loadimpact: { # name: 'My awesome test', # }, # }, # }; # b) mount the local filesystem as a Docker volume: $ docker run -i -e ... -v "$PWD/script.js:/script.js" loadimpact/k6 cloud /script.js
-
You'll see k6 print some information and the URL of your test results.
/\ |‾‾| /‾‾/ /‾/ /\ / \ | |_/ / / / / \/ \ | | / ‾‾\ / \ | |‾\ \ | (_) | / __________ \ |__| \__\ \___/ .io execution: cloud script: test.js output: https://app.k6.io/runs/TEST_RUN_ID
-
Navigate to the URL to check your test results. When the test is running, the test result page is shown.
Learn more about the different test result sections on the k6 Cloud Results docs.
All the k6 Options, like --vus
and --duration
are the same between the k6 run
and k6 cloud
commands. k6 aims to run the same script in different execution modes without making any script modifications.
Optionally, you can define some cloud options in your k6 script.
export let options = {
ext: {
loadimpact: {
name: 'Hello k6 cloud!',
projectID: 123456,
distribution: {
scenarioLabel1: { loadZone: 'amazon:us:ashburn', percent: 50 },
scenarioLabel2: { loadZone: 'amazon:ie:dublin', percent: 50 },
},
},
},
};
Name | Default | Description |
---|---|---|
name (string) | Optional. The name of the main script file, so something like "script.js". | The name of the test in the k6 Cloud UI. Test runs with the same name will be grouped together. |
projectID (number) | Optional. It is empty by default. | The ID of the project in which the test is assigned in the k6 Cloud UI. By default, the default project of the user default organization. |
distribution (object) | Optional. The equivalent of someDefaultLabel: { loadZone: "amazon:us:ashburn", percent: 100 } . |
How the traffic should be distributed. The keys are string labels that will be injected as environment variables on the appropriate nodes (matching the loadZone ): __ENV["someDefaultLabel"] |
Location | ID |
---|---|
Tokyo | amazon:jp:tokyo |
Seoul | amazon:kr:seoul |
Mumbai | amazon:in:mumbai |
Singapore | amazon:sg:singapore |
Sydney | amazon:au:sydney |
Montreal | amazon:ca:montreal |
Frankfurt | amazon:de:frankfurt |
Ireland | amazon:ie:dublin |
London | amazon:gb:london |
Paris | amazon:fr:paris |
Stockholm | amazon:se:stockholm |
N. Virginia (Default) | amazon:us:ashburn |
Ohio | amazon:us:columbus |
N. California | amazon:us:palo alto |
Oregon | amazon:us:portland |
Hong Kong | amazon:cn:hong kong |
São Paulo | amazon:br:sao paulo |
By default tests and test runs will be created and run under your default project, in your default organization.
To create and run tests under a different project, whether under your default organization or one you've been invited to, you have to pass the Project ID
to k6.
Select the project on the sidebar menu and you will find the Project ID
in the header of the Project Dashboard page.
You have two options to pass the Project ID to k6:
-
Specify it in the script options:
export let options = { ext: { loadimpact: { projectID: 123456, }, }, };
-
Set the
K6_CLOUD_PROJECT_ID
environment variable when running the test.
Tags is a powerful concept in k6 as it opens up for great flexibility in how you can slice and dice the result data.
When running a k6 test in the cloud we add two tags to all metrics:
Tag name | Type | Description |
---|---|---|
load_zone |
string | The load zone from where the the metric was collected. Values will be of the form: amazon:us :ashburn . |
instance_id |
number | A unique number representing the ID of a load generator server taking part in the test. |
Environment variables set in the local terminal before executing k6 won't be forwarded to the k6 cloud service, and thus won't be available to your script when executing in the cloud.
With cloud execution, you must use the CLI flags (-e
/--env
) to set environment variables like -e KEY=VALUE
or --env KEY=VALUE
.
For example, given the script below, which reads the MY_HOSTNAME
environment variable.
import { check, sleep } from 'k6';
import http from 'k6/http';
export default function() {
var r = http.get(`http://${__ENV.MY_HOSTNAME}/`);
check(r, {
'status is 200': r => r.status === 200,
});
sleep(5);
}
You'd execute it using the command like:
$ k6 run -e MY_HOSTNAME=test.k6.io script.js
When running in the k6 Cloud there will be three additional environment variables that can be used to find out in which load zone, server instance, and distribution label the given script is currently running.
Name | Value | Description |
---|---|---|
LI_LOAD_ZONE |
string | The load zone from where the the metric was collected. Values will be of the form: amazon:us :ashburn (see list above). |
LI_INSTANCE_ID |
number | A sequential number representing the unique ID of a load generator server taking part in the test, starts at 0. |
LI_DISTRIBUTION |
string | The value of the "distribution label" that you used in ext.loadimpact.distribution corresponding to the load zone the script is currently executed in. |
You can read the values of these variables in your k6 script as usual.
Local execution has support for iterations based test length (-i
or
--iterations
on CLI, and iterations
in script options) which is
not yet supported by the cloud execution mode.
Your setup and teardown life cycle functions
are executed as normal when running cloud tests. Depending on the size
of your test, it will execute from one or more cloud servers, but the
setup and teardown will only execute from one server, so execute once
for each test run. There's no guarantee though that the same cloud server
that executed the setup()
will execute the teardown()
.