Bot Reference
The bot object is available within Loadster Code Blocks and provides methods for controlling and gathering information about the bot that is currently executing your script. The bot object is only available within code blocks, not in regular steps, and all bot methods are synchronous - no need for await or promise chains.
Understanding Bots in Loadster
In Loadster, a “bot” represents a single virtual user that executes your script. When you run a load test, Loadster creates multiple bots to simulate concurrent users interacting with your application. Each bot operates independently, just like real users would.
There are two types of bots in Loadster:
- Protocol Bots - Execute Protocol Scripts by making HTTP/HTTPS requests directly
- Browser Bots - Execute Browser Scripts by controlling real headless Chrome browsers
The bot object represents whichever type of bot is currently running your script, whether it’s a Protocol Bot making HTTP requests or a Browser Bot controlling a web browser. Each bot operates independently with its own variable scope, just like real users would. This object provides methods for timing, variables, iteration control, and bot identification that work consistently across both bot types.
Bot Timing and Delays
These methods control script execution timing and provide information about test duration.
bot.wait(milliseconds) / bot.sleep(milliseconds)
Pause script execution for a specific number of milliseconds.
bot.wait(1000); // Wait 1 second
bot.sleep(2000); // Wait 2 seconds
These are synonymous methods that simulate realistic user behavior by adding delays between actions. Proper wait times are crucial for accurate load testing - they should reflect how real users interact with your application, such as reading content or filling out forms.
bot.getTime()
Get the elapsed time in milliseconds since the load test began.
const elapsedTime = bot.getTime();
console.log(`Test has been running for ${elapsedTime}ms`);
This is useful for implementing time-based logic in your scripts, such as changing behavior during different phases of a test or measuring custom performance metrics that span multiple actions.
Bot Variables
These methods manage bot-scoped variables that persist throughout the script iteration. Variables set with bot.setVariable() remain available for the entire duration of the bot’s script execution, unlike regular JavaScript variables which are scoped to individual code blocks.
bot.getVariable(name, column)
Retrieve the value of a bot variable that was previously set or loaded from a dataset.
bot.getVariable('account'); // get the value of the "account" bot variable
bot.getVariable('account', 1); // get the second column, if it's a multi-column dataset
Variables are essential for creating realistic test scenarios with unique data for each bot, such as different usernames, search terms, or transaction IDs. The optional column parameter allows you to access specific columns when using multi-column datasets.
bot.setVariable(name, value)
Set a bot variable that will persist throughout the current script iteration.
bot.setVariable('user', 'a1350'); // set a bot variable
This is commonly used to store values extracted from server responses (like session tokens or product IDs) so they can be used in subsequent steps. Unlike regular JavaScript variables, bot variables remain available across different code blocks and steps within the same iteration.
Bot Error Handling
These methods control how the bot responds to errors during script execution.
bot.setHaltOnErrors(boolean)
Override the global error handling behavior for this specific bot.
bot.setHaltOnErrors(false); // Continue script even on errors
When set to false, the bot will continue executing even when encountering HTTP 4xx/5xx errors, network timeouts, or validation failures that would normally halt the script. This is useful for testing error recovery scenarios or when you want to handle errors programmatically in your code blocks.
Bot Iteration and Information
These methods provide information about the current bot and its execution context.
bot.getIteration()
Returns the number of complete script iterations this bot has executed, starting from 0.
const iteration = bot.getIteration();
console.log(`This is iteration ${iteration}`);
In load testing, bots continuously repeat script iterations until the test duration expires or iteration limits are reached. This method is useful for implementing behavior that changes over time, such as simulating different user actions on subsequent visits or implementing warmup logic.
bot.getBotNumber()
Returns the unique index of this bot within its bot group, starting from 0.
const botNumber = bot.getBotNumber();
In Loadster scenarios, bot groups contain multiple bots that execute the same script simultaneously. This identifier is useful for implementing bot-specific behavior, such as having certain bots perform different actions or access different data ranges.
bot.getBotGroupNumber()
Returns the index of the bot group this bot belongs to, starting from 0.
const groupNumber = bot.getBotGroupNumber();
Loadster scenarios can contain multiple bot groups to simulate different user behaviors simultaneously (e.g., browsing users vs. purchasing users). This method helps implement group-specific logic when you have complex multi-group test scenarios.
bot.getBotIdentifier()
Returns a globally unique identifier (GUID) for this bot that remains constant throughout the entire test.
const botId = bot.getBotIdentifier();
Unlike bot numbers which are only unique within a group, this identifier is unique across all bots in all groups within the test. This is useful for advanced debugging scenarios or when you need to track specific bot behavior in logs or custom metrics.
Bot Tracing
These methods allow you to manually generate traces for debugging and analysis.
bot.trace()
Manually generate a trace that will appear in the Traces section of your test results.
bot.trace(); // Generate a trace for this point in the script
Traces provide detailed debugging information including screenshots (for Browser Bots), waterfall charts of resource timings, and execution context. While Loadster automatically generates traces for errors and from Bot 0 in each group, this method allows you to create traces at specific points in your script for debugging complex scenarios.
Bot Custom Timers
These methods let you create custom timing measurements that will appear in your test results. Custom timers are essential for measuring end-to-end processes like complete checkout flows or multi-page workflows - tracking what actually matters to your users, not just individual request response times.
bot.startTimer(name)
Start a custom timer to begin measuring a multi-step transaction or business process.
bot.startTimer("My Checkout Flow");
// ... perform checkout actions ...
This begins timing a custom transaction that you’ll later stop with bot.stopTimer(). You can have multiple timers running simultaneously by using different names.
bot.stopTimer(name)
Stop a custom timer and record the elapsed time in your test results.
// ... perform checkout actions ...
bot.stopTimer("My Checkout Flow");
This stops the timer started with bot.startTimer() and records the total elapsed time. The timing will appear in your test results alongside automatic response time measurements.
bot.timer(name, function)
Execute a function while automatically timing its duration.
bot.timer("My Checkout Flow", () => {
// Checkout logic here
});
This is a convenient shorthand for manually starting and stopping timers, ensuring the timer is properly stopped even if the function throws an exception. The timing results will appear in your test results, making this ideal for measuring discrete operations or code blocks that represent important user actions.
bot.timer(name, milliseconds)
Directly report a custom timing measurement in milliseconds without using the timer functions.
bot.timer("My Checkout Flow", 3150); // Report 3.15 seconds
This is useful when you’ve calculated timing externally or want to report aggregate timings from multiple operations. The reported timing will appear in your test results alongside other response time measurements.
Bot Script Control
These methods control the execution flow of your script.
bot.exit()
Immediately terminate this bot’s execution and exit the script.
if (someCondition) {
bot.exit(); // Stop executing the script
}
The bot will stop running and won’t perform any additional iterations. This is useful for implementing conditional logic where certain bots should stop based on application state, error conditions, or test scenarios that require dynamic bot behavior. Other bots in the test will continue running normally.