Running Your Own Gatling Script in Blazemeter Cloud

In my previous blog, I explained how, as a beginner, you can leverage Taurus and BlazeMeter to run Gatling tests without any knowledge whatsoever of how to write a Gatling script.

What if you’re not a beginner, but rather a Gatling pro ready to take your own custom scripts to the cloud? This guide will walk you through how to do just that – and more.

I’ll break it down into three broad steps:

1. Writing your own Gatling test script.
2. Wrapping your new script in a Taurus YAML configuration.
3. Executing your test on the BlazeMeter cloud.

For those of you who prefer writing your scripts in Java, I’ll close by detailing an advanced option available to you if you would like control over what version of Java BlazeMeter’s cloud engines will leverage, which may come in handy if your script is particularly dependent on a specific version.  

Why Use Taurus?

Before we begin, let’s first establish why we’re using Taurus instead of executing our script straight through Gatling.

First and foremost, Taurus enables your Gatling script to run on BlazeMeter’s cloud so that you can execute your test from various engines around the globe and scale your user load well beyond what Gatling alone would ever let you do. 

Unlocking the scalability a cloud service offers may be the biggest benefit, but it’s by no means the only benefit, for Taurus offers a lot more functionality. Even if you’re not interested in leveraging cloud resources, you can run Taurus from your own local machine and take advantage of various features it adds to Gatling, such as real-time visual reporting that displays within your command line terminal. 

Taurus can also make your existing Gatling scripts incredibly flexible. Whereas you would typically hard-code your load configuration with the Gatling script itself, Taurus gives you the option to instead configure that load in a YAML configuration which you can wrap your Gatling script with. This gives you the ability to change your load configuration on the fly. Instead of modifying the script everytime you want to adjust the load, you can simply tweak the YAML configuration for each run, leaving your script untouched. 

With these benefits established, let’s begin the walkthrough! 

Step 1: Create Your Script

As I explained in my previous entry, Gatling is a free, open-source load and performance testing tool that is extremely popular among the professional testing community. It is especially powerful because as an advanced user, you can write your own complex test scripts in Java, Kotlin, or Scala.

This means, of course, that the first step is to write your own test script. How to write a complex script from scratch is beyond the scope of today’s guide – for that, I recommend referring to Gatling’s own in-depth tutorials. Instead, I’ll provide a fairly simple demo script and explain a few lines of its code as it pertains to this guide.

Let’s begin with the following Gatling script, written in Scala:

import io.gatling.core.Predef._
import io.gatling.http.Predef._
import scala.concurrent.duration._

class DemoBlazeApiSimulation extends Simulation {

  val httpProtocol = http
    .baseUrl("https://demoblaze.com")
    .inferHtmlResources()
    .acceptHeader("*/*")
    .contentTypeHeader("application/json")

  val scn = scenario("API Simulation")
    .exec(http("Get Products")
      .get("/")
      .check(status.is(200)))
    .pause(1.second)
    .exec(http("Get Product Details")
      .get("/prod.html?idp_=1")
      .check(status.is(200)))
    .pause(1.second)
    .exec(http("Add Product to Cart")
      .post("/prod.html?idp_=1#")
      .body(StringBody("""{"id":1}""")).asJson
      .check(status.is(200)))
    .pause(1.second)
    .exec(http("Get Cart")
      .get("/cart.html")
      .check(status.is(200)))
    .pause(1.second)

  setUp(
    scn.inject(
      rampUsers(10) during (10.seconds)
    )
  ).protocols(httpProtocol)
   .maxDuration(5.minutes)
}

(Note: Though I’m using a Scala script for today’s demonstration, you can write your test in Java or Kotlin, depending on your preferred language.)

This script, just like the sample test demonstrated in my previous blog, executes a test against one of BlazeMeter’s demo sites. Last time I used blazedemo.com; this time we’re going to use demoblaze.com instead.

The first item of note is that the script defines a sub-class named DemoBlazeAPISimulation, which extends a base class named Simulation. Remember the sub-class name, because we’re going to point Taurus to it later. 

class DemoBlazeApiSimulation extends Simulation {

Next, this script will execute its steps against demoblaze.com using HTTP protocol. It expects to see metadata about the resulting webpage communicated back in JSON format:

  val httpProtocol = http
    .baseUrl("https://demoblaze.com")
    .inferHtmlResources()
    .acceptHeader("*/*")
    .contentTypeHeader("application/json")

Now we’re ready for the test proper. The script defines a scenario named “API Simulation”, which is responsible for executing all of our test steps. Those steps will be as follows:

1. Navigate to demoblaze.com and verify the store’s homepage loads.
2. Select a Samsung Galaxy S6 phone.
3. Add the selected product to the shopping cart.
4. View the shopping cart.

The first step of the test simply verifies that the URL loads correctly by performing a GET method against it and checking for a 200 “OK” response code. It then pauses execution for one second:

 val scn = scenario("API Simulation")
    .exec(http("Get Products")
      .get("/")
      .check(status.is(200)))
    .pause(1.second)

Once that executes, it simulates selecting and viewing the store’s Samsung Galaxy S6. (Alas, our fake store is quite behind the times and does not carry the latest S21 model!).

If you click the S6 from the store page yourself, you’ll notice it takes you to the URL https://demoblaze.com/prod.html?idp_=1, so that’s what the script uses. 

    .exec(http("Get Product Details")
      .get("/prod.html?idp_=1")
      .check(status.is(200)))
    .pause(1.second)

Next, it adds the S6 to its cart, which you would do in your browser by clicking the “Add to cart” button:

If you’re following along in your browser, you can discover how your clicks are processed by leveraging your browser’s developer tools to examine the website’s code. Using that information, our script will add the S6’s ID of “1” to our fake cart, then verify that we get a 200 “OK” response. 

  .exec(http("Add Product to Cart")
      .post("/prod.html?idp_=1#")
      .body(StringBody("""{"id":1}""")).asJson
      .check(status.is(200)))
    .pause(1.second)

The last step in the scenario is viewing the cart. Following along in your browser, you would do this by clicking “Cart” from the top menu:

Doing so takes you to https://demoblaze.com/cart.html. 

So the script performs the same step by navigating to that URL accordingly, then again checking for a 200 “OK” response:

    .exec(http("Get Cart")
      .get("/cart.html")
      .check(status.is(200)))
    .pause(1.second)

Our test is complete and ready to go! Of course, a real test would likely go further via additional steps, but this will suffice for our demonstration purposes today (else this would be a much longer article). 

Finally, the test configures the load by ramping up to 10 users over 10 seconds, then running the test for no longer than 5 minutes:

  setUp(
    scn.inject(
      rampUsers(10) during (10.seconds)
    )
  ).protocols(httpProtocol)
   .maxDuration(5.minutes)
}

(Note: If you recall from my previous blog, you can alternatively configure this in your Taurus YAML. Both methods are equally valid).

Step 2: Wrap the Script for Taurus

We are now ready to feed our Scala (or Java or Kotlin) script into Taurus, which will automatically download Gatling (if it’s not already installed), execute the test, and generate a report afterwards. 

To accomplish this, we need to wrap our script with a YAML configuration file. What do I mean by “wrap”? Whereas you can run a Gatling test without creating your own script by writing a standalone YAML configuration file, you can alternatively point Taurus to run your own custom Gatling script by writing the YAML to point to it instead. In fact, since we fully configured our test (including its load details) within our script, our YAML configuration can be very simple. Eight lines will do the trick:

execution:
- executor: gatling
  scenario: sample

scenarios:
  sample:
    script: Simulation.scala
    simulation: DemoBlazeApiSimulation

First, we need to configure our execution settings to tell Taurus what type of test to run, then define our test scenario. That simply means specifying the executor as “gatling” and naming the scenario whatever you’d like – In this case, let’s be super creative and name it “sample”. 

execution:
- executor: gatling
  scenario: sample

Next, we use the scenario we just named to point to the script. I gave my Scala script the filename Simulation.scala, so I can just feed that name into the scenario. We then tell Taurus the name of the simulation to find within the script, which we previously named via the script’s sub-class. Remember that we named ours DemoBlazeApiSimulation:

class DemoBlazeApiSimulation

Therefore our YAML configuration’s scenario is as follows:

scenarios:
  sample:
    script: Simulation.scala
    simulation: DemoBlazeApiSimulation

(Note: Remember, you can name your script, its sub-class, and your YAML scenario whatever you want – just remember to be consistent in referencing them by name).

That’s it! Our custom script will do all the heavy lifting, so there’s nothing further to specify in our YAML configuration. It simply exists to wrap the script for Taurus to recognize.

With our script and YAML configuration written, running the test through Taurus is easy. I gave my YAML configuration the equally creative filename of gatling.yml, so to execute the test, I need only run bzt gatling.yml from the file’s location:

Taurus runs smoothly and shows a live report as it runs:

The Gatling test is a success!

If it runs successfully in Taurus, that means it’s ready to run in Blazemeter!

Step 3: Run Your Test in the BlazeMeter Cloud

Since BlazeMeter’s engines are built on Taurus’ framework, running your test in the cloud is simple. Login to BlazeMeter, create a new test, and select the Performance Test option:

Use the “Upload Script” feature to upload both your Gatling script and your YAML configuration file:

For my demonstration, I uploaded both my Simulation.scala and gatling.yml:

(Note: If you wrote your test in, for example, Java, then you would upload your JAR file with a wrapping YML file instead of a .scala file).

Before executing the test, make sure that you have the YAML file selected so that the “Start test with:” dialogue at the top references it. Do not start the test with the Scala script instead. Taurus and BlazeMeter need to reference the YML first in order to properly recognize your script. 

(The file currently selected is the one with filled a icon beside it.) 

Also note that unlike some other types of tests (such as JMeter tests), you cannot configure the test’s load through Blazemeter’s UI because we already hard-coded the load configuration in our Scala script. 

Now we’re ready to run the test. Notice if you run my test, you’ll see this warning appear:

I indeed did not specify a location when the load was configured in the Scala script, so I’m fine with using the default location.  

I kick off the test, and in no time at all, I’m greeted by a report of a successful run!

Specifying the Java Runtime Version

In the event that you opt to write your script in Java, you may want to consider what version of Java your test will rely on. Be aware that, as of this writing, BlazeMeter’s Gatling installation currently runs on Java 1.8 (aka Java 8) by default. That means if you write your Gatling test in Java, but your script cannot compile in Java 1.8, you’ll likely be met with something resembling the following error if you attempt to run it on Blazemeter:

Run crashed java.lang.UnsupportedClassVersionError: tests/gatling/DockerTagListSimulation has been compiled by a more recent version of the Java Runtime (class file version 61.0), this version of the Java Runtime only recognizes class file versions up to 52.0

Don’t worry if this happens – You’re not out of luck! All you need to do is tell BlazeMeter’s Taurus engine to run the test with a newer version. You can achieve this by using Taurus’s ShellExec Service, which means simply adding a few lines to your YAML configuration.

For example, if I want my Gatling test to use Java 1.11, I would add the following to my YML file:

services:
- module: shellexec
  prepare:
  - command: /usr/sbin/update-java-alternatives --set java-1.11.0-openjdk-amd64
    run-at: local

(Note: Don’t be thrown off by the run-at setting being set to “local”. The term “local” here is not in the context of a local location vs. a cloud location, but rather in the context of what level command usage is set to behind the scenes – that is, internal to the cloud engine. It’s not necessary to comprehend; as long as it’s set to “local”, all will be well). 

Bottom Line

Taurus is an excellent free, open-source tool for enhancing your Gatling tests. It’s a great tool for beginners to run user-friendly Gatling tests without any scripting experience and it’s an even greater tool for seasoned users who want to get more out of their Gatling tests and see real-time performance reports. Check out my previous piece, Gatling via Taurus: The Beginner-Friendly Alternative to Gatling Load Testing, to learn not only how Taurus helps Gatling novices, but also what features Taurus and BlazeMeter add to Gatling that the tool can’t otherwise provide alone. 

You can do a lot more with Taurus and Gatling than this introductory guide covers. To learn the full extent of what Taurus can do, check out the documentation on its Gatling Executor. 

If you’re just now starting to learn about and consider Gatling as opposed to other tools, check out my colleague’s recent post, Gatling vs. JMeter: The Ultimate Comparison.

Finally, Taurus and BlazeMeter are not limited to Gatling tests, but can in fact run any number of a wide variety of popular testing tools. A good place to start learning what’s possible is Blazemeter’s documentation on Creating a Taurus Test. The Taurus community also provides its own in-depth learning material, starting with the Learning Taurus page.

Get started with running your Gatling scripts through BlazeMeter cloud today!

Start Testing Now