diff --git a/gatsby-node.js b/gatsby-node.js index ba072e6e46..89cc1f6647 100644 --- a/gatsby-node.js +++ b/gatsby-node.js @@ -433,6 +433,12 @@ const createRedirects = ({ actions, pathPrefix }) => { '/javascript-api/k6-http/response-k6-http/response-submitform-params', isPermanent: true, }); + + createRedirect({ + fromPath: '/using-k6/cloud-execution', + toPath: '/cloud/creating-and-running-a-test/cloud-tests-from-the-cli', + isPermanent: true, + }); }; exports.createPages = async (options) => { diff --git a/src/data/markdown/docs/01 guides/01 Getting started/03 Running k6.md b/src/data/markdown/docs/01 guides/01 Getting started/03 Running k6.md index d90a43149b..13e41e8df9 100644 --- a/src/data/markdown/docs/01 guides/01 Getting started/03 Running k6.md +++ b/src/data/markdown/docs/01 guides/01 Getting started/03 Running k6.md @@ -3,28 +3,9 @@ title: 'Running k6' excerpt: '' --- -## Running k6 the first time +## Running local tests -This will run a very simple k6 sample script from github (click on the _Docker_ tab -if you prefer using the k6 [Docker image](https://en.wikipedia.org/wiki/Docker_%28software%29)): - -
- -```shell -$ k6 run github.com/loadimpact/k6/samples/http_get.js -``` - -```shell -$ docker run loadimpact/k6 run github.com/loadimpact/k6/samples/http_get.js -``` - -
- -You should see `k6` download the sample script and run it with a single virtual user (VU). - -## Executing local scripts - -Next, let's try to run a local script. Copy the code below, paste it into your +Let's start by running a simple local script. Copy the code below, paste it into your favourite editor, and save it as "script.js":
@@ -43,13 +24,19 @@ export default function() { Then run k6 using this command: -
+
```shell $ k6 run script.js ``` ```shell +# When using the `k6` docker image, you can't just give the script name since +# the script file will not be available to the container as it runs. Instead +# you must tell k6 to read `stdin` by passing the file name as `-`. Then you +# pipe the actual file into the container with `<` or equivalent. This will +# cause the file to be redirected into the container and be read by k6. + $ docker run -i loadimpact/k6 run - -### Docker syntax - -When using the `k6` docker image, you can't just give the script name since -the script file will not be available to the container as it runs. Instead -you must tell k6 to read `stdin` by passing the file name as `-`. Then you -pipe the actual file into the container with `<` or equivalent. This will -cause the file to be redirected into the container and be read by k6. - -> ### ⚠️ Note -> -> If your script imports other files (JS modules), piping like this -> will not work since the extra files will not be visible inside the container. -> To use modules you need to first mount your host/local directory into the -> Docker container, see [Modules with Docker](/using-k6/modules#using-local-modules-with-docker). - ## Adding more VUs -Now we'll try running a _real_ load test, with more than 1 virtual user and a slightly longer duration: +Now we'll try running a load test with more than 1 virtual user and a slightly longer duration: -
+
```shell k6 run --vus 10 --duration 30s script.js @@ -103,17 +75,17 @@ which allows you to break larger tests into smaller pieces, or make reusable pie Scripts must contain, at the very least, a `default` function - this defines the entry point for your VUs, similar to the `main()` function in many other languages: -
+
```javascript export default function() { - // do things here... + // vu code: do things here... } ```
-## The init context and the default function +### The init context and the default function "Why not just run my script normally, from top to bottom", you might ask - the answer is: we do, but code inside and outside your default function can do different things. @@ -121,37 +93,25 @@ but code inside and outside your default function can do different things. Code _inside_ `default` is called "VU code", and is run over and over for as long as the test is running. Code _outside_ of it is called "init code", and is run only once per VU. -VU code can make HTTP requests, emit metrics, and generally do everything you'd expect a load test -to do - with a few important exceptions: you can't load anything from your local filesystem, or -import any other modules. This all has to be done from init-code. - -There are two reasons for this. The first is, of course: performance. +
-If you read a file from disk on every single script iteration, it'd be needlessly slow; even if -you cache the contents of the file and any imported modules, it'd mean the _first run_ of the -script would be much slower than all the others. Worse yet, if you have a script that imports -or loads things based on things that can only be known at runtime, you'd get slow iterations -thrown in every time you load something new. +```js +// init code -But there's another, more interesting reason. By forcing all imports and file reads into the -init context, we design for distributed execution. We know which files will be needed, so we -distribute only those files. We know which modules will be imported, so we can bundle them up -from the get-go. And, tying into the performance point above, the other nodes don't even need -writable filesystems - everything can be kept in-memory. +export default function( { + // vu code +} -As an added bonus, you can use this to reuse data between iterations (but only for the same VU): +``` -
+
-```javascript -var counter = 0; +VU code can make HTTP requests, emit metrics, and generally do everything you'd expect a load test +to do - with a few important exceptions: you can't load anything from your local filesystem, or +import any other modules. This all has to be done from init-code. -export default function() { - counter++; -} -``` +Read more about the different [life cycle stages of a k6 test](/using-k6/test-life-cycle). -
## Using options @@ -177,7 +137,7 @@ export default function() { Then you just run the script without those parameters on the command line: -
+
```shell $ k6 run script.js @@ -221,63 +181,26 @@ export default function() {
-## Using checks - -Maybe we want to verify that an HTTP transaction worked and that the transaction time stayed below some acceptable value. We can use the [check()](/javascript-api/k6/check-val-sets-tags) function for this: - -
+## Running cloud tests -```javascript -import http from 'k6/http'; -import { check, sleep } from 'k6'; - -export let options = { - vus: 10, - duration: '30s', -}; - -export default function() { - let res = http.get('http://test.k6.io'); - check(res, { - 'status was 200': r => r.status == 200, - 'transaction time OK': r => r.timings.duration < 200, - }); - sleep(1); -} -``` +k6 supports three execution modes to run your k6 tests: -
+- [Local](#running-local-tests): on your local machine or a CI server. +- [Cloud](/cloud): on cloud infrastructure managed by k6 Cloud. +- Clustered: on more than one machine managed by you. [Not supported yet](https://github.com/loadimpact/k6/issues/140). -_Using check() to verify that transactions work and are fast enough_ +One of the goals with k6 is to support running a test in the three execution modes without making modifications to the script. -The above will generate a couple of extra output lines after the test, telling you if your check conditions succeeded or failed during the test. If the check conditions never failed, you will see this: +For running cloud tests from the CLI, you must first register a k6 Cloud account and then log into your account via the CLI. Then, you only have to pass your existing script to the `k6 cloud` command. -
+
```shell -done [==========================================================] 30s / 30s -✓ status was 200 OK -✓ transaction time OK +$ k6 cloud script.js ```
-And if a check condition fails, it will instead look like this: - -
- -```shell -done [==========================================================] 30s / 30s - -✗ status was 200 -↳ 0% — ✓ 0 / ✗ 150 -✓ transaction time OK -``` - -
- -If you are using [k6 Cloud Insights](/cloud/analyzing-results/overview) you can also see how a given check has failed or passed during the test run: - -![Cloud Insights checks](./images/cloud-insights-checks.png) +For detailed instructions and the different options, read more on [running cloud tests from the CLI](/cloud/creating-and-running-a-test/cloud-tests-from-the-cli). diff --git a/src/data/markdown/docs/01 guides/01 Getting started/06 k6 Cloud.md b/src/data/markdown/docs/01 guides/01 Getting started/06 k6 Cloud.md deleted file mode 100644 index 2dcd59ea15..0000000000 --- a/src/data/markdown/docs/01 guides/01 Getting started/06 k6 Cloud.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: 'k6 Cloud' -redirect: 'https://k6.io/docs/cloud' ---- diff --git a/src/data/markdown/docs/01 guides/02 Using k6/15 Test life cycle.md b/src/data/markdown/docs/01 guides/02 Using k6/15 Test life cycle.md index 3768c9da53..6459c199bf 100644 --- a/src/data/markdown/docs/01 guides/02 Using k6/15 Test life cycle.md +++ b/src/data/markdown/docs/01 guides/02 Using k6/15 Test life cycle.md @@ -67,6 +67,20 @@ we distribute only those files. We know which modules will be imported, so we ca up from the get-go. And, tying into the performance point above, the other nodes don't even need writable filesystems - everything can be kept in-memory. +As an added bonus, you can use this to reuse data between iterations (but only for the same VU): + +
+ +```javascript +var counter = 0; + +export default function() { + counter++; +} +``` + +
+ ## The default function life-cycle A VU will execute the default function from start to end in sequence. Nothing out of the ordinary diff --git a/src/data/markdown/docs/01 guides/02 Using k6/19 Cloud execution.md b/src/data/markdown/docs/01 guides/02 Using k6/19 Cloud execution.md deleted file mode 100644 index 2e9ddf50de..0000000000 --- a/src/data/markdown/docs/01 guides/02 Using k6/19 Cloud execution.md +++ /dev/null @@ -1,273 +0,0 @@ ---- -title: 'Cloud execution' -excerpt: '' ---- - -One of the goals with k6 is to support three execution modes to run your k6 tests: - -- **Local**: on your local machine or a CI server. -- **Cloud**: on cloud infrastructure managed by k6 (triggered - from local command-line, CI or cloud UI). -- **Clustered**: on more than one machine managed by you. - -k6 aims to support moving a script between the three execution modes -without having to make modifications to the script. - -Currently, k6 supports the local execution mode. The second execution -mode, cloud execution, is available by starting a trial of the Load -Impact cloud service. See the "Getting Started" steps below. - -## Getting started - -1. First, you need to create a k6 Cloud account, [register here](https://app.k6.io/account/register). - -2. Then you need to start a trial of our cloud service, [start trial here](https://app.k6.io/start-trial?utm_source=k6%20docs%20cloud%20exec&utm_medium=CTA&utm_campaign=Start%20Trial%20Insights). - -3. After that you need to download [the latest release of k6](https://github.com/loadimpact/k6/releases). - -4. k6 needs a k6 Cloud API token to be able to communicate with the cloud. Log in to k6 Cloud from the CLI to save your token in a local config file: - -
- - ```shell - k6 login cloud - ``` - -
- - Alternatively, you could also get your token from the [API token - page](https://app.k6.io/account/api-token) and set the - environment variable `K6_CLOUD_TOKEN` or use `k6 login cloud --token YOUR_TOKEN`. - -5. Instruct k6 to run your test in the cloud. - -
- - ```shell - k6 cloud script.js - ``` - - ```shell - docker run -i -e K6_CLOUD_TOKEN= loadimpact/k6 cloud - - - > ### Docker usage - > - > Note the difference in specifying the `K6_CLOUD_TOKEN` environment variable using - > the `docker run -e` option. - > - > Also, when passing the script via stdin as shown in the example there is no way - > for the containerized k6 process to get the script filename, which is required - > for cloud execution. To fix this you can either mount the local filesystem as - > a Docker volume - > - >
- > - > ```shell - > docker run -i -e ... -v "$PWD/script.js:/script.js" loadimpact/k6 cloud /script.js - > ``` - > - >
- > - > or you will need to specify the `options.ext.loadimpact.name` property in the - > script itself. For example: - > - >
- > - > ```javascript - > export let options = { - > ext: { - > loadimpact: { - > name: 'My awesome test', - > }, - > }, - > }; - > ``` - > - >
- -6. You'll see k6 print some information and the URL of your test results. - - ![Cloud execution output](/images/02 Using k6/cloud-exec-output.png "Cloud execution output") - -7. Navigate to the URL to check your test results. During the initialization phase of a cloud test you'll see a screen like the following: - - ![Cloud execution init](/images/cloud-exec-test-init.png 'Cloud execution init') - - When the test is running, the result page for k6 tests - ("Insights") will be shown. The [k6 Cloud Results - docs](/cloud/analyzing-results/overview) - provides more documentation about the different test result - sections. - - ![Insights results](/images/cloud-insights-results.png 'Insights results') - -## Cloud execution options - -You can optionally define some cloud options in your k6 script. - -
- -```javascript -export let options = { - ext: { - loadimpact: { - name: 'Hello k6 cloud!', - 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. | -| 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](/using-k6/environment-variables) on the appropriate nodes (matching the `loadZone`): `__ENV["someDefaultLabel"]` | - -### List of supported load zones - -| 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` | - -### Run options - -
- -```shell -k6 cloud -h -``` - -
- -All the options, like `--vus` and `--duration` are the same between -the `k6 run` and `k6 cloud` commands. Check out the [Options -page](/using-k6/options) for more information about the different options. - -## Cloud execution tags - -[Tags](/using-k6/tags-and-groups) 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` | int | A unique number representing the ID of a load generator server taking part in the test. | - -![filter tags](/images/analysis-tab-tags.png 'Cloud execution tags') - -## Using setup/teardown life-cycle functions - -Your [setup and teardown life cycle functions](/using-k6/test-life-cycle) -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 -each test-wide. There's no guarantee though that the same cloud server -that executed the `setup()` will execute the `teardown()`. - -## Using environment variables - -To use [environment variables](/using-k6/environment-variables) when running -a cloud executed test you use one or more `-e KEY=VALUE` (or `--env KEY=VALUE`) CLI flags. - -> ### Use the CLI flags to set environment variables -> -> With cloud execution you must use the CLI flags (`-e`/`--env`) to -> set environment variables. 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." - -Given the script below, which reads the `MY_HOSTNAME` environment -variable, you'd execute it using the command line `k6 run -e MY_HOSTNAME=test.k6.io script.js`. - -
- -```javascript -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); -} -``` - -
- -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. - -## Running tests under a different project than your default one - -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 two options: - -1. You can specify the project ID in the script options: - -
- - ```javascript - export let options = { - ext: { - loadimpact: { - projectID: 123456, - }, - }, - }; - ``` - -
- -2. You can set the `K6_CLOUD_PROJECT_ID` environment variable when running the test. - - You find the ID of a k6 Cloud project by selecting the project in - the UI and looking in the URL bar of your browser, the `12345` in - `https://app.k6.io/projects/12345` is the project ID. - -## Differences between local and cloud execution - -There's currently one difference between local and cloud execution: -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 cloud execution. - -## Limits - -You're only limited to what your subscription, trial or premium, allows. diff --git a/src/data/markdown/docs/01 guides/02 Using k6/20 Javascript Compatibility Mode.md b/src/data/markdown/docs/01 guides/02 Using k6/19 Javascript Compatibility Mode.md similarity index 100% rename from src/data/markdown/docs/01 guides/02 Using k6/20 Javascript Compatibility Mode.md rename to src/data/markdown/docs/01 guides/02 Using k6/19 Javascript Compatibility Mode.md diff --git a/src/data/markdown/docs/01 guides/02 Using k6/images/analysis-tab-tags.png b/src/data/markdown/docs/01 guides/02 Using k6/images/analysis-tab-tags.png deleted file mode 100644 index 27e0bfd1c7..0000000000 Binary files a/src/data/markdown/docs/01 guides/02 Using k6/images/analysis-tab-tags.png and /dev/null differ diff --git a/src/data/markdown/docs/03 cloud/01 Creating and running a test/02 Running a test from the CLI.md b/src/data/markdown/docs/03 cloud/01 Creating and running a test/02 Running a test from the CLI.md new file mode 100644 index 0000000000..7382f9e821 --- /dev/null +++ b/src/data/markdown/docs/03 cloud/01 Creating and running a test/02 Running a test from the CLI.md @@ -0,0 +1,266 @@ +--- +title: 'Cloud tests from the CLI' +excerpt: '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. + +## Instructions + +1. First, you need to have a k6 Cloud account. If you don't have one, sign up [here](https://app.k6.io/account/register) and get 50 cloud tests with the Free Trial. + +2. Install k6 using the instructions [here](/getting-started/installation). + +3. Authenticate to k6 Cloud from the CLI. Log in using your username and password or your [API token](https://app.k6.io/account/api-token). + +
+ + ```shell + $ k6 login cloud + ``` + + ```shell + $ k6 login cloud --token + ``` + +
+ + `k6 login` stores your API Token in a local config file to authenticate to k6 Cloud when running cloud commands. + + +4. Run your test in the cloud. + +
+ + ```shell + $ k6 cloud script.js + ``` + + ```shell + # Note the difference in specifying the `K6_CLOUD_TOKEN` environment variable + # using the `docker run -e` option. + + $ docker run -i -e K6_CLOUD_TOKEN= loadimpact/k6 cloud - + + +6. You'll see k6 print some information and the URL of your test results. + +
+ + ```shell + /\ |‾‾| /‾‾/ /‾/ + /\ / \ | |_/ / / / + / \/ \ | | / ‾‾\ + / \ | |‾\ \ | (_) | + / __________ \ |__| \__\ \___/ .io + + execution: cloud + script: test.js + output: https://app.k6.io/runs/TEST_RUN_ID + ``` + +
+ +7. Navigate to the URL to check your test results. When the test is running, the test result page is shown. + + ![k6 Cloud Test Results](/images/cloud-insights-results.png 'k6 Cloud Test Results') + + Learn more about the different test result sections on the [k6 Cloud Results docs](/cloud/analyzing-results/overview). + +## Cloud execution options + +All the [k6 Options](/using-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. + +
+ +```javascript +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](/using-k6/environment-variables) on the appropriate nodes (matching the `loadZone`): `__ENV["someDefaultLabel"]` | + +### List of supported load zones + +| 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` | + + +### Running tests under a different project than your default one + +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. + +![k6 Cloud Project ID](/images/dashboard-project-id.png 'Project ID') + +You have two options to pass the Project ID to k6: + +1. Specify it in the script options: + +
+ + ```javascript + export let options = { + ext: { + loadimpact: { + projectID: 123456, + }, + }, + }; + ``` + +
+ +2. Set the `K6_CLOUD_PROJECT_ID` environment variable when running the test. + + + +## Cloud execution tags + +[Tags](/using-k6/tags-and-groups) 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. | + +![filter tags](/images/analysis-tab-cloud-tags.png 'Cloud execution tags') + + +## Environment variables + +[Environment variables](/using-k6/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. + + +
+ +```javascript +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: + + +
+ +```js +$ k6 run -e MY_HOSTNAME=test.k6.io script.js +``` + +
+ +### Injected environment variables on the cloud execution + +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. + + +## Differences between local and cloud execution + +### Iterations + +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. + + +### Using setup/teardown life-cycle functions + +Your [setup and teardown life cycle functions](/using-k6/test-life-cycle) +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()`. \ No newline at end of file diff --git a/src/data/markdown/docs/03 cloud/01 Creating and running a test/02 In-app script editor.md b/src/data/markdown/docs/03 cloud/01 Creating and running a test/03 In-app script editor.md similarity index 100% rename from src/data/markdown/docs/03 cloud/01 Creating and running a test/02 In-app script editor.md rename to src/data/markdown/docs/03 cloud/01 Creating and running a test/03 In-app script editor.md diff --git a/src/data/markdown/docs/03 cloud/01 Creating and running a test/03 Recording a test script.md b/src/data/markdown/docs/03 cloud/01 Creating and running a test/04 Recording a test script.md similarity index 98% rename from src/data/markdown/docs/03 cloud/01 Creating and running a test/03 Recording a test script.md rename to src/data/markdown/docs/03 cloud/01 Creating and running a test/04 Recording a test script.md index cd02627e7c..8830d2b42e 100644 --- a/src/data/markdown/docs/03 cloud/01 Creating and running a test/03 Recording a test script.md +++ b/src/data/markdown/docs/03 cloud/01 Creating and running a test/04 Recording a test script.md @@ -28,7 +28,7 @@ The k6 Cloud Chrome extension will capture everything – every single HTTP(s) r ![Step 3](images/03 Recording a test script/Step 3.png) 4. **Save your test scripts** - Save the recorded script in any of your projects. + Save the recorded script in any of your projects. If any _third party requests_ or requests to download assets were made during the recording those requests will be filtered out by default. Would you want to include some of the requests in the _third party list_ simply deselect the ones you want to include then hit save. ![Step 4](images/03 Recording a test script/Step 4.png) diff --git a/src/data/markdown/docs/03 cloud/01 Creating and running a test/04 Converters.md b/src/data/markdown/docs/03 cloud/01 Creating and running a test/05 Converters.md similarity index 100% rename from src/data/markdown/docs/03 cloud/01 Creating and running a test/04 Converters.md rename to src/data/markdown/docs/03 cloud/01 Creating and running a test/05 Converters.md diff --git a/src/data/markdown/docs/03 cloud/01 Creating and running a test/06 Running a test from the CLI.md b/src/data/markdown/docs/03 cloud/01 Creating and running a test/06 Running a test from the CLI.md deleted file mode 100644 index cc6a8b1bd9..0000000000 --- a/src/data/markdown/docs/03 cloud/01 Creating and running a test/06 Running a test from the CLI.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: 'Cloud tests from the CLI' -excerpt: 'How to run cloud tests from the k6 CLI.' ---- - -## Background - -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 tests from the command line. - -Reasons for triggering cloud tests from the command line include: - -- Integrating testing in CI/CD pipelines -- Storing test scripts in local version control -- Modularization of scripts for collaboration and easier maintenance -- Preference to work in your local environment - - -## Quick Start to using the CLI for cloud tests - -Assuming you have k6 installed and a script saved locally, the first step would -be to authenticate against the k6 Cloud, like so: - -
- -```shell -k6 login cloud -``` - -
- -Alternatively, you could also get your token from the [API token -page](https://app.k6.io/account/api-token) and set the -environment variable `K6_CLOUD_TOKEN` or use `k6 login cloud --token YOUR_TOKEN`. - -Once authenticated, you can trigger a test by using the `cloud` command: - -
- -```shell -k6 cloud nameOfYourScript.js -``` -
- -For more in depth instructions, please refer to our full article on -[cloud execution](/using-k6/cloud-execution#getting-started) diff --git a/src/data/markdown/docs/03 cloud/01 Creating and running a test/05 Scheduling a test.md b/src/data/markdown/docs/03 cloud/01 Creating and running a test/06 Scheduling a test.md similarity index 100% rename from src/data/markdown/docs/03 cloud/01 Creating and running a test/05 Scheduling a test.md rename to src/data/markdown/docs/03 cloud/01 Creating and running a test/06 Scheduling a test.md diff --git a/src/data/markdown/docs/03 cloud/01 Creating and running a test/images/analysis-tab-cloud-tags.png b/src/data/markdown/docs/03 cloud/01 Creating and running a test/images/analysis-tab-cloud-tags.png new file mode 100644 index 0000000000..7ad90a605d Binary files /dev/null and b/src/data/markdown/docs/03 cloud/01 Creating and running a test/images/analysis-tab-cloud-tags.png differ diff --git a/src/data/markdown/docs/03 cloud/01 Creating and running a test/images/dashboard-project-id.png b/src/data/markdown/docs/03 cloud/01 Creating and running a test/images/dashboard-project-id.png new file mode 100644 index 0000000000..622d1947b6 Binary files /dev/null and b/src/data/markdown/docs/03 cloud/01 Creating and running a test/images/dashboard-project-id.png differ