Grafana Cloud Performance testing Get started Run cloud tests from the CLI

Run cloud tests from the CLI

While the Test Builder is a nice way to learn the API and prototype tests, testers usually prefer to write scripts in their local code editor. k6 is also a command-line tool, and you can use it to write test files on your machine and execute them on Grafana Cloud k6.

In this topic, learn how to use the CLI to:

• Run a test on your local machine
• Run that same test on Grafana Cloud k6
• Run the test locally and stream it to the cloud

Before you begin

To run a CLI test, you’ll need:

• A machine with k6 installed
• A k6 token
• A test file

For your test file, you can copy the script prototyped in Build your first test. In the directory where you want to run your test, save this as cloud_demo.js.

To keep demo run times short, the total test duration has been modified to be only 45 seconds.

JavaScript Copy

import { sleep } from 'k6';
import http from 'k6/http';

export const options = {
  ext: {
    loadimpact: {
      distribution: {
        'amazon:us:ashburn': { loadZone: 'amazon:us:ashburn', percent: 34 },
        'amazon:gb:london': { loadZone: 'amazon:gb:london', percent: 33 },
        'amazon:au:sydney': { loadZone: 'amazon:au:sydney', percent: 33 },
      },
    },
  },
  thresholds: {},
  scenarios: {
    Scenario_1: {
      executor: 'ramping-vus',
      gracefulStop: '30s',
      stages: [
        { target: 20, duration: '15s' },
        { target: 20, duration: '15s' },
        { target: 0, duration: '15s' },
      ],
      gracefulRampDown: '30s',
      exec: 'scenario_1',
    },
  },
};

export function scenario_1() {
  let response;

  // Get homepage
  response = http.get('https://test.k6.io/');

  // Automatically added sleep
  sleep(1);
}

Run tests

To run tests from the CLI, the first step is to open your terminal and navigate to the directory where you created your script.

After you do that, there are three different ways you can run your test.

Local execution

Running tests locally is a great way to incrementally test your script as you write it.

To run locally, use the k6 run command:

bash Copy

k6 run cloud_demo.js

Cloud execution

To run a cloud test from the CLI, you’ll need a token for authenticating the k6 CLI with the Grafana Cloud k6 application.

To get a personal token in Grafana Cloud:

1. Log in to your Grafana Cloud account.

2. Go to Performance testing > Settings.

3. Select Copy to clipboard to copy your personal API token.

4. Run the following command to authenticate with the k6 CLI, replacing K6_CLOUD_API_TOKEN with your personal API token:

   bash Copy

   k6 login cloud --token K6_CLOUD_API_TOKEN

   Note that you only need to authenticate once with your local k6 CLI. Alternatively, other authentication options are also available.

With the CLI authentication configured, you can run cloud tests by using the k6 cloud command:

bash Copy

k6 cloud cloud_demo.js

Run locally and stream to the Cloud

You can also run a test from a local machine and stream the results for storage and visualization on Grafana Cloud. A common use case for this feature is to run load tests on networks that aren’t accessible from the public internet.

To run a test locally and stream the results to Grafana Cloud k6, use the k6 run --out cloud:

bash Copy

k6 run --out cloud cloud_demo.js

Run a CLI test in a specific project

By default, when you run a test from the CLI, the test runs in your default project. To set the test run in a different project, specify the projectID option in the k6 script:

JavaScript Copy

export const options = {
  ext: {
    loadimpact: {
      projectID: 3479144,
    },
  },
};

In Grafana Cloud, you can find the projectID value below the project name on the project view: