Testing guides on Grafana Labs

Load test types

Mon, 21 Sep 2026 15:16:28 +0000

Load test types

Many things can go wrong when a system is under load. The system must run numerous operations simultaneously and respond to different requests from a variable number of users. To prepare for these performance risks, teams use load testing.

But a good load-testing strategy requires more than just executing a single script. Different patterns of traffic create different risk profiles for the application. For comprehensive preparation, teams must test the system against different test types.

Different tests for different goals

Start with smoke tests, then progress to higher loads and longer durations.

The main types are as follows. Each type has its own article outlining its essential concepts.

Smoke tests validate that your script works and that the system performs adequately under minimal load.
Average-load test assess how your system performs under expected normal conditions.
Stress tests assess how a system performs at its limits when load exceeds the expected average.
Soak tests assess the reliability and performance of your system over extended periods.
Spike tests validate the behavior and survival of your system in cases of sudden, short, and massive increases in activity.
Breakpoint tests gradually increase load to identify the capacity limits of the system.

Note
In k6 scripts, configure the load configuration using options or scenarios. This separates workload configuration from iteration logic.

Test-type cheat sheet

The following table provides some broad comparisons.

Type	VUs/Throughput	Duration	When?
Smoke	Low	Short (seconds or minutes)	When the relevant system or application code changes. It checks functional logic, baseline metrics, and deviations
Load	Average production	Mid (5-60 minutes)	Often to check system maintains performance with average use
Stress	High (above average)	Mid (5-60 minutes)	When system may receive above-average loads to check how it manages
Soak	Average	Long (hours)	After changes to check system under prolonged continuous use
Spike	Very high	Short (a few minutes)	When the system prepares for seasonal events or receives frequent traffic peaks
Breakpoint	Increases until break	As long as necessary	A few times to find the upper limits of the system

General recommendations

When you write and run different test types in k6, consider the following.

Start with a smoke test

Start with a smoke test. Before beginning larger tests, validate that your scripts work as expected and that your system performs well with a few users.

After you know that the script works and the system responds correctly to minimal load, you can move on to average-load tests. From there, you can progress to more complex load patterns.

The specifics depend on your use case

Systems have different architectures and different user bases. As a result, the correct load testing strategy is highly dependent on the risk profile for your organization. Avoid thinking in absolutes.

For example, k6 can model load by either number of VUs or by number of iterations per second ( open vs. closed). When you design your test, consider which pattern makes sense for the type.

What’s more, no single test type eliminates all risk. To assess different failure modes of your system, incorporate multiple test types. The risk profile of your system determines what test types to emphasize:

Some systems are more at risk of longer use, in which case soaks should be prioritized.
Others are more at risk of intensive use, in which case stress tests should take precedence.

In any case, no single test can uncover all issues.

What’s more, the categories themselves are relative to use cases. A stress test for one application is an average-load test for another. Indeed, no consensus even exists about the names of these test types (each of the following topics provides alternative names).

Aim for simple designs and reproducible results

While the specifics are greatly context-dependent, what’s constant is that you want to make results that you can compare and interpret.

Stick to simple load patterns. For all test types, directions is enough: ramp-up, plateau, ramp-down.

Avoid “rollercoaster” series where load increases and decreases multiple times. These will waste resources and make it hard to isolate issues.

Automated performance testing

Mon, 21 Sep 2026 15:16:28 +0000

Automated performance testing

Performance testing automation is about establishing a repeatable and consistent process that checks reliability issues at different stages of the development and release cycle. For instance, you could run performance tests from CI/CD pipelines and nightly jobs, or manually trigger load tests and monitor their impact in real-time.

In performance testing, automation does not remove the need to run tests manually. It’s about planning performance tests as part of your Software Development Life Cycle (SDLC) for continuous performance testing.

This guide provides general recommendations to help you plan and define a strategy for running automated performance tests:

Which tests to automate?
Which environment to test?
What frequency and how to run tests?
How to analyze performance results?

Please note that this guide assumes you are familiar with k6 and already have performance tests. If you are new to performance testing or k6, we recommend looking at our get-started resources.

Before we dive in, let’s consider the “why” behind automation and how it unlocks the full benefits of your performance testing efforts.

Start your learning experience with Grafana Learning Paths

Grafana Learning Paths provide a clear, structured path that leads you from beginner concepts to advanced use cases. Learn about this Grafana feature on Establish a performance baseline with k6.

Start learning

Why automate performance tests

Whether it’s a website loading in under a second, API responses in milliseconds, or instantaneous fault responses, performance is critical as it directly impacts the end-user experience. However, an organizational challenge is that performance may often not receive the recognition of a feature or requirement.

Performance is still intangible in many organizations, which react only when bad things happen. Automation changes this approach - from reactive to proactive.

In performance testing, it’s crucial to establish routines to be consistent in our practices. Automation is necessary to create a performance testing habit, and boost some of its benefits, including:

Improve testing coverage, confidence, and maintenance: Automation creates a constant and iterative process for various types of testing. This continuous effort in performance testing leads to expanded test coverage, enhanced test maintenance, and increased confidence in testing outcomes.
Detect issues earlier: Automating performance tests as part of the software delivery process can ensure applications meet reliability goals while catching issues earlier in the SDLC.
Collaborate across teams: Automation prompts teams to outline a strategy and plan across the SDLC and departments. It fosters engineering leaders to advocate for reliability and implement shared practices.

Without automation, the lack of a shared framework often leads to isolated and sporadic activities. Automation helps drive continuous performance and reliability testing, introducing a more efficient and effective testing process.

More than CI/CD

Automation often refers to running tests with pass/fail conditions as part of the release process within CI/CD pipelines. However, not all performance tests are suited for CI/CD workflows, nor are they solely about providing a Pass/Fail (green/red) status and acting as a release gatekeeper.

Automation into CI/CD pipelines is an option, but it’s not the only method to schedule the execution of performance tests. When creating a performance testing plan, it’s important to remember that there are different ways to run performance tests in a frequent basis:

Cron and cron job runners.
Cloud testing tools, such as scheduling in Grafana Cloud k6.
Test management tools with automation capabilities.
Trigger manual tests. Include this as a step in your release checklist process.

Running tests only from CI/CD tools on software changes limits the objectives of our performance tests. A complete performance testing strategy can include CI/CD tests, cron-based tests, or even manual tests to address various testing purposes:

Determine the purpose of the tests

The first step in the process is reviewing your existing or planned tests and understanding each test’s purpose. Can the test serve additional purposes if executed regularly? Some common goals are:

Comparing current performance against an existing performance baseline.
Understanding variances over time in key performance metrics. Observing flat or changing trends.
Detecting regressions of new releases.
Testing Service Level Objectives (SLOs) on a regular basis.
Testing critical areas during the release process.
Setting quality gates in the CI/CD pipelines.

When considering a consistent and ongoing purpose for each test, you discover which tests to automate, any lacking functionality, and missing tests in your test suite. It also guides you in determining the best time to run each test and how.

Choose which tests to automate

Performance tests can generally be divided into two aspects:

Test scenario (test case): What is the test verifying?
Test workload (test load): How much traffic and which traffic pattern?

Your test suite should incorporate a diverse range of tests that can verify critical areas of your system using distinct load test types.

Any existing test that you wish to run on a frequent basis is a candidate for automation. Fundamentally, automation is about running tests frequently and consistently, whether that’s daily, weekly, or annually.

When designing your performance test suite for automation, consider two key points: start simple and modularize your tests.

Start simple and iterate: Your test suite, and consequently test coverage, will expand as the team learns and encounters reliability issues to investigate.
Modularize your test suite: In k6, you can separate the scenario and workload logic and reuse them across different tests. That simplifies the process of creating tests with various traffic patterns for different purposes. Modularization also allows reusing common logic across multiple tests.

When planning test coverage or automation, consider starting with tests that:

Verify the core functionality crucial to the product and business.
Evaluate the performance in scenarios with high traffic.
Track key performance metrics to observe their trends and compare against their baselines.
Validate reliability goals or SLOs with Pass/Fail criteria.

Model the scenarios and workload

Once one or multiple tests have been selected, you should determine the various types of traffic that need to be tested.

Let’s illustrate an example with two simple tests: one test to assess the performance of a GET endpoint and one test to verify a checkout process.

The next step is to identify the traffic the system under test (SUT) handles for these tests. In this case, we could utilize our analytics and monitoring tools to find the typical traffic patterns for the GET endpoint and checkout flow.

Depending on the type of traffic, we can create different kinds of tests:

Smoke: Test for script errors and verify SUT with minimal traffic.
Average-Load: Test for regular/normal traffic.
Stress: Test for maximum expected traffic.
Spike: Test for a surge of traffic.
Soak: Test for a prolonged period of traffic.

In our example, we decided on the following workload for the two scenarios:

Test scenario	Smoke	Average	Stress	Spike	Soak
GET endpoint	1 iteration	100 reqs/s - 3m	1500 reqs/s - 5m
Checkout process	3 iterations	50 VUs - 5m		200 VUs - 1m

We recommend always creating average-load tests for baseline comparisons and smoke tests to validate test script errors before executing larger tests.

In our example, we have tests that use the same test scenario with distinct workloads. This pattern is extremely common. In this case, the ability to reuse the scenario logic across tests simplifies both test creation and maintenance. A common pattern for organizing tests is prefixing them with the type of workload:

smoke-get-api.js: imports the common scenario and set 1 iteration.
load-get-api.js: imports the common scenario and set 100 reqs/s during 3m.
stress-get-api.js: imports the common scenario and set 1500 reqs/s during 3m.

To learn more about configuring workloads in k6, refer to Scenarios.

Decide the testing frequency for each environment

The next step is to decide which environment to test and its frequency. Each organization has different environments, and their purpose might also vary from one organization to another.

Here are some common environments found at organizations, and general guidelines of what kind of testing to use them for.

Development environment

This environment, whether the personal machine or its dedicated environment, might not include all the components of the system. It is commonly used for preliminary testing before deploying the application to a more comprehensive environment.

This environment is great for verifying the basic functionality of our tests by running smoke tests.

In this type of environment, debugging and building our performance tests is more common than any type of automation. However, if your project structure permits, you can also schedule the execution of smoke tests on project changes.

QA environment

This environment often deploys the entire application but with minimal infrastructure resources. It’s like a low-scale staging environment that all teams can use to test functional aspects and find regressions for new features.

Given the infrastructure does not closely match the production environment, this type of QA environment is unsuitable for assessing the performance and scalability of the application.

However, validating the functional aspects of our testing with smoke tests can help to catch errors earlier in this environment. Additionally, it verifies that the same script can run in larger load tests later.

Run all the available smoke tests: end-to-end, integration, and unit test types. Schedule these tests as part of the suite of automated tests executed in the CI flow.

Pre-release and ephemeral environments

These environments are available to test upcoming releases, with each organization using them differently as part of their unique release process.

As a general rule on pre-release environments, we should run our larger tests with quality gates, Pass/Fail criteria that validate SLOs or reliability goals. In k6, you can do that by using Thresholds in options as follows:

export const options = {
  thresholds: {
    // http errors should be less than 1%
    'http_req_failed': ['rate<0.01'],
    // 90% of requests should be below 600ms
    'http_req_duration': ['p(90)<600'],
    // 95% of requests tagged as static content should be below 200ms
    'http_req_duration{type:staticContent}': ['p(99)<250'],
    // the error rate of my custom metric should be below 5%
    'my_custom_metric': ['rate<0.05'],
  },
};

However, it can be challenging to effectively assess all reliability goals. Frequently, you’ll encounter “false positives” and “true negatives” when testing with distinct types of load.

For larger tests, verifying the release based “only” on a Pass/Fail status can create a false sense of security in your performance testing and release process.

We recommend keeping the pre-release environment available for a few hours or days to thoroughly test the entire system. Our recommendations include:

Allocating a period of one to several days for validating the release.
Executing all the existing average-load, stress, and spike tests.
Executing each test at least twice consecutively.
Scheduling all tests to run periodically, for instance, every 4 hours or 8 hours.

Staging/pre-production

In some cases, the staging environment acts like the “Pre-release” environment. If so, follow the strategy mentioned in the previous section.

The staging environment is always available and consistently updated with the latest changes. It’s generally suitable for assessing performance changes like performance trends, regressions, or improvements.

In this case, we should choose the tests that assess key performance indicators and schedule them for consistent execution to collect metrics over a period. Start by selecting a few tests and scheduling their runs two to three times per week.

Like in the pre-release environment, we suggest executing each test at least twice consecutively, allowing us to ignore unreliable tests.

As we aim to find performance changes, consider scaling the workload of the test according to the staging infrastructure, which often does not match the scale of the production environment.

Production

Typically, the previous testing environments do not perfectly mirror the production environment, with differences in test data, infrastructure resources, and scalability policies.

Testing in production provides real-world insights that cannot be achieved in other environments. However, production testing requires a careful approach to handling and storing test data in production and avoiding impacting real users.

A low-risk common practice is to utilize smoke tests for synthetic testing, also called synthetic monitoring. Testing production with minimal load is safe. Schedule smoke tests every five minutes, establishing Pass/Fail test conditions and an effective alerting mechanism. For instance, if six consecutive test runs fail, send an alert.

If release strategies like Blue/Green or Canary deployments are in place, run load tests against the Green or new version to validate the release. It’s an ideal moment to see how SLOs behave in production.

Also, consider scheduling nightly tests or when the system handles less traffic. The goal is not to stress the system, but to consistently gather performance results to compare changes and analyze performance trends. For instance, schedule tests with half of the average traffic level on a weekly basis.

Example plan

Test	Deployment Env.	Type	Workload	Automation	Frequency
Checkout process	QA	Smoke	1 iteration	CI flow	Branch changes
Checkout process	Pre-release	Average	50 VUs - 5m	Scheduled during QA/Pre-release period	3 times per day during pre-release period
Checkout process	Pre-release	Spike	200 VUs - 1m	Scheduled during QA/Pre-release period	3 times per day during pre-release period
Checkout process	Staging	Average	50 VUs - 5m	Schedule	2 times per week

GET endpoint	QA	Smoke	1 iteration	CI flow	Branch changes
GET endpoint	Pre-release	Average	100 reqs/s - 3m	Scheduled during QA/Pre-release period	3 times per day during pre-release period
GET endpoint	Pre-release	Stress	1500 reqs/s - 5m	Scheduled during QA/Pre-release period	3 times per day during pre-release period
GET endpoint	Staging	Average	100 reqs/s - 3m	Schedule	2 times per week
GET endpoint	Production	50% Avg.	50 reqs/s - 3m	Schedule on minimal traffic	Weekly

Plan the result analysis process

Following the previous steps, you should now have an initial performance testing plan. Now, let’s see how we can analyze and interpret performance results.

The first step is learning what options you have for outputting performance results. If you’re using k6, there are a few options you can choose from. You can review those options and the k6 metrics to decide on a long-term solution to analyze the results of your test automation plan.

Here are some questions to consider when creating your result analysis process.

How to store your performance results

In k6, you can get the aggregated results at the end of a test, or time series metrics in real-time. Both options allow you to customize the output.

The process we recommend is:

Select a storage backend.
Understand how it stores your test data and its particular capabilities.
Learn how to query and visualize results and any limitations.
Establish a policy for deleting old test results, and make sure to retain key performance results for future comparisons like baseline performance data.
Test the solution and decide on a long-term storage choice to avoid frequent changes to this critical component.

Which key performance metrics will be your focus

Think about the goal of each particular test, and make sure you track the metrics that depend on your test goals.

k6 provides built-in metrics that aggregate all the interactions against the SUT. You can also utilize tags and custom metrics to categorize and filter results for one interaction or particular types.

Consider defining your own performance criteria and their visualization. For instance, set different colors for what is good, acceptable, slightly concerning, or wrong so you can quickly visualize if a particular set of performance results are ok.

Think about performance changes. Is there any particular metric to compare changes or track its trend over time? Most of the test visualization choices focus on the results of individual test runs. Consider implementing a way to visualize the result of a critical performance metric over time so you can identify any changes and trends.

How often will you analyze results

Consider creating dashboards and custom notifications that can quickly provide an overview of the latest results of any automated tests. These dashboards are the first line to indicate issues requiring investigation.

Additionally, we recommend setting up alerts for important issues. Think about priority and non-priority levels and follow-up actions. Consider these tips to design alerts.

Correlate testing and observability data

Last but not least, set up proper instrumentation of the SUT and understand the monitoring and observability in place for system and application data.

Performance testing results can highlight poor performance, such as slow responses. However, it does not show what happens internally on the SUT, such as a slow SQL query or CPU and memory saturation.

To bridge the gap, work out a way to correlate testing results with how you instrument your infrastructure and application code. For instance, connecting or building custom dashboards with test results or using trace data from your tests.

Continuous testing helps detect issues and performance degradations, whether from test results or system data. Proper observability will help to find the root cause.

Example plan

As we finalize our planning, we can organize our test plan considering how often tests are run, the options to analyze their results, and follow-up actions. For example:

Deployment Env.	Test type	Frequency	Alerts	Test overview	Action
QA	Smoke tests	CI on Branch changes	CI		Fix broken tests
Pre-release	All performance tests except smoke tests	2 or 3 times daily during the QA/pre-release period			Validate the release after assessing performance results
Staging	Baseline performance tests	Schedule 2 times per week	Only for critical issues	Custom dashboard	Oversee test results
Production	Baseline performance tests	Weekly schedule	Priority and Non-priority issues	Custom dashboards and notifications	Oversee test results
Production	Synthetic tests	Hourly schedule	Custom alerts		Respond to alerts

Considerations

Start simple and then iterate

When starting your performance test plan or automation, it is common to think about having a few dozen scenarios to test. Start small to avoid planning paralysis.

We recommend beginning with a few distinct tests across testing environments.

Over time, you can add more tests, and your performance test suite will gradually increase its test coverage.

Focus on proving your test automation plan and solution across the software release process. A successful implementation will pave the way for collaborating with other teams and promoting the value of continuous performance testing.

Test consistency is critical

One of the primary objectives of continuous performance testing is assessing changes in the key metrics that define reliability and performance goals. To achieve this, we need to compare the value of these metrics between test runs over a period.

It’s critical to compare test run results of the same test. Otherwise, you’re comparing apples with oranges. Compare identical test runs, the same workload, running the same scenario with the same test data against the same environment.

Make sure not to introduce variance between test runs. If changes are necessary, rename or create a new test and start comparing test results from scratch.

Additionally, we recommend scheduling the execution of the same test twice and almost consecutively. This collects one extra test run result for better comparison and allows us to ignore a potentially unreliable test.

Establish how to stop automated and manual tests

Certain performance tests, especially those involving heavy-load tests, might cause outages. Automating the execution of risky tests without supervision may not be desirable, but that doesn’t mean you should avoid them.

These tests require controlled test execution and real-time analysis of test results, allowing them to be stopped before the system becomes unresponsive.

Similarly, you might want to stop a test when the system begins to produce a flood of errors. When a system becomes completely overloaded, continuing the test execution often doesn’t provide more meaningful insights and merely consumes resources.

To stop a k6 test, learn how to use the abortOnFail threshold option or integrate with the k6 CLI or Grafana Cloud k6.

Complement automation with a repeatable QA process

We mentioned this at the beginning of the guide: automation in performance testing is about establishing a repeatable and consistent testing process.

You should also plan the frequency of tests that are manually triggered and require supervision of the system during their execution. To ensure these different cases are consistently tested, set reminders and document them as part of the QA process and release checklists. Common examples are:

Running soak tests quarterly.
Running heavy-stress tests 2 months before an important seasonal event.
Running heavy-load tests for major releases in a pre-release environment.

Quality gates in CI/CD may result in false assurance

Quality gates in performance tests are often defined as Pass/Fail criteria that verify the release meets its reliability goals.

However, setting up reliable quality gates is challenging when testing thousands or millions of interactions. The test script, the SLO for that particular environment, and the Pass/Fail criteria could easily be wrong.

Assume reliability checks may have false negatives (and vice versa); ensure performance tests don’t block releases wrongly.

Unless your verification process is mature, do not rely entirely on Pass/Fail results to guarantee the reliability of releases. If unsure, start utilizing Pass/Fail results to warn about possible issues for deeper investigation, and continuously tweak the criteria until becoming confident.

Moreover, note that the load test duration often takes between 3 to 15 minutes or more; thus, introducing performance testing into CI/CD significantly increases the time of the release process. This is another reason we advise not to run larger tests in pipelines meant for automatic deployment. Instead, plan one or more days for performance testing pre-releases in a dedicated environment.

API load testing

Mon, 21 Sep 2026 15:16:28 +0000

API load testing

An API load test generally starts with small loads on isolated components. As your testing matures, your strategy can consider how to test the API more completely. In this process, you’ll test your API with more requests, longer durations, and on a wider test scope—from isolated components to complete end-to-end workflows.

When you design your API tests, first consider why you want to test the API at all:

What flows or components do you want to test?
How will you run the test?
What criteria determine acceptable performance?

Once you can answer these questions, your API testing strategy will likely follow something like this procedure:

Script the test. Write user flows, parameterize test data, and group URLs.
Assert performance and correctness. Use Checks to assert system responses and use Thresholds to ensure that the system performs within your SLOs.
Model and generate load. Choose the executors to correctly model the workload that’s appropriate to your test goals. Make sure the load generators are located where they should be.
Iterate over your test suite. Over time, you’ll be able to reuse script logic (e.g., a user log-in flow or a throughput configuration). You’ll also be able to run tests with a wider scope or as a part of your automated testing suite.

The following sections provide specific explanations and examples of the steps in this process.

Identify the components to test

Before you start testing, identify the components you want to test. Do you want to test a single endpoint or an entire flow?

The following script uses the k6 HTTP module to test a single endpoint.

import http from 'k6/http';

export default function () {
  const payload = JSON.stringify({
    name: 'lorem',
    surname: 'ipsum',
  });
  const headers = { 'Content-Type': 'application/json' };
  http.post('https://quickpizza.grafana.com/api/post', payload, { headers });
}

This is a minimal test, with one call to one component. Generally, your test suite will progress from scripts like this to more complex and complete workflows. In this process, your test suite will advance through the testing pyramid as follows:

Testing an isolated API. Hammering an API endpoint like ab to test the baseline performance, breaking point, or availability. If a component doesn’t meet performance requirements, it is a bottleneck. Generally, the load is set in requests per second.
Testing integrated APIs. Testing one or multiple APIs that interact with other internal or external APIs. Your focus might be on testing one system or various.
Testing end-to-end API flows. Simulating realistic interactions between APIs to test the system as a whole. The focus is often on frequent and critical user scenarios.

Your load test suite should include a wide range of tests. But, when you start, start small and simple, testing individual APIs and uncomplicated integration tests.

Determined the reason for the test

Before you configure test load, you should know what traffic patterns you want to test the API for. A load test typically aims to do one of two things:

Validate reliability under expected traffic
Discover problems and system limits under unusual traffic.

For example, your team might create one set of tests for frequent user flows on average traffic, and another set to find breaking points in the API. Even if the test logic stays the same, its load might change.

The test goal determines the test type, which in turn determines the test load. Consider the following test types, which correspond to different goals load profiles:

Smoke test. Verify the system functions with minimal load.
“Average” load test. Discover how the system functions with typical traffic.
Stress test. Discover how the system functions with the load of peak traffic.
Spike test. Discover how the system functions with sudden and massive increases in traffic.
Breakpoint test. Progressively ramp traffic to discover system breaking points.
Soak test. Discover whether or when the system degrades under loads of longer duration.

The test types that you choose inform how you plan and structure your test. But each application, organization, and testing project differs. Our recommendation is always:

“Start simple and test frequently. Iterate and grow the test suite”.

Once you’ve decided on the load profile, you can schedule it with k6 options.

Model the workload

To configure the workload, use test options. The test load configures the traffic generated by the test. k6 provides two broad ways to model load:

Through virtual users (VUs), to simulate concurrent users
Through requests per second, to simulate raw, real-world throughput

Note
Generally, your load tests should add sleep time. Sleep time helps control the load generator and better simulates the traffic patterns of human users.

However, when it comes to API load tests, these recommendations about sleep come with a few qualifications. If testing an isolated component, you might care only about performance under a pre-determined throughput. But, even in this case, sleep can help you avoid overworking the load generator, and including a few randomized milliseconds of sleep can avoid accidental concurrency.

When testing the API against normal, human-run workflows, add sleep as in a normal test.

Virtual users

When you model load according to VUs, the basic load options are:

You can define these options in the test script. In the following test, 50 concurrent users continuously run the default flow for 30 seconds.

import http from 'k6/http';

export const options = {
  vus: 50,
  duration: '30s',
};

export default function () {
  const payload = JSON.stringify({
    name: 'lorem',
    surname: 'ipsum',
  });
  const headers = { 'Content-Type': 'application/json' };
  http.post('https://quickpizza.grafana.com/api/post', payload, { headers });
}

Request rate

When analyzing API endpoint performance, the load is generally reported by request rate—either requests per second or per minute.

To configure workloads according to a target request rate, use the constant arrival rate executor.

constant-arrival-rate sets a constant rate of iterations that execute the script function. Each iteration can generate one or multiple requests.

To reach a request-rate target (RequestsRate), follow this approach:

Set the rate frequency to the time unit of the target. Per second or per minute.
Get the number of requests per iteration (RequestsPerIteration).
Set the iteration rate to the requests per second target divided by the number of requests per iteration. rate = RequestsRate ÷ RequestsPerIteration.

To reach target of 50 reqs/s with the previous example:

Set the timeUnit options to 1s.
The number of requests per iteration is 1.
Set the rate option to 50/1 (so it equals 50).

import http from 'k6/http';

export const options = {
  scenarios: {
    my_scenario1: {
      executor: 'constant-arrival-rate',
      duration: '30s', // total duration
      preAllocatedVUs: 50, // to allocate runtime resources     preAll

      rate: 50, // number of constant iterations given `timeUnit`
      timeUnit: '1s',
    },
  },
};

export default function () {
  const payload = JSON.stringify({
    name: 'lorem',
    surname: 'ipsum',
  });
  const headers = { 'Content-Type': 'application/json' };
  http.post('https://quickpizza.grafana.com/api/post', payload, { headers });
}

This test outputs the total number of HTTP requests and RPS on the http_reqs metric:

# the reported value is close to the 50 RPS target
 http_reqs......................: 1501   49.84156/s

# the iteration rate is the same as rps, because each iteration runs only one request
iterations.....................: 1501   49.84156/s

For a more extensive example, refer to this post about generating a constant request rate

With the constant-arrival-rate executor, load is constant through the test. To ramp the request rate up or down, use the ramping-arrival-rate executor instead.

For all ways to model the load in k6, refer to Scenarios.

Verify functionality with Checks

Traditionally, performance tests care most about:

Latency, how fast the system responds
Availability, how often the system returns errors.

The http_req_duration metric reports the latency, and http_req_failed reports the error rate for HTTP requests. The previous test run provided the following results:

http_req_duration..............: avg=106.14ms min=102.54ms med=104.66ms max=198.93ms p(90)=113.78ms p(95)=114.58ms
    { expected_response:true }...: avg=106.14ms min=102.54ms med=104.66ms max=198.93ms p(90)=113.78ms p(95)=114.58ms
http_req_failed................: 0.00% ✓ 0    ✗ 1501

Your test analysis might need to go beyond what’s available with default metrics. For more meaningful results analysis, you might also want to validate functionalities and report errors.

Some application failures happen only under certain load conditions, such as high traffic. These errors are hard to find. To find the cause of failures more quickly, instrument your APIs and verify that requests get the expected responses. To verify application logic in k6, you can use Checks.

Checks validate conditions during the test execution. For example, you can use checks verify and track API responses. With checks, you can confirm expected API responses, such as the HTTP status or any returned data.

Our script now verifies the HTTP response status, headers, and payload.

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

export const options = {
  scenarios: {
    my_scenario1: {
      executor: 'constant-arrival-rate',
      duration: '30s', // total duration
      preAllocatedVUs: 50, // to allocate runtime resources

      rate: 50, // number of constant iterations given `timeUnit`
      timeUnit: '1s',
    },
  },
};

export default function () {
  const payload = JSON.stringify({
    name: 'lorem',
    surname: 'ipsum',
  });
  const headers = { 'Content-Type': 'application/json' };
  const res = http.post('https://quickpizza.grafana.com/api/post', payload, { headers });

  check(res, {
    'Post status is 200': (r) => res.status === 200,
    'Post Content-Type header': (r) => res.headers['Content-Type'] === 'application/json',
    'Post response name': (r) => res.status === 200 && res.json().name === 'lorem',
  });
}

In this snippet, all checks succeeded:

my_scenario1 ✓ [======================================] 00/50 VUs  30s  50.00 iters/s
     ✓ Post status is 200
     ✓ Post Content-Type header
     ✓ Post response name

After the load increased to 300 requests per second, the results returned 8811 successful requests and 7 failures:

my_scenario1 ✓ [======================================] 000/300 VUs  30s  300.00 iters/s
     ✗ Post status is 200
      ↳  99% — ✓ 8811 / ✗ 7
     ✗ Post Content-Type header
      ↳  99% — ✓ 8811 / ✗ 7
     ✗ Post response name
      ↳  99% — ✓ 8811 / ✗ 7

By default, a failed check doesn’t fail or abort the test. In this regard, a check differs from how assertions work for other types of testing. A load test can run thousands or millions of script iterations, each with dozens of assertions.

Some rate of failure is acceptable, as determined by your SLO’s “number of nines” or your organization’s error budget.

Test your reliability goals with Thresholds

Every test should have a goal. Engineering organizations set their reliability goals using Service Level Objectives (SLOs) to validate availability, performance, or any performance requirements.

SLOs may be defined at distinct scopes, such as on the level of an infrastructure component, of an API, or of the entire application. Some example SLOs could be:

That 99% of APIs returning product information respond in less than 600ms.
That 99.99% of failed log-in requests respond in less than 1000ms.

Design your load tests with pass/fail criteria to validate SLOs, reliability goals, or other important metrics. To ensure your system achieves its SLOs, test them frequently, both in pre-production and production environments.

In k6, you can use Thresholds to set the test pass/fail criteria. This script codifies two SLOs in the thresholds object, one about error rate (availability) and one about request duration (latency).

export const options = {
  thresholds: {
    http_req_failed: ['rate<0.01'], // http errors should be less than 1%
    http_req_duration: ['p(95)<200'], // 95% of requests should be below 200ms
  },
  scenarios: {
    my_scenario1: {
      executor: 'constant-arrival-rate',
      duration: '30s', // total duration
      preAllocatedVUs: 50, // to allocate runtime resources

      rate: 50, // number of constant iterations given `timeUnit`
      timeUnit: '1s',
    },
  },
};

When the test fails, the k6 CLI returns a non-zero exit code—a necessary condition for test automation. As an example of a failed test, here’s the output for a test with a threshold that 95 percent of requests finish in under 50ms, http_req_duration:["p(95)<50"]:

  █ THRESHOLDS

    http_req_duration
    ✗ 'p(95)<200' p(95)=348.21ms

    http_req_failed
    ✓ 'rate<0.01' rate=0.05%


  █ TOTAL RESULTS

    checks_total.......................: 90      13.122179/s
    checks_succeeded...................: 100.00% 90 out of 90
    checks_failed......................: 0.00%   0 out of 90

    ✓ Post status is 200
    ✓ Post Content-Type header
    ✓ Post response name

    HTTP
    http_req_duration..................: avg=140.36ms   min=119.08ms med=140.96ms max=154.63ms p(90)=146.88ms p(95)=148.21ms
      { expected_response:true }.......: avg=140.36ms   min=119.08ms med=140.96ms max=154.63ms p(90)=146.88ms p(95)=148.21ms
    http_req_failed....................: 0.00%  0 out of 45
    http_reqs..........................: 45     6.56109/s

    EXECUTION
    iteration_duration.................: avg=152.38ms   min=119.37ms med=141.27ms max=684.62ms p(90)=147.11ms p(95)=148.39ms
    iterations.........................: 45     6.56109/s
    vus................................: 1      min=1       max=1
    vus_max............................: 1      min=1       max=1

    NETWORK
    data_received......................: 519 kB 76 kB/s
    data_sent..........................: 4.9 kB 718 B/s

running (0m30.1s), 00/50 VUs, 1501 complete and 0 interrupted iterations
my_scenario1 ✓ [======================================] 00/50 VUs  30s  50.00 iters/s
ERRO[0030] some thresholds have failed

Scripting considerations

If you have scripted tests before, implementing k6 scripts should seem familiar. k6 tests are written in JavaScript, and the design of the k6 API has similarities with other testing frameworks.

But, unlike other tests, load tests run their scripts hundreds, thousands, or millions of times. The presence of load creates a few specific concerns. When you load test APIs with k6, consider the following aspects of your script design.

Data parameterization

Data parameterization happens when you replace hard-coded test data with dynamic values. Parameterization makes it easier to manage a load test with varied users and API calls. A common case for parameterization happens when you want to use different userID and password values for each virtual user or iteration.

For example, consider a JSON file with a list of user info such as:

{
  "users": [
    { "username": "lorem", "surname": "ipsum" },
    { "username": "dolorem", "surname": "ipsum" }
  ]
}

You can parameterize the users with the SharedArray object as follows:

import { check } from 'k6';
import http from 'k6/http';
import { SharedArray } from 'k6/data';

const users = new SharedArray('users.json', function () {
  return JSON.parse(open('./users.json')).users;
});

export const options = {};

export default function () {
  // now, user data is not the same for all the iterations
  const user = users[Math.floor(Math.random() * users.length)];
  const payload = JSON.stringify({
    name: user.username,
    surname: user.surname,
  });

  const headers = { 'Content-Type': 'application/json' };
  const res = http.post('https://quickpizza.grafana.com/api/post', payload, {
    headers,
  });

  check(res, {
    'Post status is 200': (r) => res.status === 200,
    'Post Content-Type header': (r) => res.headers['Content-Type'] === 'application/json',
    'Post response name': (r) => res.status === 200 && res.json().name === user.username,
  });
}

To read more about data parameterization, check out the parameterization examples and Execution context variables.

Error handling and acceptance of failures

Remember to implement error handling in the test logic. Under sufficiently heavy load, the SUT fails and starts to respond with errors. Though a test might be designed to induce failures, sometimes we focus on only the best-case scenario and forget the importance of accounting for errors.

The test script must handle API errors to avoid runtime exceptions and to ensure that it tests how the SUT behaves under saturation according to the test goals. For example, we could extend our script to do some operation that depends on the result of the previous request:

import { check } from 'k6';
import http from 'k6/http';
import { SharedArray } from 'k6/data';

const users = new SharedArray('users.json', function () {
  return JSON.parse(open('./users.json')).users;
});

export const options = {};

export default function () {
  const user = users[Math.floor(Math.random() * users.length)];
  const payload = JSON.stringify({
    name: user.username,
    surname: user.surname,
  });
  const headers = { 'Content-Type': 'application/json' };
  const res = http.post('https://quickpizza.grafana.com/api/post', payload, {
    headers,
  });

  check(res, {
    'Post status is 200': (r) => res.status === 200,
    'Post Content-Type header': (r) => res.headers['Content-Type'] === 'application/json',
    'Post response name': (r) => res.status === 200 && res.json().name === user.username,
  });

  if (res.status === 200) {
    // enters only successful responses
    // otherwise, it triggers an exception
    const delPayload = JSON.stringify({ name: res.json().name });
    http.patch('https://quickpizza.grafana.com/api/patch', delPayload, { headers });
  }
}

Test reuse and modularization

Load testing can be vast in scope, and it may involve different types of tests. Generally, teams start with simple or critical load tests and continue adding tests for new use cases, user flows, traffic patterns, features, systems, etc.

In this process, load testing suites grow over time. To minimize repetitive work, try to reuse test scripts early and to modularize test functions and logic. If you script common scenarios in reusable modules, it’s easier to create different types of load tests. The process of creating a new load test goes like this:

Create a new test file.
Configure the specific load and other options.
Import the scenario.

As your testing matures, consider creating tests that combine multiple scenarios to simulate more diverse traffic.

Dynamic URLs for one endpoint

By default, when you access the same API endpoint with different URLs―for example, http://example.com/posts/${id}―k6 reports the endpoint results separately. This may create an unnecessary amount of metrics.

To group the results of the endpoint, use URL grouping.

Load generator locations

When you plan the test, consider the locations of your load generators, the machines that run the test. Sometimes, running the test from a specific location is a test requirement. Other times, you might just choose the location based on convenience or practicality. Either way, when you set the location of the load generator, keep the following in mind:

Required locations. To compare performance or ensure accurate results, some load tests need to measure the latency from specific locations. These tests launch the load generators from locations that match their user’s region.
Optional locations. Other tests try to measure against a performance baseline—how the system performance changes from a particular performance status or time. To avoid skewed latency results, ensure that the location of the load generator is constant across test runs, and avoid running the tests from locations that are too close to the SUT.

Internal APIs

End-to-end API tests try to replicate real-world user flows, which access public APIs from external systems. Other APIs are internal and unreachable from outside. The need to run internal tests is common when testing API integrations and isolated endpoints.

If the API is in an internal or restricted environment, you can use k6 to test it in a few different ways:

Run the test from your private network using the k6 run command or the Kubernetes operator. Optionally, store the test results in k6 Cloud or other external services.
For cloud tests:
- Open your firewall for cloud test traffic.
- Run the cloud test from your Kubernetes clusters.

Supplementary tools

You might want to use k6 in conjunction with other API tools.

Integrate with API tools

The tooling around REST APIs is vast, but there’s not much focus on performance testing. k6 provides a few converters to help you incorporate the wider API tooling ecosystem into your load tests:

Postman-to-k6 converter: to create a k6 test from a Postman collection.
Bash
```
postman-to-k6 collection.json -o k6-script.js
```
OpenAPI k6 generator: to create a k6 test from an Open API (formerly Swagger) definition.
Bash
```
openapi-generator-cli generate -i my-api-spec.json -g k6
```

These tools generate a k6 test that you can edit and run as usual:

k6 run k6-script.js

Depending on the test type, the converters could help you quickly create your first tests or help onboard new users to k6. Even so, we recommend you get familiar with the k6 Javascript API and script your own tests.

Using proxy recorders

Another option is to auto-generate a k6 test from a recorded session. These scripts might help you start building more complex end-to-end and integration tests.

The har-to-k6 converter creates the k6 test from a recorded session in HAR format which collects HTTP traffic.

har-to-k6 archive.tar -o k6-script.js

The generated k6 test can be edited and run as usual:

k6 run k6-script.js

To export a recorded session to HAR format, use a proxy recorder such as Fiddler proxy or GitLab HAR recorder.

As with the previous converters, the recorder can help prototype tests. Again, we recommend learning to write your test scripts.

Beyond HTTP APIs

Due to the popularity of the web and REST APIs, this guide has used the term focused on HTTP APIs. But APIs are not restricted to the HTTP protocol.

By default, k6 supports testing the following protocols:

import grpc from 'k6/net/grpc';
import { check, sleep } from 'k6';

const client = new grpc.Client();
client.load(null, 'quickpizza.proto');

export default () => {
  client.connect('grpc-quickpizza.grafana.com:443');

  const data = { ingredients: ['Tomatoes', 'Cheese'], dough: 'Thin' };
  const response = client.invoke('quickpizza.GRPC/RatePizza', data);

  check(response, {
    'status is OK': (r) => r && r.status === grpc.StatusOK,
  });

  client.close();
  sleep(1);
};

But modern software is not built only based on these protocols. Modern infrastructure and applications rely on other API protocols to provide new capabilities or improve their performance, throughput, and reliability.

To test the performance and capacity of these systems, the testing tool should be able to generate protocol-specific requests against their APIs.

If k6 doesn’t support a protocol you need, you can use (or create) extensions. The list of extensions is long:

Avro
ZeroMQ
Ethereum
STOMP
MLLP
NATS
and more.

Calculate concurrent users for load tests

Mon, 21 Sep 2026 15:16:28 +0000

Calculate concurrent users for load tests

When planning load tests, determining the right number of concurrent users is crucial for creating realistic test scenarios. This guide explains how to use Google Analytics data to calculate concurrent user numbers and design effective load tests.

Note
You can use any analytics tool that provides the same metrics to help you calculate the concurrent users you need for load testing.

Understanding concurrent users

Google Analytics tracks visitors (“Users”) and their activity periods (“Sessions”) on your site. During a session, users generate traffic through page loads or AJAX requests that your servers must handle. To create realistic load tests, you need to determine how many users are actively generating traffic at any given time.

The recommended formula for calculating your baseline of hourly concurrent users is:

An hour in seconds = 3600
Concurrent users  = Hourly sessions * Average session duration (in seconds) / 3600

Get the data from Google Analytics

To find the required metrics in Google Analytics:

Log in to your Google Analytics account.
Navigate to the Reporting tab.
Click Audience on the sidebar menu.
Click Overview.
Set your desired time period.
Click Hourly view in the line graph settings.

You should be able to view the session count and average session duration on the overview dashboard.

Note
These instructions might vary depending on which version of Google Analytics you’re using. If you’re using Google Analytics 4, you can find these metrics by selecting Explore and creating a Free form report.

Designing load tests

With the data in hand, it’s important to mention why you want to use the “Hourly” view.

Using hourly metrics rather than daily or monthly averages is crucial for accurate load testing. Daily averages can mask significant traffic variations that occur throughout the day. For example, an e-commerce site might see most of its traffic during business hours, with peaks during lunch breaks. Using daily averages would underestimate these crucial peak periods.

Additionally, hourly metrics help identify patterns in user behavior. A news site might see traffic spikes during morning commute hours and evening hours, while a restaurant booking service might peak during evening hours. Understanding these patterns through hourly data helps you design more realistic load tests that match your actual usage patterns.

Calculate peak traffic

Instead of using average traffic levels, base your load tests on peak traffic periods:

Identify peak hours in Google Analytics.
Calculate concurrent users during these peaks.
Add a margin to ensure you can handle higher traffic levels.

For example, if your site averages 0.08 concurrent sessions monthly but peaks at 7.2 concurrent sessions during high-traffic hours, you should test for at least this peak level.

Example calculation

As an example, for a website that has the following metrics:

2,591 monthly sessions
82 seconds per session

Applying the concurrent user formula, you can find the average concurrent users:

2,591 monthly sessions x 82 seconds per session / 3600 = 59.0172

// To convert monthly sessions to hourly sessions, you can divide the value by 720
59.0172 / 720 (30 days in November x 24h per day = 720) = 0.08 average concurrent users in November

But, if the same website has peak hours from 3 PM to 4 PM with different metrics:

990 sessions
92 seconds

In this case, applying the concurrent users formula leads to:

990 sessions x 92 seconds per session / 3600 = 25.3 average concurrent users

This example shows how peak traffic can reach a considerably higher value than the monthly average, in this case from 0.8 to 25.3 concurrent users, highlighting the importance of testing beyond average traffic levels.

Additional testing considerations

There are multiple scenarios where a different kind of test might give you a better insights on your system reliability. Consider implementing these testing strategies:

Spike tests before major events.
Regular load tests at peak traffic levels.
Tests that exceed your highest historical traffic by a safety margin.

These practices help ensure your system remains stable during unexpected traffic increases. Refer to Testing guides for more details about all of the different performance testing strategies.

Load testing websites

Mon, 21 Sep 2026 15:16:28 +0000

Load testing websites

This doc explains some key concepts about load testing websites, including:

The difference between backend and frontend performance testing
When to choose between protocol-based, browser-based, or hybrid scripts
Recommended practices about how to load test websites

All load tests try to simulate real user traffic to prevent failures, improve reliability, and release new code with confidence. But your approach to load testing must adapt to the type of application you want to test.

In this guide, learn about strategies to test websites, including specific recommendations for complex scenario scripting and test execution.

Load testing approaches

When you approach the load test, first consider the following perspectives:

Backend vs. frontend performance
Protocol-based, browser-based, or hybrid load testing
Component testing vs. end-to-end testing

Backend vs. frontend performance

Performance has a significant influence on the user experience of a website.

For example, when users want to visualize or interact with some information, they expect the website to react quickly.

To measure performance, testers often look at response times, which are affected by two main factors:

Frontend performance
Backend performance

Frontend performance

Frontend performance testing verifies application performance on the interface level, measuring round-trip metrics that consider how and when page elements appear on the screen. It’s concerned with the end-user experience of an application, usually involving a browser.

Frontend performance testing excels at identifying issues on a micro level but does not expose issues in the underlying architecture of a system.

Because it primarily measures a single user’s experience of the system, frontend performance testing tends to be easier to run on a small scale. Frontend performance testing has metrics that are distinct from backend performance testing. Frontend performance tests for things like:

Whether the pages of the application are optimized to render quickly on a user’s screen
How long it takes a user to interact with the UI elements of the application.

Some concerns when doing this type of performance testing are its dependency on fully integrated environments and the cost of scaling. You can test frontend performance only once the application code and infrastructure have been integrated with a user interface. Tools to automate frontend testing are also inherently more resource-intensive, so they can be costly to run at scale and are not suitable for high load tests.

Backend performance

Backend performance testing targets the underlying application servers to see how they behave under production-like conditions. When it comes to websites, while frontend performance involves how assets included in the page are rendered, backend performance focuses on how those assets are processed by the application servers, served to users, and downloaded by browsers.

Backend testing is broader in scope than frontend performance testing. API testing can be used to target specific components or integrated components, meaning that application teams have more flexibility and higher chances of finding performance issues earlier. Backend testing is less resource-intensive than frontend performance testing and is thus more suitable for generating high load.

Which one should you test?

It depends! Ideally, both.

Frontend testing tools are executed on the client side and are limited in scope: they do not provide enough information about backend components for fine-tuning beyond the user interface.

This limitation can lead to false confidence in overall application performance when the amount of traffic against an application increases. While the frontend component of response time remains more or less constant, the backend component of response time increases exponentially with the number of concurrent users:

Testing only frontend performance ignores a large part of the application, one more susceptible to increased failures and performance bottlenecks at higher levels of load.

Testing only backend performance, on the other hand, ignores “the first mile” of user experience and breadth. Backend testing involves messaging at the protocol level rather than interacting with page elements the way a real user would. It verifies the foundation of an application rather than the highest layer of it that a user ultimately sees.

Testing both frontend and backend performance leads to the best overall performance and user experience for your application. Ignoring one or the other exposes you to performance bottlenecks that significantly decrease a user’s satisfaction with your application.

However, if your testing is smaller in scope, you can choose to focus on either frontend or backend with the goal of eventually building a test suite that encompasses both.

Component testing vs. end-to-end testing

When you’re testing a web app, you may wonder whether how you structure your test scripts. Consider the following two methods.

Component testing

One way you could load test a web app is to load test its components. Maybe you know there are issues with a specific functionality due to previous production issues, or maybe you’d like to target components that are business-critical to reduce risk exposure.

In these cases, the type of test you write may:

be protocol-based
call only those API endpoints that are relevant
have smaller or no sleep/think time
be focused on eventually stress testing a component or service or finding its breaking point

Testing in this way is more flexible. With protocol testing, you can specify the endpoints or servers you’d like to hit, and narrow your test’s target that way. You can test specific functionalities while skipping others that come chronologically before it in a standard user flow. You can more finely control the type of traffic that is generated. If you’re recreating a specific mix of requests, you can script those requests and reproduce them in a repeatable manner.

Doing component testing for load may not always require that your script behave like an end user. In fact, it may be necessary to artificially inflate traffic to more quickly reproduce issues, or to deflate traffic to reduce the noise in the logs. By the nature of this type of testing, scripts don’t contain the full flow of a request that you would expect to see in production, so realism is not a priority.

End-to-end testing

You could also do end-to-end testing against a web app. End-to-end testing seeks to replicate real user behaviour and track its effects across the entire stack. When doing end-to-end testing, you might:

do protocol-level, browser-level, or hybrid load testing
replicate the actions in a typical user flow
think about the performance of the entire workflow as well as how long a request took to be processed by each component
write scripts that access the application the same way users would, such as by browsing to the homepage before finding their way to other parts of the website

This type of load testing is broader in scope than component testing, but shallower in terms of depth. With end-to-end testing, you get a better idea of the full user experience of the application as a whole. However, it can also be more complex to troubleshoot, as you have more components to monitor and more places to look for issues that are found.

End-to-end testing is based on real user behavior, so it’s often important that end-to-end test scripts also be realistic.

Protocol-based, browser-based, or hybrid load testing

The decision of whether to test the frontend, backend, or both will also affect the type of load testing you should carry out and the kind of scripts you should write.

Protocol-based load testing

Protocol-based load testing verifies the backend performance of an application by simulating the requests underlying user actions. For websites, this commonly involves HTTP requests that bypass the user interface of your application and are sent directly to a server or application component.

For example, a protocol-based load testing script might request all the resources on a webpage from the application servers, but those resources are merely downloaded. The response times reported by a purely protocol-based script do not include frontend metrics such as the time taken for images to render on a browser. The load is generated by simulating many requests sent to application servers.

While protocol-based load testing may seem to lend itself better to component testing, you can also do end-to-end website testing with protocol-level scripts.

Sample protocol-based test script

The following is an example of a protocol-based load testing script in k6 that fetches the homepage, along with resources embedded into the page.

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

export function Homepage() {
  const params = {
    'sec-ch-ua': '"Chromium";v="94", "Google Chrome";v="94", ";Not A Brand";v="99"',
    'accept-encoding': 'gzip, deflate, br',
    'accept-language': 'en-GB,en;q=0.9',
  };

  // 01. Go to the homepage
  let responses = http.batch([
    ['GET', 'https://mywebsite.com/', params],
    ['GET', 'https://mywebsite.com/style.min.css', params],
    ['GET', 'https://website.com/header.png', params],
    ['GET', 'https://website.com/polyfill.min.js', params],
  ]);
  check(responses, {
    'Homepage loaded': (r) => JSON.stringify(r).includes('Welcome to my site'),
  });

  sleep(4);

  // 02. View products
  responses = http.batch([
    ['GET', 'https://mywebsite.com/products', params],
    ['GET', 'https://mywebsite.com/style.css', params],
    ['GET', 'https://website.com/product1.jpg', params],
    ['GET', 'https://website.com/product2.jpg', params],
    ['GET', 'https://website.com/displaylist.js', params],
  ]);
  check(responses, {
    'Products loaded': (r) => JSON.stringify(r).includes('Add to Cart'),
  });

  sleep(1);
}

Recording browser traffic helps you prototype to test websites on the protocol level.

Browser-based load testing

Browser-based load testing verifies the frontend performance of an application by simulating real users using a browser to access your website.

For example, a browser-based load testing script might include instructions to navigate to a page, click on a button, and type out text on a form. Those user actions then trigger underlying requests on the protocol layer, but only user actions are scripted in browser-based testing.

Unlike protocol-based load testing, browser-based load testing scripts generate load by starting multiple instances of browsers and interacting with your application the way real users would. Testing at the browser level can also be the only option for testing Single-Page Applications where a lot of the application logic is executed by client-side scripts.

Scripting on the browser level usually requires the use of different tools from the ones used to test at the protocol level. However, k6 now has a module called k6 browser that allows the creation of browser-based test scripts alongside protocol-based ones.

Sample browser-based test script

The following is an example of a browser-based load testing script in k6 using the browser module on a dummy website. Instead of making an HTTP request, the script views the homepage, then looks for and clicks on a link to the product page.

import { browser } from 'k6/browser';

export default async function () {
  const page = await browser.newPage();

  // 01. Go to the homepage
  try {
    await page.goto('https://mywebsite.com');

    await page.waitForSelector('p[class="woocommerce-result-count"]"]');
    await page.screenshot({ path: 'screenshots/01_homepage.png' });

    await page.waitForTimeout(4000);

    // 02. View products
    const element = page.locator(
      'a[class="woocommerce-LoopProduct-link woocommerce-loop-product__link"]'
    );
    await element.click();
    await page.waitForSelector('button[name="add-to-cart"]');
    await page.screenshot({ path: 'screenshots/02_view-product.png' });

    await page.waitForTimeout(1000);
  } finally {
    await page.close();
  }
}

Tips for writing browser-level scripts

The following steps can help you get started with a browser-level test script.

Script user actions, not requests. Determine what a user might do for a particular task, and script interactions with elements on the browser level. For example, script what buttons the user clicks on.

Identify unique selectors. Once you have identified which page elements a user interacts with, use the Element Inspector for DevTools in your browser to find a unique, static, and simple way to identify each element. The script needs selectors to find the right element to interact with.

Use elements to verify responses. After every action, use locators to search for elements on the page that you would expect to find. This verification helps ensure that the script has reached the expected page.

Take screenshots for every action while debugging. One of the advantages of browser-based testing is the ability to take screenshots. After every user interaction the script simulates, use page.screenshot to save a visual image of what the script encountered for later troubleshooting.

Hybrid load testing

Hybrid load testing is a combination of protocol-based and browser-based load testing. While you can use two tools or two scripts to execute different types of load tests (one protocol-based and one browser-based), having both types of tests executed by the same script and the same tool is ideal. Aggregating results between different tools can be difficult at best and inconsistent at worst.

A best practice in hybrid load testing is to generate most of the load using the protocol-level test, and then to run a smaller number of the browser-level testing scripts. This approach:

reduces the number of load generators needed, since protocol-level testing requires fewer machines to generate the same load
measures backend and frontend performance in the same test execution
provides a single source of aggregated output at the end
reduces complexity in the creation and maintenance of scripts

Scripting considerations

When you script a test for a website, consider these recommendations.

Consider factors that affect script realism

Record your user journey. Using the browser recorder can facilitate initial test script creation by capturing all the embedded resources on webpages. Check out the Session Recording guide to learn more about how to auto-generate your load test from a user session.

Correlate data. Recordings often don’t take into account dynamic values that are generated anew each time a request is made. Go through the recorded requests and determine whether you need to extract values from previous responses and use parameters in subsequent requests. This practice ensures your VUs behave more like real users would.

Include or exclude static resources. Determine whether you should include or exclude static resources on pages such as images, JavaScript, etc. Consider including them if you want to measure overall user experience. Consider excluding them if you are using a Content Delivery Network (CDN) that is under a separate Service Level Agreement (SLA).

Exclude third-party requests. Don’t load test servers that you don’t own. Many applications make calls to third-party providers for authentication, social sharing, and marketing analytics. Disable these requests unless you have permission to include them in your tests.

Use concurrent requests. To mimic the way modern browsers download some requests in parallel, use batching.

Determine cache and cookie behaviour. k6 automatically resets cookies between iterations, but you can also change this behavior if maintaining cookies would be more realistic.

Use dynamic think time and pacing. Consider adding varying delays so you don’t artificially stagger a script with completely uniform delays.

Use test data. Real users typically don’t search for or submit the same data repeatedly. Consider adding a test data file for the script to iterate through.

Model test parameters and load profile after production. In k6, you can use test options to determine the exact shape and profile of your load test script. Select the appropriate executors for the job.

Create a reusable framework

Use tags and groups. Organizing requests by tagging and grouping them helps you consolidate like metrics and makes your test scripts more understandable by others.

Use scenarios. When combining protocol-based and browser-based tests, use scenarios to independently control their test parameters and executors.

Modularize scripts. Use modules to separate and organize functions for protocol-level testing and browser-level testing, and then use a test runner script to execute them. This approach means different scripts can be versioned and changed without affecting each other.

Integrate your tests into your CI pipeline. Adopting a “tests as code” approach enables you to tie your load tests more closely into your project’s existing CI/CD processes, helping you get the most value out of every test.

Test with thresholds in mind

Create thresholds for both types of testing. Some browser-level and protocol-level metrics cannot be combined because they don’t measure the same thing. Set thresholds for relevant metrics from both the browser-level script and the protocol-level one.

When possible, use hybrid load testing

Use protocol-based scripts to generate majority of the load. When writing the test scenario, use the protocol-based requests to simulate most of the traffic and use fewer VUs for the browser-based requests. Relying on the protocol-level traffic helps keep resource utilization on load generators down.

Execution considerations

When you run tests, consider the test environment and the load generator location.

Run your tests in the appropriate environment

Testing in pre-production environments and in production environments both add value.

Testing in pre-production environments (staging, test, system integration testing, user acceptance testing, and production replica environments) enables you to identify performance defects early, which can save a lot of time and effort (and reputation) later on. Running in test environments also means you can often afford to be more aggressive with your tests. However, it’s also more critical to get your load profiles right, and the test results you get may not necessarily apply to production.

Testing in production yields the most accurate results, but it’s also more risky. Often, testing production is the only feasible alternative. You can reduce the risk of impact to real customers while testing in production by using lower levels of load when running load tests during peak hours, schedule tests for off-peak hours, choosing load test types that are less risky, using techniques like synthetic monitoring that generate less traffic, using real user monitoring tools to get snapshots of user performance at load, and ensuring that your observability stack is working at peak efficiency.

Run tests where your customers are

The location of the load generator(s), where the traffic is coming from, can also have an impact on your test results. The question is: where are your end users located?

On-premises load testing can be ideal when testing early on in the development a website, or when there are machines that can be repurposed as load generators. However, testing entirely from within a corporate network may also yield false positives, in that response times reported are significantly lower than if the same application servers were accessed from across the country.

Load testing on the cloud is an essential part of the testing strategy for many public-facing websites. Using load generators on the cloud gives you access to test in different states and geographical countries, creating a mix of load generators proportional to your users’ locations. Cloud load generators are easier to provision and cheaper to maintain in the long run than on-premise ones. Load testing on the cloud can help you include the effects of network latency in your tests and yield results that are more realistic.

Recommendations

Here are some recommendations to help you plan, script, and execute your load tests for websites.

If you want to test the last-mile user experience of your website:

focus on frontend performance,
write browser-based test scripts,
and consider doing more realistic end-to-end tests of the user flow.

If you want to test the underlying infrastructure of your website:

focus on backend performance,
write protocol-based test scripts,
and consider starting with component testing and then gradually increasing the scope.

If your website is meant for internal or has limited access:

Use on-premise load generators located within the network that most of your users access the website from.

If your website is external and public-facing:

Use cloud load generators in the load zones where your users reside.

Test in pre-production environments when you can, but also consider testing in production in a limited capacity.

Load testing websites can be complex due to the number of viable testing approaches available, the scope for performance testing, and the potential effects of releasing undertested code. By following the recommendations we’ve put forward here, you can tailor your testing more closely to your objectives.

Performance testing gRPC services

Mon, 21 Sep 2026 15:16:28 +0000

Performance testing gRPC services

In this guide, you’ll learn the basics of gRPC and how to write a gRPC performance test using k6.

Before you begin

Install k6 v0.29 or higher.

What is gRPC

gRPC is a lightweight open source RPC framework. It was originally developed by Google, with 1.0 being released in August 2016.

In comparison to JSON, which is transmitted as human-readable text, gRPC is binary, making it both faster to transmit and more compact. For chatty, distributed systems, these improvements accumulate quickly, making the difference not only noticeable in benchmarks but also by the end-user.

API types

gRPC supports four different types of RPCs: unary, server streaming, client streaming, and bi-directional streaming. In reality, the messages are multiplexed using the same connection, but in the spirit of keeping things simple and approachable, this isn’t illustrated in the gRPC service model diagrams below.

Unary

Unary calls work the same way as a regular function call: a single request is sent to the server which in turn replies with a single response.

Server streaming

In server streaming mode, the client sends a single request to the server, which in turn replies with multiple responses.

Client streaming

The client streaming mode is the opposite of the server streaming mode. The client sends multiple requests to the server, which in turn replies with a single response.

Bi-directional streaming

In bi-directional streaming mode, both the client and the server may send multiple messages.

The `.proto` definition

The messages and services used for gRPC are described in .proto files, containing Protocol buffers, or protobuf, definitions.

The definition file is then used to generate code which can be used by both senders and receivers as a contract for communicating through these messages and services. As the binary format used by gRPC lacks any self-describing properties, this is the only way for senders and receivers to know how to interpret the messages.

For this guide, you can use the quickpizza.proto definition available for download on the QuickPizza demo application GitHub repository. For details on how to build your own gRPC proto definition, refer to the official gRPC docs.

syntax = "proto3";
option go_package = "pkg/grpc/quickpizza";
package quickpizza;

service GRPC {
    rpc Status(StatusRequest) returns (StatusResponse) {}
    rpc RatePizza(PizzaRatingRequest) returns (PizzaRatingResponse) {}
}

message StatusRequest {
}

message StatusResponse {
    bool ready = 1;
}

message PizzaRatingRequest {
    repeated string ingredients = 1;
    string dough = 2;
}

message PizzaRatingResponse {
    int32 stars_rating = 1;
}

Write a gRPC performance test with k6

Starting with k6 v0.29.0, you can use a built-in module for gRPC communication. You can find more details for all the methods available on the k6/net/grpc module documentation.

Create the test

The gRPC module is a separate module, available from your test script as k6/net/grpc. Before you can use it, you first have to create an instance of the client. Instantiating the client, as well as the load() function, is only available during test initialization, that is, directly in the global scope.

import grpc from 'k6/net/grpc';
import { check, sleep } from 'k6';

const client = new grpc.Client();

Next, load a .proto definition applicable to the system under test. For the purpose of this article, you can use QuickPizza.

Note
The QuickPizza gRPC service URL grpc-quickpizza.grafana.com:443 returns a 464 HTTP status code if you try to access it in your browser. However, you can still use it in your k6 test scripts, and the gRPC functionality works correctly.

The load() function takes two arguments, the first one being an array of paths to search for proto files, and the second being the name of the file to load.

import grpc from 'k6/net/grpc';
import { check, sleep } from 'k6';

// Download quickpizza.proto for grpc-quickpizza.grafana.com, located at:
// https://raw.githubusercontent.com/grafana/quickpizza/refs/heads/main/proto/quickpizza.proto
// and put it in the same folder as this script.
const client = new grpc.Client();
client.load(['definitions'], 'quickpizza.proto');

After that’s done, add the rest of the test that calls the gRPC service.

import grpc from 'k6/net/grpc';
import { check, sleep } from 'k6';

// Download quickpizza.proto for grpc-quickpizza.grafana.com, located at:
// https://raw.githubusercontent.com/grafana/quickpizza/refs/heads/main/proto/quickpizza.proto
// and put it in the same folder as this script.
const client = new grpc.Client();
client.load(null, 'quickpizza.proto');

export default () => {
  client.connect('grpc-quickpizza.grafana.com:443', {
    // plaintext: false
  });

  const data = { ingredients: ['Cheese'], dough: 'Thick' };
  const response = client.invoke('quickpizza.GRPC/RatePizza', data);

  check(response, {
    'status is OK': (r) => r && r.status === grpc.StatusOK,
  });

  console.log(JSON.stringify(response.message));

  client.close();
  sleep(1);
};

This test script does the following:

First, it uses the .connect() function to connect to the system under test. By default, the client will set plaintext to false, only allowing you to use encrypted connections. If you, for any reason, need to connect to a server that lacks SSL/TLS, just flip this setting to true.
The script then continues by creating the object you want to send to the remote procedure you’re invoking. In the case of RatePizza, the object includes the ingredients for the pizza, and the type of dough.
Next, it invokes the remote procedure, using the syntax <package>.<service>/<procedure>, as described in the proto file. This call is made synchronously, with a default timeout of 60000 ms (60 seconds). To change the timeout, add the key timeout to the config object of .connect() with the duration as the value, for instance '2s' for 2 seconds.
After k6 receives a response from the server, the script checks to make sure the procedure executed successfully. The gRPC module includes constants for this comparison which are listed here. Comparing the response status with grpc.StatusOK, which is 200 OK just like for HTTP/1.1 communication, ensures the call was completed successfully.
The script then logs the message in the response, closes the client connection, and sleeps for a second.

Run the test

You can execute the test just like any other test by using the k6 run command:

$ k6 run grpc-example.js

         /\      Grafana   /‾‾/
    /\  /  \     |\  __   /  /
   /  \/    \    | |/ /  /   ‾‾\
  /          \   |   (  |  (‾)  |
 / __________ \  |_|\_\  \_____/

     execution: local
        script: grpc-example.js
        output: -

     scenarios: (100.00%) 1 scenario, 1 max VUs, 10m30s max duration (incl. graceful stop):
              * default: 1 iterations for each of 1 VUs (maxDuration: 10m0s, gracefulStop: 30s)

INFO[0000] {"starsRating":3}                             source=console

  █ TOTAL RESULTS

    checks_total.......................: 1       0.86/s
    checks_succeeded...................: 100.00% 1 out of 1
    checks_failed......................: 0.00%   0 out of 1

    ✓ status is OK

    GRPC
    grpc_req_duration..................: avg=33.75ms min=33.75ms med=33.75ms max=33.75ms p(90)=33.75ms p(95)=33.75ms

    EXECUTION
    iteration_duration.................: avg=1.16s   min=1.16s   med=1.16s   max=1.16s   p(90)=1.16s   p(95)=1.16s
    iterations.........................: 1       0.86/s
    vus................................: 1       min=1      max=1
    vus_max............................: 1       min=1      max=1

    NETWORK
    data_received......................: 4.1 kB  3.6 kB/s
    data_sent..........................: 762 B   656 B/s


running (00m01.2s), 0/1 VUs, 1 complete and 0 interrupted iterations
default ✓ [======================================] 1 VUs  00m01.2s/10m0s  1/1 iters, 1 per VU

From the output, you can check that the script is working and that the server indeed responds with a rating for the type of pizza supplied in the request body. You can also see that the check was successful, meaning the server responded with 200 OK.

Summary

In this article, you’ve gone through some of the fundamentals of gRPC and how it works. You also had a look at the k6 gRPC client and created a working test script demonstrating its functionality.

Additional resources

Running distributed tests

Mon, 21 Sep 2026 15:16:28 +0000

Running distributed tests

It has already been established that k6 can run large load tests from a single instance, but what about multiple instances running a single test?

Several reasons why you may wish to run a distributed test include:

Your system under test (SUT) should be accessed from multiple IP addresses.
A fully optimized node cannot produce the load required by your extremely large test.
Kubernetes is already your preferred operations environment.

For scenarios such as these, we’ve created the k6-operator.

Note
Refer to Use the k6 Operator with Grafana Cloud k6 on how to integrate the k6 Operator with Grafana Cloud, including creating Private Load Zones.

Introducing k6-operator

k6-operator is an implementation of the operator pattern in Kubernetes, defining custom resources in Kubernetes. The intent is to automate tasks that a human operator would normally do; tasks like provisioning new application components, changing configurations, or resolving run-time issues.

The k6-operator defines the custom TestRun resource type and listens for changes to, or creation of, TestRun objects. Each TestRun object references a k6 test script, configures the environment, and specifies the number of instances, as parallelism, for a test run. Once a change is detected, the operator will react by modifying the cluster state, spinning up k6 test jobs as needed.

Get started with k6-operator

Let’s walk through the process for getting started with the k6-operator. The only requirement being access to a Kubernetes cluster and having the appropriate access and tooling.

Note
This process can be performed on a local Kubernetes cluster running within Docker! Using kind or k3d are awesome options to experiment with the process.

1. Install the operator

The first step to running distributed tests in Kubernetes is to install the operator if not already installed in the cluster.

Note
Besides privileged access to a Kubernetes cluster, installation will require that the system performing the installation has the following tools installed:

Kubectl

Ensure that your kubectl tool is set for the appropriate Kubernetes cluster.

Then, from your command-line, execute the following:

curl https://raw.githubusercontent.com/grafana/k6-operator/main/bundle.yaml | kubectl apply -f -

Refer to Install k6 Operator for other installation methods.

By default, the operator will be installed into a new namespace, k6-operator-system. You can verify the successful installation by listing available resources within the namespace:

kubectl get pod -n k6-operator-system

After a few moments, your resulting status should become Running as shown below:

NAME                                              READY   STATUS    RESTARTS   AGE
k6-operator-controller-manager-7664957cf7-llw54   2/2     Running   0          160m

You are now ready to start create and execute test scripts!

2. Create a test script

Creating k6 test scripts for Kubernetes is no different from creating the script for the command-line. If you haven’t already created test cases for your system, then we suggest having a read through one of our guides for creating tests for websites and APIs/microservices:

In general, it is advised to start small and expand on your scripts over iterations. So let’s start simple and create a test.js with the following content:

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

export const options = {
  vus: 10,
  duration: '10s',
};

export default function () {
  http.get('https://test.k6.io/');
  sleep(1);
}

Note
While creating scripts, run them locally before publishing to your cluster. This can give you immediate feedback if you have errors in your script.

Let’s go ahead and verify our script is valid by performing a brief test:

k6 run test.js

We should see a successful execution and resulting output summary.

3. Add test scripts

In order for your test scripts to be run, they must be published into your cluster. Two main methods for this are using ConfigMap or PersistentVolume resources.

Add as a ConfigMap

Using a ConfigMap is a quick and straightforward mechanism for adding your test scripts to Kubernetes. The kubectl tool provides a convenient method to create a new ConfigMap from a local script.

Let’s create our ConfigMap as my-test with the content of our test.js script we created in the previous step:

kubectl create configmap my-test --from-file test.js

Caution
Limitations exist on how large your test script can be when deployed within a ConfigMap. Kubernetes imposes a size limit of 1,048,576 bytes (1 MiB) for the data, therefore if your test scripts exceed this limit, you’ll need to mount a PersistentVolume.

Check the motivations for when you should use a ConfigMap versus a PersistentVolume.

You should see confirmation with configmap/my-test created.

Add inside a PersistentVolume

Setting up a PersistentVolume is beyond the scope of this guide, but enables access to a shared filesystem from your Kubernetes cluster via PersistentVolumeClaim.

When using this option, organize your test scripts in the applicable filesystem just as you would locally. This mechanism is ideal when breaking up monolithic scripts into reusable modules.

Note
Organizing your test scripts was part of the discussion during episode #76 of k6 Office Hours.

Caution
When using a PersistentVolume, the operator will expect all test scripts to be contained within a directory named /test/.

To learn more about creating PersistentVolume and PersistentVolumeClaim resources, review the Kubernetes documentation.

4. Create a custom resource

During installation, the TestRun Custom Resource definition was added to the Kubernetes API. The data we provide in the custom resource TestRun object should contain all the information necessary for the k6-operator to start a distributed load test.

Specifically, the main elements defined within the TestRun object relate to the name and location of the test script to run, and the amount of parallelism to utilize.

Note
The TestRun custom resource provides many configuration options to control the initialization and execution of tests. For the full listing of possible options, please refer to the project source and README.

The following examples will show some common variations for the custom resource:

Script in a ConfigMap

When the test script to be executed is contained within a ConfigMap resource, we specify the script details within the configMap block of YAML. The name is the name of the ConfigMap and the file is the key-value for the entry.

Let’s create the file run-k6-from-configmap.yaml with the following content:

apiVersion: k6.io/v1alpha1
kind: TestRun
metadata:
  name: run-k6-from-configmap
spec:
  parallelism: 4
  script:
    configMap:
      name: my-test
      file: test.js

Recall when the script was added as a ConfigMap for our configuration values. We created the ConfigMap named my-test. The test script content was added to the map using the filename as the key-value, therefore the file value is test.js.

The amount of parallelism is up to you; how many pods do you want to split the test amongst? The operator will split the workload between the pods using execution segments.

Caution
It is important that the ConfigMap and CustomResource are created in the same Namespace.

Script in a PersistentVolume

If the test script to be executed is contained within a PersistentVolume, creation of a PersistentVolumeClaim will be required. We won’t go into the details of PersistentVolumes and PersistentVolumeClaims, but to learn more, you should review the Kubernetes documentation.

Assume we’ve created a PersistentVolumeClaim named my-volume-claim against a PersistentVolume containing the test script /test/test.js, we can create the file run-k6-from-volume.yaml with the following content:

apiVersion: k6.io/v1alpha1
kind: TestRun
metadata:
  name: run-k6-from-volume
spec:
  parallelism: 4
  script:
    volumeClaim:
      name: my-volume-claim
      # File is relative to /test/ directory within volume
      file: test.js

Caution
It is important that the PersistentVolumeClaim and CustomResource are created in the same Namespace.

Configure the environment

Not everything should be included directly in your scripts. Well written scripts will allow for variability to support multiple scenarios and to avoid hard-coding values that tend to change. These could be anything from passwords to target urls, in addition to system options.

We can pass this data as environment variables for use with each pod executing your script. This can be defined explicitly within the TestRun resource, or by referencing a ConfigMap or Secret.

apiVersion: k6.io/v1alpha1
kind: TestRun
metadata:
  name: run-k6-with-vars
spec:
  parallelism: 4
  script:
    configMap:
      name: my-test
      file: test.js
  runner:
    env:
      - name: MY_CUSTOM_VARIABLE
        value: 'this is my variable value'
    envFrom:
      - configMapRef:
          name: my-config-vars
      - secretRef:
          name: my-secrets-vars

Note
The above YAML introduces the runner section. This section applies to each pod that will be running a portion of your test, based upon the desired parallelism.

Now, with the referenced resources, our test scripts can use environment variables as in the following:

export function setup() {
  console.log(`Variable is set as: ${__ENV.MY_CUSTOM_VARIABLE}`);
}

Change command-line arguments

k6 options can be specified in many ways, one being the command-line. Specifying options via command-line can still be accomplished when using the operator as shown with the following example:

apiVersion: k6.io/v1alpha1
kind: TestRun
metadata:
  name: run-k6-with-args
spec:
  parallelism: 4
  script:
    configMap:
      name: my-test
      file: test.js
  arguments: --tag testid=run-k6-with-args --log-format json

With the above arguments, we’re adding a test-wide custom tag to metrics and changing the output format of logs to JSON.

Note
Be sure to visit the options reference for a listing of available options.

5. Run your test

Tests are executed by applying the custom resource TestRun to a cluster where the operator is running. The test configuration is applied as in the following:

kubectl apply -f /path/to/your/k6-resource.yaml

After completing a test run, you need to clean up the test jobs created. This is done by running the following command:

kubectl delete -f /path/to/your/k6-resource.yaml

Note
If you make use of real-time results output, e.g. Prometheus Remote Write, use the cleanup option to automatically remove resources upon test completion as with the following example:
YAML
apiVersion: k6.io/v1alpha1
kind: TestRun
metadata:
  name: run-k6-with-realtime
spec:
  parallelism: 4
  # Removes all resources upon completion
  cleanup: post
  script:
    configMap:
      name: my-test
      file: test.js
  arguments: -o experimental-prometheus-rw

6. When things go wrong

Sadly nothing works perfectly all the time, so knowing where you can go for help is important.

Be sure to check the troubleshooting guide as it contains many common pitfalls.

You can also search the k6-operator category in the community forum. k6 has a growing and helpful community of engineers working with k6-operator, so there’s a good chance your issue has already been discussed and overcome. It’s also in these forums where you’ll be able to get help from members of the k6 development team.

Running large tests

Mon, 21 Sep 2026 15:16:28 +0000

Running large tests

k6 can generate a lot of load from a single machine. With proper monitoring and script optimization, you might be able to run a rather large load test without needing distributed execution. This document explains how to launch such a test, and some of the aspects you should be aware of.

Maximizing the load a machine generates is a multi-faceted process, which includes:

Changing operating system settings to increase the default network and user limits.
Monitoring the load-generator machine to ensure adequate resource usage.
Designing efficient tests, with attention to scripting, k6 options, and file uploads.
Monitoring the test run to detect errors logged by k6, which could indicate limitations of the load generator machine or the system under test (SUT).

A single k6 process efficiently uses all CPU cores on a load generator machine. Depending on the available resources, and with the guidelines described in this document, a single instance of k6 can run 30,000-40,000 simultaneous users (VUs). In some cases, this number of VUs can generate up to 300,000 HTTP requests per second (RPS).

Unless you need more than 100,000-300,000 requests per second (6-12M requests per minute), a single instance of k6 is likely sufficient for your needs. Read on to learn about how to get the most load from a single machine.

OS fine-tuning

Modern operating systems are configured with a fairly low limit of the number of concurrent network connections an application can create. This is a safe default since most programs don’t need to open thousands of concurrent TCP connections like k6. However, if we want to use the full network capacity and achieve maximum performance, we need to change some of these default settings.

On a GNU/Linux machine, run the following commands as the root user:

sysctl -w net.ipv4.ip_local_port_range="1024 65535"
sysctl -w net.ipv4.tcp_tw_reuse=1
sysctl -w net.ipv4.tcp_timestamps=1
ulimit -n 250000

These commands enable reusing network connections, increase the limit of network connections, and range of local ports.

The sysctl commands apply immediately for the entire system, and will reset to their default values if you restart the network service or reboot the machine. The ulimit command applies only for the current shell session, and you’ll need to run it again for it to be set in another shell instance.

For detailed information about these settings, how to make them permanent, and instructions for macOS, check out our “Fine tuning OS” article.

Hardware considerations

As load increases, you need to pay attention to hardware constraints.

Network

Network throughput of the machine is an important consideration when running large tests. Many AWS EC2 machines come with connections of 1Gbit/s, which may limit the load k6 can generate.

When running the test, use a tool like iftop in the terminal to view the amount of network traffic generated in real time. If the traffic is constant at 1Gbit/s, your test is probably limited by the network card. Consider upgrading to a different EC2 instance.

CPU

k6 is heavily multi-threaded, and will effectively utilize all available CPU cores.

The amount of CPU you need depends on your test script and associated files. Regardless of the test file, you can assume that large tests require a significant amount of CPU power. We recommend that you size the machine to have at least 20% idle cycles (up to 80% used by k6, 20% idle). If k6 uses 100% of the CPU to generate load, the test will experience throttling limits, and this may cause the result metrics to have a much larger response time than in reality.

Memory

k6 can use a lot of memory, though more efficiently than some other load testing tools. Memory consumption heavily depends on your test scenarios. To estimate the memory requirement of your test, run the test on your development machine with 100VUs and multiply the consumed memory by the target number of VUs.

Simple tests use ~1-5MB per VU. (1000VUs = 1-5GB). Tests that use file uploads, or load large JS modules, can consume tens of megabytes per VU. Note that each VU has a copy of all JS modules your test uses. To share memory between VUs, consider using SharedArray, or an external data store, such as Redis.

If you’re using swap space, consider disabling it. If the system runs out of physical memory, the process of swapping memory to much slower secondary storage will have erratic effects on performance and system stability. Which likely will invalidate any test results as the load generator had different performance in different parts of the test. Instead, plan ahead for the memory usage you expect your tests to achieve, and ensure that you have enough physical RAM for the usage to not exceed 90%.

Monitoring the load generator

The previous section described how hardware limits the load your machine can generate. Keeping this in mind, you should monitor resources while the test runs—especially when running tests for the first time.

The easiest way to monitor the load generator is to open multiple terminals on the machine: one to run k6, and others to monitor the CPU, memory, and network. We recommend the following tools:

CPU and memory: htop or nmon.
Network: iftop or nmon.

If you prefer graphical applications, use the system monitoring tool from your OS (e.g. GNOME System Monitor or Plasma System Monitor), or standalone tools like SysMonTask.

Here’s a screenshot of 3 terminal sessions showing k6, iftop and htop.

Monitoring guidelines

As the test runs, these are good indicators to monitor:

CPU utilization stays within 80%. If all CPU cores are 100% utilized during the test run, you might notice performance degradation in your test results.
Network utilization is at an acceptable level. Depending on your test, you might expect to fully saturate the network bandwidth, or this might be a signal that your test is bound by the available bandwidth. In other scenarios, you might want to minimize network usage to keep costs down.
Memory utilization doesn’t exceed 90%. If you’re close to exhausting available physical RAM, the system might start swapping memory to disk, which will affect performance and system stability (note that we recommend disabling swap space altogether). In extreme cases, running out of memory on Linux will cause the system to end the k6 process.

Error handling should be resilient

When running large stress tests, your script shouldn’t assume anything about the HTTP response. An oversight of some scripts is to test with only the happy path in mind.

For example, in k6 scripts, we often see something like this happy path check:

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

const res = http.get('https://test.k6.io');
const checkRes = check(res, {
  'Homepage body size is 11026 bytes': (r) => r.body.length === 11026,
});

Code like this runs fine when the SUT is not overloaded and returns proper responses. When the system starts to fail, this check won’t work as expected.

The issue is that the check assumes that the response always has a body. But if the server is failing, r.body might not exist. In such cases, the check itself won’t work as expected, and an error such as the following will be returned:

ERRO[0625] TypeError: Cannot read property 'length' of undefined

To fix this issue, make your checks resilient to any response type.

The following change will handle the exception.

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

const res = http.get('https://test.k6.io');
const checkRes = check(res, {
  'Homepage body size is 11026 bytes': (r) => r.body && r.body.length === 11026,
});

Refer to subsequent sections for a list of common errors.

k6 options to reduce resource use

The following k6 settings can reduce the performance costs of running large tests.

Save memory with `discardResponseBodies`

By default, k6 loads the response body of the request into memory. This causes much higher memory consumption and is often unnecessary.

To instruct k6 to not process all response bodies, set discardResponseBodies in the options object like this:

export const options = {
  discardResponseBodies: true,
};

If you need the response body for some requests, override the option with Params.responseType.

When streaming, use `--no-thresholds` and `--summary-mode=disabled`

If you’re running a local test and streaming results to the cloud (k6 cloud run script.js --local-execution), you might want to disable the terminal summary and local threshold calculation, because the cloud service will display the summary and calculate the thresholds.

Without these options, the operations will be duplicated by both the local machine and the cloud servers. This will save some memory and CPU cycles.

Here are all the mentioned flags, all in one:

k6 cloud run scripts/website.js \
  --local-execution \
  --vus=20000 \
  --duration=10m \
  --no-thresholds \
  --summary-mode=disabled

Script optimizations

To squeeze more performance out of the hardware, consider optimizing the code of the test script itself. Some of these optimizations involve limiting how you use certain k6 features. Other optimizations are general to all JavaScript programming.

Limit resource-intensive k6 operations

Some features of the k6 API entail more computation to execute. To maximize load generation, you might need to limit how your script uses the following.

Checks and groups: k6 records the result of every individual check and group separately. If you are using many checks and groups, you may consider removing them to boost performance.
Custom metrics: Similar to checks, values for custom metrics (Trend, Counter, Gauge and Rate) are recorded separately. Consider minimizing the usage of custom metrics.
Thresholds with abortOnFail: If you have configured abortOnFail thresholds, k6 needs to evaluate the result constantly to verify that the threshold wasn’t crossed. Consider removing this setting.
URL grouping: k6 v0.41.0 introduced a change to support time-series metrics. A side effect of this is that every unique URL creates a new time-series object, which may consume more RAM than expected.; To solve this, use the URL grouping feature.

JavaScript optimizations

Finally, if the preceding suggestions are insufficient, you might be able to do some general JavaScript optimizations:

Avoid deeply nested for loops.
Avoid references to large objects in memory as much as possible.
Keep external JS dependencies to a minimum.
Perform tree shaking of the k6 script if you have a build pipeline, and so on.

Refer to this article about garbage collection in the V8 runtime. While the JavaScript VM that k6 uses is very different and runs on Go, the general principles apply. Note that memory leaks are still possible in k6 scripts, and, if not fixed, they might exhaust RAM much more quickly.

File upload considerations

File uploads can affect both resource usage and cloud costs.

Network throughput: The network throughput of the load generator machine and of the SUT are likely bottlenecks for file uploads.
Memory: k6 needs a significant amount of memory when uploading files. Every VU is independent and has its own memory, and files will be copied in all VUs that upload them. You can follow issue #1931 that aims to improve this situation.
Data transfer costs: k6 can upload a large amount of data in a very short period of time. Make sure you understand the data transfer costs before commencing a large scale test.; Outbound Data Transfer is expensive in AWS EC2. The price ranges between $0.08 to $0.20 per GB depending on the region. If you use the cheapest region, the cost is about $0.08 per GB. Uploading 1TB, therefore, costs about $80. A long-running test can cost several hundreds of dollars in data transfer alone.; If your infrastructure is already hosted on AWS, consider running your load generator machine within the same AWS region and availability zone. In some cases, this traffic will be much cheaper or even free. For additional data cost-saving tips, check this article on how to reduce data transfer costs on AWS. Our examples are made with AWS in mind. However, the same suggestions also apply to other cloud providers.
Virtual server costs: The AWS EC2 instances are relatively cheap. Even the largest instance we have used in this benchmark (m5.24xlarge) costs only $4.6 per hour.; Make sure you turn off the load generator servers once you are done with your testing. A forgotten EC2 server might cost thousands of dollars per month. Tip: it’s often possible to launch “spot instances” of the same hardware for 10-20% of the cost.

Common errors

If you run into errors during the execution, it helps to know whether they were caused by the load generator or by the failing SUT.

read: connection reset by peer

This is caused by the target system resetting the TCP connection. It happens when the Load Balancer or the server itself isn’t able to handle the traffic.

WARN[0013] Request Failed       error="Get http://test.k6.io: read tcp 172.31.72.209:35288->63.32.205.136:80: read: connection reset by peer"

context deadline exceeded

This happens when k6 can send a request, but the target system doesn’t respond in time. The default timeout in k6 is 60 seconds. If your system doesn’t produce the response in this time frame, this error will appear.

WARN[0064] Request Failed    error="Get http://test.k6.io: context deadline exceeded"

dial tcp 52.18.24.222:80: i/o timeout

This error is similar to context deadline exceeded, but in this case, k6 wasn’t even able to make an HTTP request. The target system can’t establish a TCP connection.

WARN[0057] Request Failed     error="Get http://test.k6.io/: dial tcp 52.18.24.222:80: i/o timeout"

socket: too many open files

This error means that the load generator can’t open TCP sockets because it reached the limit of open file descriptors. Make sure that your limit is set sufficiently high. Refer to the “Fine tuning OS” article.

WARN[0034] Request Failed     error="Get http://test.k6.io/: dial tcp 99.81.83.131:80: socket: too many open files"

Note
Decide what level of errors is acceptable. At large scale, some errors are always present. If you make 50M requests with 100 failures, this is generally a good result (0.00002% errors).

Benchmarking k6

We’ve executed a few large tests on different EC2 machines to see how much load k6 can generate. Our general observation is that k6 scales proportionally to the hardware. A machine with 2x more resources can generate roughly 2x more traffic. The limit to this scalability is the number of open connections. A single Linux machine can open up to 65,535 sockets per IP address (refer to RFC 6056 for details). This means that a maximum of 65k requests can be sent simultaneously on a single machine. This is a theoretical limit that will depend on the configured ephemeral port range, whether HTTP/2 is in use, which uses request multiplexing and can achieve higher throughput, and other factors.

Primarily, though, the RPS limit depends on the response time of the SUT. If responses are delivered in 100ms, the theoretical RPS limit is 650,000 for HTTP/1 requests to a single remote address.

We maintain a repository with some scripts used to benchmark k6 and create reports. These tests are run for every new k6 version, and you can see the results in the results/ directory.

Distributed execution

In load testing, distributed execution happens when a load is distributed across multiple machines.

Users often look for the distributed execution mode to run large-scale tests. Although a single k6 instance can generate enormous load, distributed execution is necessary to:

Simulate load from multiple locations simultaneously.
Scale the load of your test beyond what a single machine can handle.

In k6, you can split the load of a test across multiple k6 instances using the execution-segment option. For example:

## split the load of my-script.js across two machines
k6 run --execution-segment "0:1/2"   --execution-segment-sequence "0,1/2,1" my-script.js
k6 run --execution-segment "1/2:1"   --execution-segment-sequence "0,1/2,1" my-script.js

## split the load of my-script.js across three machines
k6 run --execution-segment "0:1/3"   --execution-segment-sequence "0,1/3,2/3,1" my-script.js
k6 run --execution-segment "1/3:2/3" --execution-segment-sequence "0,1/3,2/3,1" my-script.js
k6 run --execution-segment "2/3:1"   --execution-segment-sequence "0,1/3,2/3,1" my-script.js

## split the load of my-script.js across four machines
k6 run --execution-segment "0:1/4"     --execution-segment-sequence "0,1/4,2/4,3/4,1" my-script.js
k6 run --execution-segment "1/4:2/4"   --execution-segment-sequence "0,1/4,2/4,3/4,1" my-script.js
k6 run --execution-segment "2/4:3/4"   --execution-segment-sequence "0,1/4,2/4,3/4,1" my-script.js
k6 run --execution-segment "3/4:1"     --execution-segment-sequence "0,1/4,2/4,3/4,1" my-script.js

However, at this moment, the distributed execution mode of k6 is not entirely functional. The current limitations are:

k6 does not provide the functionality of a “primary” instance to coordinate the distributed execution of the test. Alternatively, you can use the k6 REST API and --paused to synchronize the multiple k6 instances’ execution.
Each k6 instance evaluates Thresholds independently - excluding the results of the other k6 instances. If you want to disable the threshold execution, use --no-thresholds.
k6 reports the metrics individually for each instance. Depending on how you store the load test results, you’ll have to aggregate some metrics to calculate them correctly.

With the limitations mentioned above, we built a Kubernetes operator to distribute the load of a k6 test across a Kubernetes cluster. For further instructions, check out the tutorial for running distributed k6 tests on Kubernetes.

The k6 goal is to support a native open-source solution for distributed execution. If you want to follow the progress, subscribe to the distributed execution issue on GitHub.

Large-scale tests in the cloud

Grafana Cloud k6, our commercial offering, provides an instant solution for running large-scale tests, among other benefits.

If you aren’t sure whether OSS or Cloud is a better fit for your project, we recommend reading this white paper to learn more about the risks and features to consider when building a scalable solution.

Synthetic monitoring

Mon, 21 Sep 2026 15:16:28 +0000

Synthetic monitoring

You can use k6 as synthetic monitoring tool by scheduling k6 smoke tests for continuous production monitoring.

For a more comprehensive solution, you can use Grafana Cloud Synthetic Monitoring to proactively monitor your application and services in production. You can run k6 smoke tests at frequent intervals, receive alerts on potential issues, and manage incidents directly from Grafana Cloud.

Use Chai with k6

Mon, 21 Sep 2026 15:16:28 +0000

Use Chai with k6

As a codebase grows, engineering teams might adopt frameworks or libraries that can help them write more readable and maintainable code. Similarly, as teams write new k6 test scripts, or expand existing tests, you might start looking for ways to keep them readable and organized, so that they’re easier to update in the future.

Chai is a BDD/TDD assertion library that’s commonly used with testing frameworks. You can use Chai with k6 by using the k6chaijs library. With k6chaijs, you get:

BDD, or Behavior-Driven Development, style of assertions for more expressive language
Chainable assertions
More powerful assertions functions such as: deep, nested, ordered, etc.
Automatic assertion messages
Exception handling for better test stability

You can use k6chaijs as an alternative to the check and group functions.

Installation

The k6chaijs library is hosted on jslib and can be imported directly in your k6 script.

import { describe, expect } from 'https://jslib.k6.io/k6chaijs/4.5.0.1/index.js';

Alternatively, you can use a copy of this file stored locally. The source code is available on GitHub.

Benefits of k6chaijs

Here are some of the ways you can use k6chaijs to write better tests.

Expressive language

Using the expect and describe methods can make code easier to read and maintain. For example, writing a code snippet to check if a string length is equal to five can look like the following:

if ('Hello'.length !== 5) {
  throw new Error(`Expected 'Hello' to have a length of 5 but got ${'Hello'.length}`);
}

With Chai, that can be rewritten as follows:

import { describe, expect } from 'https://jslib.k6.io/k6chaijs/4.5.0.1/index.js';

describe('should match expected length', () => {
  expect('Hello').to.have.lengthOf(5);
});

Automatic messages

Chai can also help make your code more concise by providing automatic error messages. For example, the following code triggers an error when executed:

import { describe, expect } from 'https://jslib.k6.io/k6chaijs/4.5.0.1/index.js';

describe('should match expected length', () => {
  expect('Goodbye').to.have.lengthOf(6);
});

And when you run that code, you automatically get an error message without writing any additional code that says:

// 🔥 AssertionError: expected 'Goodbye' to have a length of 6 but got 7

Structure tests

Through encapsulation, your tests can define sections for your application. This makes it easier to:

Locate tests.
Spot missing edge cases.
Keep everything tidy.
Provide a logical format for adding additional tests.

For example, you can encapsulate your tests for two different services in your test script as the following:

import { describe } from 'https://jslib.k6.io/k6chaijs/4.5.0.1/index.js';

describe('service A', () => {
  describe('should do x from service A', () => {
    /*...*/
  });
  describe('should do y from service A', () => {
    /*...*/
  });
});

describe('service B', () => {
  describe('should do x from service B', () => {
    /*...*/
  });
  describe('should do y from service B', () => {
    /*...*/
  });
});

Assert API responses

Assertion libraries are typically used to write mocked unit/integration tests, but you can also use it to test any API response. For example:

import expect from 'https://jslib.k6.io/k6chaijs/4.5.0.1/index.js';
import http from 'k6/http';

const expected = { foo: 'Hello', bar: 'World' };
const response = http.get('https://your.example.domain');

expect(response.body).to.deep.equal(expected);

Error handling with `describe`

The check function doesn’t protect your tests against unsafe code. If a check fails, k6 throws an exception and restarts the script execution from the beginning. For example:

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

export default function () {
  const response = http.get('https://your.example.domain'); // 🙈 could return Error 503

  check(response, {
    'got more than 5 items': (res) => {
      // 🙉 `.json()` might be undefined
      return res.json().length > 5;
    },
  }); // 🙊 k6 will throw an exception and restarts execution from the beginning.

  // 💀 RIP
  check(response, {
    /*...*/
  });
}

With k6chaijs, error handling is provided automatically. Script errors are caught by the describe block and execution can proceed to the next set of tests. For example:

import { describe, expect } from 'https://jslib.k6.io/k6chaijs/4.5.0.1/index.js';
import http from 'k6/http';

export default function () {
  // 😇 You are safe now
  describe('got more than 5 items', () => {
    const response = http.get('https://your.example.domain'); // 🙈 could return Error 503

    // 🙉 `.json()` might be undefined
    expect(response.json()).to.have.lengthOf(5);
  });

  describe('hooray I still get a turn!', () => {
    /*...*/
  });
}

Example

The following script incorporates thresholds with three test cases that use Chai:

One describe function creates sections and groups tests together.
Another describe provides clear instructions on what we hope to achieve from each test.
Chai’s BDD-style expect function is used to write the tests in an expressive, readable way.

import { describe, expect } from 'https://jslib.k6.io/k6chaijs/4.5.0.1/index.js';
import http from 'k6/http';

export default function () {
  const headers = { Authorization: 'token abcdef0123456789' };

  describe('crocodiles API', () => {
    describe('should fetch a list of public crocodiles', () => {
      const response = http.get('https://quickpizza.grafana.com/api/ratings', { headers: headers });

      expect(response.status, 'response status').to.equal(200);
      expect(response).to.have.validJsonBody();
      expect(response.json('ratings').length, 'number of ratings').to.be.above(1);
    });

    describe('should respond with status 200, when a valid rating id is provided', () => {
      const expected = {
        id: 1,
        stars: 5,
        pizza_id: 1,
      };

      const response = http.get('https://quickpizza.grafana.com/api/ratings/1', {
        headers: headers,
      });

      expect(response.status, 'status').to.equal(200);
      expect(JSON.parse(response.body), 'response body').to.deep.equal(expected);
    });

    describe('should respond with status 404, when an invalid rating id is provided', () => {
      const response = http.get('https://quickpizza.grafana.com/api/ratings/12312123123123', {
        headers: headers,
      });

      expect(response.status, 'status').to.equal(404);
      expect(JSON.parse(response.body).error, 'error message').to.contain('not found');
    });
  });
}

k6 users will use the group function to perform this type of operation, however, for users of Javascript testing frameworks, describe is the familiar term. Under the hood, k6chaijs still calls group, but it’s wrapped with a additional extra logic. The same is true for the expect function. That can help users who are already familiar with testing frameworks, and still provide the same output summaries you expect from the built-in k6 functions.

Injecting faults with xk6-disruptor

Mon, 21 Sep 2026 15:16:28 +0000

Injecting faults with xk6-disruptor

xk6-disruptor is an extension that adds fault injection capabilities to k6. It implements the principles of the Chaos Engineering discipline to test the reliability of our applications under turbulent conditions such as delays and response errors.

Key features include:

Everything as code. Facilitate test reuse and collaboration between teams without learning a new DSL.
Fast to adopt with no day-two surprises. No need to deploy and maintain a fleet of agents or operators.
Easy to extend and integrate with other types of k6 tests. No need to try to glue multiple tools together to get the job done.

Capabilities

Currently, the disruptor is intended to test applications running in Kubernetes. Other platforms are not supported at this time.

It provides a Javascript API to inject different faults in HTTP and gRPC requests, such as errors and delays, into the selected Kubernetes Pods or Services.

Other types of faults and disruptors will be introduced in the future. The Roadmap presents the project’s goals for the coming months regarding new functionalities and enhancements.

Use cases

The disruptor lets you test the resiliency of distributed applications by introducing errors in the requests served by your services.

The disruptor does not try to reproduce root causes, such as failed application instances or degraded computing or network resources. It focuses on reproducing the side effects of such failures, so you can focus on understanding the propagation of errors between internal and public services and improving the error handling in your application.

This way, the disruptor makes reliability tests repeatable and predictable while limiting their blast radius. These are essentials to test applications deployed on shared infrastructures such as pre-production and testing environments.

Common use cases are:

Test resilient policies such as backoff, timeouts, retries, etc.
Test the fallback functionality when internal failures arise.
Test SLOs under common internal failures.
Test application performance when experiencing delays.
Add fault injection to existing performance tests.

Learn more

Learn more about Fault injection and Building Resilience early in the development cycle.

Check the first steps to get started with the disruptor.

Follow the examples of injecting faults in different scenarios.

Visit the interactive demo environment in Killercoda and try the disruptor in a demo application without having to do any setup.

Contributing

For any unexpected behavior, please search the GitHub issues first.

And if you are interested in contributing to the development of this project, check the contributing guide.