Browser Scripts

Browser scripts automate headless Chrome web browsers. They are executed by Browser Bots.

Real browsers are the best way to test the full stack of your application, including client-side rendering, or when protocol scripting is too tricky to work with your site.

If you’ve worked with browser automation tools like Selenium, Puppeteer, or Playwright, you already understand the concept of browser scripts. Speedway’s implementation is based on Playwright.

Steps in a Browser Script

Each step in your browser script represents an action taken by the user in their web browser. A browser script could have just a single step (loading a page) or many (navigating, clicking, typing, waiting, etc).

You can also write your own JavaScript to be executed on the page or in Speedway’s own environment.

Speedway always executes browser steps sequentially.

A navigate step is like putting a URL into the browser’s location bar. If this is the initial step in your script, it opens a fresh browser context and navigates to that location. If there were previous steps, this step leaves the current location and navigates to a new one.

Click

A click step clicks an element on the page.

You can specify the element with a DOM selector like #id or .class or title. Longer, more complicated selectors like iframe[0] form[name='registration'] input[0] are also supported. If the element is not found on the page initially, the bot will automatically wait a while for the element to appear.

Click steps are useful for clicking on links or buttons, just like a human user might do.

Type

A type step simulates typing text into an input element, such as a text field or textarea.

You can specify the input element to type into with a DOM selector like #username or form input.username. If the element is not found on the page initially, the bot will automatically wait a while for the element to appear before typing.

Typing into fields is necessary when your script needs to log in, fill out a form, and so on.

Select

A select step can choose an option from an HTML select element on the page.

You’ll need to specify the select element with a DOM selector like #countries or form select[name=countries]. If the select element is not found on the page initially, the bot will automatically wait a while for the element to appear.

You’ll also need to specify which of the options to select from the list. The option can be specified by name, value, or index. For example, let’s say your select tag has the following HTML markup:

<select name="countries">
  <option value="CR">Costa Rica</option>
  <option value="HR">Croatia</option>
  <option value="CU">Cuba</option>
</select>

If you wanted to select Croatia, your step could specify CR to select by value, "Croatia" with double quotes to select by name, or [1] with square brackets to select by index.

You can also select elements programmatically in a Code Block.

Files

To interact with a file input element, like <input type="file"/>, use a Files step. Executing a files step is equivalent to clicking on the file picker, opening up the file chooser dialog, and choosing a file from your local filesystem in a real browser.

When you add a files step to your script, you get to specify what file(s) it should use. Your local file’s content becomes part of your script, so when the bots later run the script out on the engine, they have the file data and no longer need access to your local filesystem.

Evaluate Block

Browser bots can even evaluate arbitrary JavaScript inside the automated browser. This is great if you need to do special on-page automation at a more granular level than you can accomplish with individual steps. This is a big topic, and we cover a few of the possibilities in Evaluate Blocks.

Scrape

A scrape step captures the entire DOM from your browser in real time. It’s basically like “View Source”. This is helpful when you are scripting, since it allows you to see what elements exist on the page.

Screenshot

When scripting, you can take a screenshot of the bot’s browser at any time. It’s often helpful to see what the bot is seeing.

Taking a screenshot can be CPU intensive for Speedway’s engines, but has no impact on your server.

Wait

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

Waiting between actions like a real user would makes a script more realistic.

Wait steps can be skipped over in certain situations, like when you’re running the script as a monitor or playing the script in Fast Play mode in the script editor.

Wait For

Instead of waiting for a fixed amount of time, you can wait for a certain element on the page to be in a certain state. The element can be any selector, and the states are:

  • visible - The element exists in the DOM and is not transparent, hidden, or behind another element.
  • hidden - The element exists in the DOM, but is hidden by CSS or obscured by another element.
  • attached - The element exists in the DOM.
  • detached - The element has been removed from the DOM.

If the element never achieves the desired state, the step will eventually time out with an error.

Code Block

A code block lets you write your own JavaScript code, which is executed in Speedway’s environment, not in the browser. Code blocks are meant for implementing your own looping, conditional logic, and control flow in your script.

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).

Code blocks are very powerful, and in fact you could write an entire script in a code block. Read more about them in the Code Blocks section.

Since the code block isn’t executed in the browser, it doesn’t have direct access to the variables in the browser’s context, such as window or document. Take a look at Evaluate Blocks if you need to access those.

Recording a Browser Script

Recording a script from your web browser is often the easiest way to get started, and it works the same way for browser scripts as it does for protocol scripts.

Installing the Loadster Recorder browser extension

To record your browser traffic and make a Speedway 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 extension icon in your browser’s toolbar. You can toggle the switch to enable or disable sharing your browsing activity with Speedway.

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 browser script and hit Record. Speedway 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, Speedway 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.

Immediately after you stop the recording, you’ll see a list of all of the recorded browser actions. You can choose to exclude any actions that you don’t want in your script.

Editing Browser Scripts

You probably 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.

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 browser steps

Most of the other steps, like navigate steps and click steps, allow you to specify which element to act upon with a DOM selector. Some steps, like type steps, also accept another parameter, which is the text to be entered into the field.

You can use variables and expressions to inject dynamic data into these fields.

Validation in Browser Scripts

Unlike protocol scripts, which have validation rules, browser scripts do not have a special construct for validation. Instead, you can perform custom validation by throwing an error from a code block or eval block.