k6 Performance Tool with EC2 Scalability

A shared, on-demand performance testing platform for teams — run k6 tests at scale on EC2 without building or maintaining your own infrastructure.

Overview

The QE Performance Test tool gives every team a common way to author and execute k6 performance tests. Tests live alongside shared configuration and utilities, deploy through the same Terraform-managed EC2 runner, and report into your own S3 bucket. Teams plug into a maintained platform instead of standing up perf infrastructure of their own.

Paired with QE's MCP servers, the platform also accelerates how new tests are written: an MCP-assisted prompt produces a k6 starter for the right category, which you then refactor against the shared helpers and validate locally before promoting to an EC2 run.

Why Teams Use This Tool

Teams get a shared performance testing platform instead of creating one.

Key benefits

Shared execution model with repeatable scripts.
On-demand EC2 execution for scalable test runs without always-on cost.
Centralized configuration through .env, TEST_ENV, and category/test selectors.
MCP-assisted test generation for faster creation of new k6 tests.

What This Platform Handles for You

You do not need to build separate infrastructure per team.

Provided by this repository

Terraform-managed AWS resources for a k6 EC2 runner.
Scripted deployment/execution flow via scripts/run-tests.sh and scripts/deploy-to-ec2.sh.
Organized test layout under k6-tests/ with shared config/utilities.
Environment targeting (qa, dev, proto, beta, production).
Report output into your own S3 bucket.

Shared platform flow: scripts deploy k6 tests to an on-demand EC2 runner via SSM, execute the load test, upload reports to S3, then stop the instance.

Purpose

This guide explains how a new user can clone the repository, configure the project, run a k6 test through the framework, and verify that the output file is uploaded to S3.

The k6 Performance Tool supports MCP-assisted test generation and EC2-based execution. Teams can generate a starter k6 test using the QE MCP server, configure the required values, execute the test on EC2, and review the results in Amazon S3.

For the complete framework guide, refer to: k6 EC2 Performance Testing Framework – GitLab CI/CD with Terraform.

Repository (test branch):
https://gitlab.com/bloombergindustrygroup/qe/performance/k6-ec2-performance/-/tree/test?ref_type=heads

Prerequisites

Before starting, make sure you have:

Access to the GitLab repository
AWS CLI configured for your target account/environment
Terraform installed
k6 installed if local validation is needed
Required AWS permissions
Valid application credentials (stored locally — we do not store your creds)
Correct environment configuration values
An accessible S3 bucket for reports

Step-by-step Instructions

Follow these steps in order. Start with a small test load, then scale up after you confirm a successful EC2 run and S3 upload.

Clone the repository

Clone the shared performance testing repository and switch to the supported branch.

git clone https://gitlab.com/bloombergindustrygroup/qe/performance/k6-ec2-performance.git
cd k6-ec2-performance
git checkout test

Generate or select a k6 test

Use the QE MCP configuration at .vscode/mcp.json. The MCP server can generate a starter k6 test based on the application, endpoint, user flow, and load pattern. You can also select an existing test under k6-tests/.

Example prompt

Generate a k6 spike test for the selected application.

Use TEST_ENV-driven URLs, environment variables for credentials,
shared configuration, functional checks, and latency thresholds.

Save the generated test under the appropriate folder inside k6-tests/.

Before using an MCP-generated test, confirm that it does not contain hardcoded credentials or secrets and that it uses the shared framework configuration.

Create the environment file

Copy the sample environment file to create your local .env. This file stores runtime configuration, AWS settings, and test credentials.

cp .env.example .env

Update the `.env` file

Open .env and set the required values. Example:

K6_RUN_MODE=ec2
AWS_REGION=us-east-1
AWS_PROFILE=default
TEST_ENV=beta
TEST_SIZE=small
K6_TEST_FILE=auth/login-blawauth.js
BLAW_USERNAME=your-username
BLAW_PASSWORD=your-password
S3_BUCKET_EAST=your-s3-bucket

Make sure that:

The execution mode (K6_RUN_MODE) is correct
The selected test file exists and matches K6_TEST_FILE
The target environment (TEST_ENV) is correct
AWS configuration values are valid
The S3 bucket is accessible
Credentials are stored securely

Never commit the .env file or real credentials to the repository.

Check available tests

List the available test files before running:

./scripts/list-tests.sh

Confirm that K6_TEST_FILE matches an available test. Run the test locally first when possible to verify authentication, environment URLs, shared helpers, checks, and thresholds before an EC2 run.

Initialize Terraform

Move to the Terraform directory and initialize providers:

cd tf
terraform init

Review the Terraform plan

Run plan with the correct environment file and review the output:

terraform plan -var-file=environments/sbx/terraform.tfvars

Confirm that the infrastructure changes look correct before applying.

Apply the Terraform configuration

Provision or update the AWS resources required for EC2-based k6 execution:

terraform apply -var-file=environments/sbx/terraform.tfvars

Return to the project root

cd ..

Run the test

Run the framework execution script:

./scripts/run-tests.sh

The framework will typically:

Prepare the selected k6 test
Deploy the test files to the EC2 runner
Execute the test remotely through AWS Systems Manager
Generate test logs and performance reports
Upload the generated results to Amazon S3
Stop the EC2 runner after execution

Monitor the execution

Watch the terminal output or GitLab CI/CD logs during the run. Confirm that:

The EC2 runner starts successfully and is reachable
The test files are deployed
The k6 test executes successfully
Checks and thresholds complete
Reports are generated
The S3 upload completes successfully

Verify the S3 upload and final validation

After execution, open the configured S3 bucket and verify that the reports and logs are available.

Check:

Correct bucket
Correct folder path
Expected report or log file
Successful file visibility
File can be downloaded if needed

Also review results for response times, request failure rate, checks pass rate, threshold failures, stability, and regressions.

The run is successful when:

The repository was cloned correctly
.env was configured correctly
Terraform completed successfully
The selected test executed successfully
The output file was generated
The file was uploaded to S3 and is visible there

Notes

        Important
        Never commit the .env file or real credentials
Always verify the selected test before execution
Use the correct Terraform environment file
Start with TEST_SIZE=small; increase load only after validating the initial run
Always confirm S3 upload after EC2 execution

      

Summary

A new user should follow this sequence:

Clone the repo and check out the test branch
Generate or select a k6 test under k6-tests/
Create .env from .env.example and update configuration values
Check available tests with ./scripts/list-tests.sh
Run terraform init, plan, and apply in tf/
Return to the project root and run ./scripts/run-tests.sh
Verify the output file in S3

MCP Workflow for K6 Test Generation

You can also use our MCPs to generate tests faster. See Step 2 above for the primary path; this section is a deeper reference.

Define the scenario you need (endpoint, user journey, expected load profile, assertions).
Ask MCP tools to generate a k6 starter test for the target category (api, auth, browser, load).
Place generated test files under k6-tests/<category>/.
Refactor to shared config/utilities in k6-tests/common/.
Add or update .env variables required by the generated test.
Validate with a local run.
Promote to an EC2 run for team-scale execution.

Prompt Pattern for MCP Test Generation

Use a prompt structure like:

Generate a k6 <category> test for <service/endpoint or user flow>.
Environment: TEST_ENV-driven URLs.
Use shared config from k6-tests/common/config.js.
Use credentials from environment variables only.
Assertions: status, latency threshold, and key functional checks.
Output file: k6-tests/<category>/<test-name>.js.

Tip: Keep the prompt focused on one scenario at a time. A tight, single-purpose prompt produces a cleaner starter test that is easier to refactor into the shared helpers.

MCP Guardrails Before Merging Generated Tests

Before merging an MCP-generated test, confirm:

No hardcoded credentials or secrets.
Uses TEST_ENV-driven configuration.
Uses existing shared helpers where possible.
Includes meaningful checks and thresholds.
Runs successfully in local mode before EC2 mode.

← E2E Tests MCP Guide (k6 / e2e_performance) ← Back to Quality Engineering Tools Suite