Skip to content

Latest commit

 

History

History
77 lines (49 loc) · 3 KB

create-test-script-using-the-cli.md

File metadata and controls

77 lines (49 loc) · 3 KB
title description weight
Create a test script using the CLI
Learn how to create a test using the k6 CLI and the k6 new command.
100

Create a test script using the CLI

Writing a k6 test script from scratch can seem challenging if you're just getting started with k6, or repetitive if you're already familiar with the tool. The k6 new command can help both new and experienced users quickly generate a test script, which they can use to try out k6, or use as a starting point to test out their applications and services.

Before you begin

To use the k6 new command, you'll need:

  • k6 v0.57 or higher installed on your machine.
  • Custom templates require k6 v1.0.0-rc1 or higher.

Use the k6 new command

To create a script with the k6 new command, run the following in your terminal:

k6 new

The command creates a k6 test script file named script.js in the current directory.

You can customize the script filename by passing the name as an argument. For example, to create a script named test.js:

k6 new test.js

Options

You can customize the generated script using the following options: --template and --project-id.

--template

The --template flag allows you to specify a template that best fits your use case.

The options are:

  • minimal: Creates a minimal test script with a short options configuration, and a single request and check example. This is the default option.
  • protocol: Creates a script that includes environment variables, stages with different durations and VUs, thresholds, and a setup function. This is ideal for learning, and as a good starting point for real-world scenarios.
  • browser: Creates a browser script that checks if a websites successfully loaded, looks for elements on the screen, and takes a screenshot. Similar to the protocol option, this is ideal for learning, and a good starting point for creating browser tests.
  • An absolute or a relative path to a local file, such as ./my-template.js or /path/to/my-template.js to use a custom template. k6 uses Go templating syntax to render the script.

To generate a script using a template, run:

k6 new --template protocol

--project-id

The --project-id allows you to specify a Grafana Cloud k6 project ID. The generated script is then configured to run in that project. To include the project ID in your custom template, use {{ .ProjectID }} as a placeholder, for example:

export default function () {
  console.log('Hello from project {{ .ProjectID }}!');
}

To use the project ID flag, run:

k6 new --project-id 12345

{{< admonition type="note" >}}

To run your test in a specific Grafana Cloud k6 project, you need a Grafana Cloud account with access to that project.

To learn more about Grafana Cloud k6, refer to Grafana Cloud k6 documentation.

{{< /admonition >}}