k6 Documentation

1. Project Overview & Quickstart (grafana/k6) Copy Chapter

Like unit testing, for performance

k6 is a modern load-testing tool, built on our years of experience in the performance and testing industries.
It's built to be powerful, extensible, and full-featured. The key design goal is to provide the best developer experience.

Its core features are:

• Configurable load generation. Even lower-end machines can simulate lots of traffic.
• Tests as code. Reuse scripts, modularize logic, version control, and integrate tests with your CI.
• A full-featured API. The scripting API is packed with features that help you simulate real application traffic.
• An embedded JavaScript engine. The performance of Go, the scripting familiarity of JavaScript.
• Multiple Protocol support. HTTP, WebSockets, gRPC, Browser, and more.
• Large extension ecosystem. You can extend k6 to support your needs. And many people have already shared their extensions with the community! Explore the available extensions.
• Flexible metrics storage and visualization. Summary statistics or granular metrics, exported to the service of your choice.
• Native integration with Grafana cloud. SaaS solution for test execution, metrics correlation, data analysis, and more.

This is what load testing looks like in the 21st century.

Example script Copy Chapter

import http from "k6/http";
import { check, sleep } from "k6";

// Test configuration
export const options = {
  thresholds: {
    // Assert that 99% of requests finish within 3000ms.
    http_req_duration: ["p(99) < 3000"],
  },
  // Ramp the number of virtual users up and down
  stages: [
    { duration: "30s", target: 15 },
    { duration: "1m", target: 15 },
    { duration: "20s", target: 0 },
  ],
};

// Simulated user behavior
export default function () {
  let res = http.get("https://quickpizza.grafana.com");
  // Validate response status
  check(res, { "status was 200": (r) => r.status == 200 });
  sleep(1);
}

You can run scripts like this on the CLI, or in your CI, or across a Kubernetes cluster.

[!NOTE]
Don't want to write code ?

We got you! Meet k6 Studio, a desktop application made to help you generate k6 scripts without having to touch code!

Documentation Copy Chapter

The docs cover all aspects of using k6. Some highlights include:

• Get Started. Install, run a test, inspect results.
• HTTP requests. Have your virtual users use HTTP methods.
  Or, check the other Protocols.
• Thresholds. Set goals for your test, and codify your SLOs.
• Options. Configure your load, duration, TLS certificates, and much, much more.
• Scenarios.
  Choose how to model your workload: open models, closed models, constant RPS, fixed iterations, and more.
• Results output. Study, filter, and export your test results.
• JavaScript API. Reference and examples of all k6 modules.
• Extensions. Extend k6 for new protocols and use cases.

These links barely scratch the surface! If you're looking for conceptual information, you can read about Test types, Test strategies, or one of the many informative Blog posts.

Roadmap Copy Chapter

Our team is dedicated to continuously improving and providing the best user experience possible. The public roadmap covers user-oriented features, UX improvements and JavaScript support that our team will focus on. Remember that timeframes and priorities may shift, but we believe it's important to share our vision.

We hope it provides a clear overview of our plans for future development. We welcome feedback, corrections, and suggestions via GitHub to make it more comprehensive, accessible, and valuable for the community.

It's worth mentioning that we consider upvotes (thumbs-up) to be one of the essential metrics for determining community needs. If you want to show us the importance of a feature, please give it a thumbs-up.

Contribute Copy Chapter

If you want to contribute or help with the development of k6, start by reading CONTRIBUTING.md. Before you start coding, it might be a good idea to first discuss your plans and implementation details with the k6 maintainers—especially when it comes to big changes and features. You can do this in the GitHub issue for the problem you're solving (create one if it doesn't exist).

Note: To disclose security issues, refer to SECURITY.md.

Support Copy Chapter

To get help, report bugs, suggest features, and discuss k6 with others, refer to SUPPORT.md.

License Copy Chapter

k6 is distributed under the AGPL-3.0 license.

2. Official Technical Reference & Guides (grafana/k6-docs) Copy Chapter

k6 Documentation

Welcome to the k6 docs!
This repo contains the source code of the k6 documentation.

Some key facts:

• Issues and contributions are always welcome!
• The docs are written in Markdown and built with Hugo.
• The Contributor's guide has meta-documentation about building locally, using special components and styling, deploying, troubleshooting, and more.
• We have a Code of conduct.
• We follow the Grafana Style Guide, and you can find more information about it in the Writers' Toolkit.

Contributing Copy Chapter

Don't feel shy about contributing! All input is welcome. No fix is too trivial.

If something confuses you or feels lacking about the docs, make an issue.
If you find something that you think you can fix, please go ahead. You don't need to ask permission.

Markdown files for the documentation are located in the docs/sources/ folder, with sub-folders for each k6 version. The URL structure is generated based on the folder structure and file names.

For small changes and spelling fixes, the GitHub UI is the most convenient way to contribute.
For larger contributions, consider running the project locally to see how the changes look like before making a pull request.

The following docs cover the different stages of the writing workflow:

• Local development. For any large changes, being able to see a preview of the site can help make sure things are rendered correctly, and spot any issues before they're deployed to production.
• Writers' Toolkit. Learn more about the Grafana writing style guide, front matter properties, how to upload and add images, and much more.
• Preview and deploy. Changes made to the files inside of docs/sources are automatically deployed to production once they're merged to the main branch.

For more details, refer to the CONTRIBUTING section.

Local development Copy Chapter

Before you begin Copy Section

To build the k6 docs in your machine, you'll need:

• Docker or Podman

If you're using Docker, make sure you have the Docker Desktop application running.

Build and preview Copy Section

Clone the repository to your machine:

git clone https://github.com/grafana/k6-docs.git

Run npm start:

npm start

You should see an output similar to this when the site finishes building:

View documentation locally:
                             http://localhost:3002/docs/k6/

                                                           Press Ctrl+C to stop the server

Go to http://localhost:3002/docs/k6/, and you should be able to see a preview of the docs.