Protocol Scripts

Protocol scripts are a sequence of HTTP/HTTPS requests. They are executed by protocol bots.

In a protocol script, you have precise control of each request: the method, URL, and body. You can also supply dynamic request data for each iteration of the script, such as unique usernames and passwords, so that every request is different.

Since protocol scripts work at the request level, they are ideally suited to load testing APIs and simple static websites. They can also work for dynamic web applications. While it’s possible to test nearly anything at the protocol level, you may find browser scripts to be easier for load testing complex web apps.

Steps in a Protocol Script

Steps form the building blocks for your protocol scripts. A protocol script might have just a single step, or many. Loadster always executes the steps sequentially.

HTTP Steps

An HTTP step makes a single HTTP request. You specify the method, URL, and headers to be sent. If it’s a method that supports a body (like a POST or PUT) you can supply a body too.

You can think of each HTTP step rather like a visual representation of a curl command.

HTTP steps can also have nested resources, validators, capturers, and other attributes. These will be covered in more detail a little later.

Wait Steps

A wait step makes the bot pause, much like a real user might do when viewing a page and before navigating to the next page.

Wait steps are important for a realistic load test: if you create a script without wait times, your test will probably not be representative of normal user behavior, so you’ll have to discount the validity of the results. Try to include realistic wait times in your script.

Code Blocks

Advanced code blocks are far more powerful than ordinary HTTP steps, and they’re meant for situations that require control flow or conditional logic.

In a code block, you can write your own JavaScript to make requests and parse responses, together with loops, if statements, etc.

It’s important to note that the JavaScript in your code blocks doesn’t run in a web browser, but rather in a sandboxed environment on Loadster’s engines.

In code blocks, you have access to modern ECMAScript syntax like the () => {} arrow functions and const and let, as well as common parsing functionality like JSON.parse(str) and XML.parse(str). You also have Loadster’s own user object that is basically a user agent for making HTTP requests.

When you’re ready to dive into code blocks, read all about them in the Code Blocks section.

Recording a Protocol Script

Recording a script from your web browser is often the easiest way to get started.

Recording is especially helpful for static sites with lots of page resources (images, CSS, JS, etc) or dynamic web applications. It can also be useful for testing APIs that serve as the backend for a single page web application (SPA).

Installing the Loadster Recorder browser extension

To record your browser traffic and make a Loadster script, you’ll need the free Loadster Recorder for Chrome or Loadster Recorder for Firefox.

After you’ve installed the extension in your browser, expand it by clicking the Loadster icon in your browser’s toolbar. You can toggle the switch to enable or disable sharing your browsing activity with Loadster.

The browser extension is open source and you can review the source code on GitHub.

Recording your browser activity

To start recording, open a new or existing script and hit Record. Loadster will start communicating with the Loadster Recorder browser extension.

Enter the URL of the first page you want to record.

When you hit Start Recording, Loadster will open a new browser tab to that location. Whatever you do in that browser tab will be recorded as an event and show up in the recording log. Traffic in your other browser tabs is not recorded.

Click Stop Recording when you’re finished.

Filtering which browser events should be included in your script

Many sites have third party trackers, ads, and other content that aren’t in scope for load testing. You may want to filter these out from the recording. Filtering them out results in a cleaner script, and also avoids redundant traffic to third party domains out of your control. However, if you have concerns about the scalability of any of these third parties you rely on to serve your customers, leave them in or coordinate with them for a comprehensive load test.

After you finish recording, Loadster presents you with a list of recorded domains and event types. Uncheck any domains and/or event types that you do not want included in your script.

Previewing and filtering recorded browser events
Previewing and filtering recorded browser events

When you click Add to Script, Loadster converts your raw traffic into steps and append them to your script.

A newly recorded Loadster script
A newly recorded Loadster script

You might notice that many of the events that were recorded have been folded up as resources of other events. When you record a protocol script, Loadster does its best to determine which requests are primary requests (pages) and secondary requests (page assets like CSS, JS, images, etc). For this reason, the number of steps added to your script may not match the number of raw events that were recorded.

Best practices for recording protocol scripts

Recording saves time, but it isn’t always perfect! Avoid the temptation to blindly record and play back scripts without reviewing and understanding them first.

When you record your browser traffic into a protocol script, Loadster does its best to guess the relationship between pages and their resources. Typically, images and stylesheets are recorded as static page resources under the pages that requested them, rather than independent steps. However, there are cases when you may need to edit the script after recording to get it just right.

Also, if you are testing a dynamic site with complicated interactions (such as an OAuth flow, a series of form submissions, or an API), the initially recorded script might need to be edited a bit to allow for repeated use. You generally wouldn’t want to submit the exact same recorded data over and over in a load test.

You may also want to delete recorded steps that you don’t want in your script.

Last of all, always play through your script in the editor before running a load test, to make sure the script runs as intended and you know what it’s doing!

Playing Protocol Scripts

Playing a script in the editor is your chance to discover and fix any errors in your script before running a load test. When you play a script in the editor, it runs with just a single bot. This is a quick way to avoid problems ahead of time.

There are two ways to play a script: Fast Play and Play.

Fast Play and Play
Fast Play and Play

Either mode will play each step in the script sequentially, but Fast Play shortens all wait times, while Play keeps them as-is. Wait times are often unnecessary when scripting, but important when running an actual load test.

As your script plays through each step, you will see flashing lights to show which step is active, and a status displayed when the step finishes.

Steps with green lights indicate success
Steps with green lights indicate success
Steps with red lights indicate errors
Steps with red lights indicate errors

Successful steps will appear with three green dots showing underneath the type of HTTP command (GET, POST, etc.). If an error was encountered, these same three dots will appear in red.

You can stop script playback at any time by clicking on the Stop Button in the toolbar.

Stopping a script when it is still playing
Stopping a script when it is still playing

Viewing script logs and results

After you play your script in the editor, the Logs and Requests tabs appear, with more information about the script that you just played.

The Logs tab displays output from each step, such as the URL, processed response body size (in bytes), info about additional page resources, and any errors that may have occurred.

Use the log to see how the script ran
Use the log to see how the script ran

The Requests tab lets you drill into a tree view of every HTTP step that was played, so you can view the full requests and responses.

Use the Requests tab to drill down into specific steps
Use the Requests tab to drill down into specific steps

It is quite common to receive some errors the first time you play your script. If this happens to you, don’t worry! You can figure out what happened and edit your script to fix the error.

Troubleshooting with the script logs

As your script plays, Loadster shows you a realtime log of the requests being made, their response codes, and other information. This can be really helpful in determining what went wrong. Errors show up in red under each step.

Script errors show up in the log
Script errors show up in the log

The error displayed above is a simple HTTP 404, due to the URL pointing to a non-existent resource. Errors can occur for many reasons.

It is helpful to know the HTTP Status Codes and how your application uses them.

Here are a few of the HTTP status codes you will commonly see when load testing:

  • 200 - Successful
  • 201 - Created
  • 301 - Moved Permanently (a type of redirect)
  • 302 - Moved Temporarily (another type of redirect)
  • 404 - Not Found (the URL is probably incorrect or the resource is missing on the server)
  • 500 - Internal Server Error
  • 502 - Bad Gateway
  • 503 - Service Unavailable

Skimming through the logs can often give you all the information you need to know if your script is playing correctly, and if not, to diagnose and fix script errors.

Troubleshooting with the script requests and responses

If you are unable to spot what went wrong from the Logs, Loadster also provides a more detailed way to view script results. The Requests tab shows a tree-like view of every HTTP step that was executed the last time you played your script.

Drill down into individual steps to see the requests and responses
Drill down into individual steps to see the requests and responses

You can drill down to see details about the request and response. You can even view the entire request or response body by clicking on the magnifier.

Troubleshooting with your application logs

On the rare occasions that you are getting script errors and still cannot figure out what is going on from within Loadster, you should look to your application and server logs. Since load testing is specific to your application, these will often provide the details you need to figure out what went wrong.

This is particularly important if your site hides the details of errors and instead surfaces opaque error messages to the browser.

Editing Protocol Scripts

If you’ve spent a few seconds in the script editor, you’ll have already noticed that you can add, edit, drag, and remove steps to edit your script.

Here are a few things that work for all kinds of steps:

  • Add a step by clicking the toolbar button with the relevant step type.
  • Select a step or steps by clicking (or shift-clicking) in a neutral area of a step, such as the left handle.
  • Copy and paste steps by selecting them and using your ordinary keyboard shortcuts (control-c/v or command-c/v). You can even copy and paste them between scripts.
  • Duplicate a step by hovering and clicking on the duplicate icon on the right-hand side of the step.
  • Delete a step by hovering and clicking on the delete icon on the right-hand side of the step.
  • Disable or enable a step by hovering and clicking the toggle icon on the right-hand side of the step. Disabled steps remain in your script but are not played (like commenting them out).
  • Drag to reorder steps by clicking in a neutral area, such as the left handle, and dragging to a new position.

Aside from that, each type of step has its own attributes that you can edit separately.

Editing wait steps

Wait steps are simple. They simply make the bot pause execution of the script for a certain number of seconds.

A wait step
A wait step

To change the duration, click the number of seconds, and enter a new number.

Having realistic wait times is important. You should try to make your scripts run at the same cadence a real user would. If your wait times are unrealistic, your load test results related to the number of concurrent users will be too.

Editing HTTP Steps

HTTP steps are a bit more complicated. In its simplest form, an HTTP step represents a single request to the server, much like a real user’s browser or client would make.

An HTTP step
An HTTP step

When many bots run your script together, the concurrent requests put load on your server.

HTTP Method

The HTTP method is a standard part of every HTTP request. The most commonly used methods are GET and POST, but many applications (especially REST APIs) make use of others such as PUT and DELETE also.

To change the method of a step, click on it and select the new method.

Changing the HTTP Method
Changing the HTTP Method

If you’ve recorded your script, you will rarely need to change the method of a step. However, if you’re creating steps manually, it is important that they have the correct method.

Request URL

Of course, the URL is central to each request. We’re pretty sure you are already familiar with URLs and won’t belabor the point.

You can edit a step’s URL by clicking on it.

Editing a URL
Editing a URL

If you’re editing query string parameters, make sure they are URL encoded! For example, a space in the query parameter values should be encoded as %20. Loadster has some helper functions to help with this.

Request Body

The request body is an optional part of certain types of HTTP requests. Usually, POST and PUT requests have request bodies and other methods like GET and DELETE do not.

Loadster supports pretty much any Content-Type you want to use. Content types that are usually text-based (JSON, XML, form fields, text, etc) are directly editable in your script, while binary data is not directly editable but can be replaced from a file.

Editing the request body and content type
Editing the request body and content type

If the request body is an encoded web form, you can edit it as key-value pairs under the Form Fields tab, or edit the raw encoded body under the Raw Body tab.

Editing form fields
Editing form fields
Editing the raw body
Editing the raw body

You can also replace the body directly from a local file with the Load… button, or truncate it with the Clear button.

It is important that the Request Content Type matches what your server is expecting. The most common type for a web form is application/x-www-form-urlencoded. However, some forms (such as file upload forms) send multipart/form-data. REST APIs may expect application/json, application/xml or even text/xml.

Last of all, watch out for the Interpolate variables in request body option. This checkbox tells whether any string in the body that matches Loadster’s expression syntax should be interpolated into a value. Unless you are knowingly using variables in your script, it is safest to uncheck this, so that strings that resemble ${variables} are left literal.

Request Headers

Request headers are sent with every HTTP request. Most of the time, Loadster sends generic default headers for you, and you don’t have to worry about them much.

But in some cases, you may need to specify headers yourself. You can add a header with Add request header from the step’s Add… menu.

Setting a custom Authorization header for a request
Setting a custom Authorization header for a request

The example above sets an Authorization header with an OAuth token. You can add multiple headers to the same step if you want.

Authentication

Loadster has built-in support for Basic, Bearer, and NTLM authentication. If you want to use something else, chances are you can make it work with custom headers.

You can enable authentication for a step with Add authentication from the step’s Add… menu.

Basic Authentication

HTTP Basic Authentication has been around for decades, and provides a simple way to encode a username and password in an HTTP Authorization header. This approach has mostly fallen out of favor with web applications, but remains popular with APIs where a simple stateless authentication mechanism is desirable.

Bearer Authentication

HTTP Bearer Authentication is commonly used with OAuth, and other situations where authenticating with a single API key is desired. The Bearer token is passed in an Authorization header by itself without any kind of encoding.

NTLM Authentication

Some Microsoft servers, particularly for in-house applications, use the NTLM protocol to authenticate users. This is a challenge-response protocol that involves some kind of identity manager such as Active Directory. It requires a Windows “domain” and a username and password.

Page Resources

Loadster can optionally request additional page resources that piggyback on the primary request.

These are usually static assets like CSS, JavaScript, and images.

Requesting additional resources along with the primary request
Requesting additional resources along with the primary request

If your step includes additional resources, the bot will request them in parallel after the main request completes, much like a web browser would load an HTML page and then load the associated images, CSS, JS, etc.

Loadster’s reported response time for this step will include the time it takes to load these resources.

Page resources only make sense if the request is for a web page and you want the full page with static assets grouped together. You should not use them when testing an API.

Validation Rules

Validation rules (or validators) are a way to assert that the server responds to a step the way you want it to. You can add one or more of these to any HTTP step from the step’s Add… menu.

Adding a Validation Rule to a step
Adding a Validation Rule to a step

You can learn more about them in the Validation Rules section.

Capturing Rules

Capturing rules are a way to capture, or extract, a value from a step’s response. After capturing, the value is stored in a variable, so you can reuse it later in the script.

Adding a Capturing Rule to a step
Adding a Capturing Rule to a step

Capturing and reusing values from server responses is often important when you’re load testing dynamic web apps or APIs.

Learn all about the types of capturing rules and when to use them in Capturing Rules.

Protocol Scripting Best Practices

It’s very important that your Loadster scripts should represent a single user’s usage pattern as realistically as possible. A load test’s results are only as accurate as the traffic patterns you simulate.

Do:

  • Include all relevant HTTP steps and page resources, so your bots hit your servers just like a real user would.
  • If you’re testing an API or dynamic web application, make sure to parameterize any request data that should be unique per user.
  • Play the script to make sure it runs properly with a single user, before launching a load test with multiple users.

Don’t:

  • Remove wait times or leave inaccurate wait times in your script, because unrealistic wait times will cause unrealistic results.
  • Load test someone else’s site without their permission.

Load Testing with Protocol Scripts

Up until now, we’ve been editing the steps in a single protocol script, and playing it in the editor. It’s time to create a test scenario and run a load test!

Protocol scripts are the lower cost option that Loadster offers. They’re great for testing APIs and simple static sites. If your site is complicated and you’re having trouble testing it effectively at the protocol level, check out browser scripts for real headless browser automation.