We believe in goal oriented and automated load testing. That's why we built k6 to work well in such environments, integrating nicely with tools like AWS CodeBuild, a fully managed build service in the cloud by Amazon.
This guide will help you get up and running with k6, AWS CodeBuild and LoadImpact Insights. This guide assumes you are familiar with k6 and AWS CodeBuild.
It also assumes you have a LoadImpact account. If not, go get one here – it’s free. Once you have your account setup, try this sample of how to include load testing in your AWS CodeBuild setup.
The load test
It starts with code. This is the load test example script we'll be using in this guide. It tests our example site test.loadimpact.com:
To describe the load test script in words:
- The test will ramp up from 0 to 10 users over 60s, stay flat at 10 users for another 60s, before ramping down to 0 users again over 60s
- We've set a goal that the 95th percentile response time should be below 500ms. This step, k6 thresholds, is essential, it's how we define our goals which is the basis for the pass/fail mechanism to work that is built into k6. If a threshold fails, k6 will end with a non-zero exit code, which in turn indicates a failed build step to the CI tool.
- In the load test "main" function we define a group
Front pageinside which we make a request, check the response status code and sleep for 10s before letting the user loop from the top of the function.
Next, we created an AWS CodeBuild project which we named
k6_codebuild. It’s very simple, almost everything is just default.
Name your build project, identify what you want to build by identifying your repository. In our example we use the github repository loadimpact/k6-codebuild which we have made public so you can get it all.
And this is the history when we have executed a couple of times.
What actually controls the build actions is the
version: 0.1 environment_variables: plaintext: JAVA_HOME: "/usr/lib/jvm/java-8-openjdk-amd64" phases: install: commands: - apt-get install -y curl - mkdir -p ~/k6-bin - | curl -O -L https://github.com/loadimpact/k6/releases/download/v0.17.1/k6-v0.17.1-linux64.tar.gz; tar -xvzf k6-v0.17.1-linux64.tar.gz; mv k6-v0.17.1-linux64/k6 ~/k6-bin/k6; pre_build: commands: - echo Nothing to do in the pre_build phase... build: commands: - ~/k6-bin/k6 run -q -o cloud loadtests/main.js post_build: commands: - echo Build completed on `date`
We just set up a pipeline that only executes a performance test so you can include it as you wish in your pipeline. There is nothing else in this demo.
All the good stuff is in the Pipeline so let’s go there and take a look.
First phase, the install commands, we have added a necessary dependency (CURL) to get the correct version of k6 installed.
Then we create a working directory for k6, download the k6 release, unpack it and move it into the working directory.
No pre or post build commands are added here.
There is a single build command only running k6 and the loadtest.
Integrate with Load Impact Insights
Before we dive into the details – let's get some essentials from your Load Impact account. We need the Insights API key so you can analyze the results in the Load Impact Insights cloud service. The Insights API key you get in your Load Impact account when you are logged in.
Go to your profile, i.e. click your name at the top left and then select “Insider program”. Then copy if from the Manage API token text box underlined in red. The key itself has been masked in the sample below.
Now you have an API key for your account to store the results from the test.
All of the code is shared at GitHub for your download in the loadimpact/k6-codebuild repo!
k6 will pick up the API key from the environment variable
K6CLOUD_TOKEN when executed so it has to be in the environment when executed. This is set in the AWS CodeBuild advanced settings where you add a new environment variable named
You can just leave all the settings to default or whatever setting makes sense for your particular build of course. As we don’t want to keep our Load Impact API key in the code in the repository we add it as an environment variable.
Now let’s execute a build. Once started it will look something like the below picture.
If you open the detailed build log there’s also a direct link to the full results and analysis in Load Impact Insights where you can always find all the results of all your tests.
If the performance test is successful, so will the build be in the pipeline and all is fine. If it fails it will exit with a non-zero exit code and thus fail the build step as well.
A passing build is not much fun to look at. But, when builds fail, you want to understand why. No exception when it's a load test failing the build. We've built Insights to be a perfect companion to k6 for analysing results! The analysis workflow is error driven, meaning the goal is to help you quickly finding the cause of the failed load test.
That's it, happy automated testing!