Automated Load Testing with Jenkins pipelines

Make load testing a first class citizen in your automated testing.

Getting started

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 Jenkins (v2 and above) and services based on it like CloudBees.

This guide will help you get up and running with k6, Jenkins and LoadImpact Insights. This guide assumes you are familiar with k6 and Jenkins v2 and above. We set up a new pipeline and use the Blue Ocean UI to run because it looks nice.

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 Jenkins Pipeline setup.

Jenkins

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:

k6 load test script

To describe the load test script in words:

  1. 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
  2. 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 Jenkins (and other CI tools).
  3. In the load test "main" function we define a group Front page inside 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.

Configuration

Next we created a Jenkins pipeline with the name k6_jenkins_demo

Create a Jenkins pipeline

And here it is when we have executed it a couple of times.

Executed Jenkins pipeline

So slightly more interesting – let’s take a look at the configuration of the pipeline.

Configuration of Jenkins pipeline

For example purposes we've set up a pipeline that only executes a load test, you can however include it as you wish in your pipeline.

All the good stuff is in the Pipeline script so let's go there and take a look.

Jenkins pipeline script

It's all in the Groovy script for the pipeline so we will take a look at what it does in some detail.

You can get the code from the loadimpact/k6-jenkins-example GitHub repo where the code is shared.

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.

Load Impact profile

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.

Load Impact Insights API key

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-jenkins-example repo!

The code has three parts, three stages "Build stuff", "test" and "Done". If you are familiar with Jenkins pipelines you know the stages will be visible in Jenkins when you execute your pipeline including your k6 load test.

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 from the Groovy code so beware you have a token in there.

Before running, make sure k6 is installed in the executable PATH of your build node. Install instructions can be found in the k6 documentation.

The pipeline

node {

    stage ("Build stuff") {
    }

    stage ("test") {
        env.K6CLOUD_TOKEN="INSERT_MY_API_TOKEN_HERE"
        if (isUnix()) {
            sh "k6 run --quiet -o cloud github.com/loadimpact/k6-circleci-example/loadtests/main.js"
        } else {
            bat 'k6.exe run --quiet -o cloud github.com/loadimpact/k6-circleci-example/loadtests/main.js'
        }
    }

    stage ("Done") {
    }
}

The first stage, "Build stuff" is just a placeholder in this example. As is the last stage, "Done".

The action happens in the "test" stage.

The first thing that happens is we set the K6CLOUD_TOKEN environment variable. So replace "INSERT_MY_API_TOKEN_HERE" with your API key. Keep inside the quotes (it is a string).

Next we check if the build node the pipeline is executing on is a windows or unix box. If it’s unix we execute the sh command and if it’s windows the bat command.

Now that's for the execution of the load test. What does the load test itself do? It pulls the script itself from a repo in GitHub.

Execute

Finally, we can look at executing the pipeline in Jenkins and just because it looks good, we’ll use Blue Ocean.

In the dashboard we only have a single pipeline for the purposes of this demo.

Jenkins Blue Ocean dashboard

Open it.

Jenkins Blue Ocean pipeline

And run. Open the running pipeline.

Jenkins Blue Ocean pipeline running

Once it moves into running state it looks like this

Final stage – Show results.

Jenkins Blue Ocean pipeline results

If the load 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.

Result analysis

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. Read more about Insights functionality on this page and adjacent pages in our Knowledge Base

Jenkins Pipeline Analysis

That's it, happy automated testing!