k6 distributed testing lets you run load tests from multiple geographic locations simultaneously, making your results far more realistic than a single-point test.
Let’s see it in action. Imagine you’re testing an e-commerce API that serves customers worldwide. You want to simulate traffic coming from the US, Europe, and Asia to understand how latency and network conditions in those regions affect your API’s performance.
Here’s a simplified k6 script simulating user sign-ups:
import http from 'k6/http';
import { sleep } from 'k6';
export const options = {
stages: [
{ duration: '1m', target: 50 }, // Ramp up to 50 users over 1 minute
{ duration: '2m', target: 50 }, // Stay at 50 users for 2 minutes
{ duration: '1m', target: 0 }, // Ramp down to 0 users over 1 minute
],
thresholds: {
http_req_failed: '2%', // http errors should be less than 2%
http_req_duration: '500ms', // response time should be less than 500ms
},
};
export default function () {
http.get('https://your-api.com/signup');
sleep(1); // Wait 1 second between requests
}
To run this distributed, you’d typically use k6 Cloud. You upload your script and then configure the test execution. Instead of just hitting "Run," you’d select "Distributed Execution" and choose your target regions.
Let’s say you pick:
us-east-1(N. Virginia)eu-central-1(Frankfurt)ap-southeast-2(Sydney)
k6 Cloud then spins up load generators in each of these AWS regions. Each load generator runs a copy of your script, simulating a portion of the total load you’ve defined (e.g., 50 VUs per region, for a total of 150 VUs). The results from each generator are aggregated in real-time in the k6 Cloud dashboard.
You’ll see metrics like average response time, error rates, and throughput, broken down by each region. This is crucial because a request originating from Sydney to your API server in Frankfurt will have a vastly different latency than a request from N. Virginia to the same server. Distributed testing exposes these regional performance differences.
The core problem this solves is the "single point of failure" or "single point of measurement" issue in traditional load testing. If you run a 1000-user test from your office network in London, you’re not measuring how a user in Tokyo experiences your application. You’re measuring how your London network, your ISP, and your London-to-Tokyo internet route perform before hitting your application. Distributed testing moves the measurement point closer to your actual users.
Internally, k6 Cloud orchestrates this by managing a fleet of load generator instances. When you specify regions, it provisions these instances, deploys your script, starts the tests, and collects the metrics. The aggregation happens on the cloud platform, presenting a unified view. You control the total load, the distribution of that load across regions, and the specific geographic locations from which the load originates.
The options object in your k6 script is where you define the behavior of the load (stages, thresholds), but the execution environment (single-node vs. distributed, specific regions) is configured externally, typically through the k6 Cloud UI or API. This separation allows you to test the same script from vastly different network conditions without modifying the script itself.
What most people don’t realize is that the k6 Cloud load generators themselves are not infinitely scalable within a single region. If you need to simulate 10,000 VUs from us-east-1 alone, you might still need to select multiple availability zones or even regions to distribute that intra-region load effectively, ensuring you don’t saturate the network or CPU of a single generator instance. k6 Cloud handles much of this automatically, but understanding the underlying resource constraints is key for massive scale.
The next step after achieving global distribution is often correlating external performance with internal system metrics using distributed tracing.