@loadster/bot

The @loadster/bot module provides Loadster-specific context for Playwright scripts. It gives your tests access to Loadster dataset variables, information about the bot and iteration currently running, and timing functions.

The interface is similar to the bot object available in Loadster’s Browser Bot scripts, but is a separate implementation for Playwright so is not exactly the same.

Overview

When running Playwright Test scripts in Loadster, the @loadster/bot module gives your tests access to:

  • Dataset variables — Values from datasets attached to your script
  • Bot metadata — Information about the current bot (number, group, iteration)
  • Timing — Relative time since the script iteration started

This module is automatically available to Playwright Test scripts executing in the Loadster environment.

Usage

When running in the Loadster environment, you can simply import or require the module.

import {test, expect} from '@playwright/test';
import bot from '@loadster/bot';

test('login with dataset credentials', async ({page}) => {
    const [username, password] = bot.getVariable('credentials');

    await page.goto('https://example.com/login');
    await page.fill('#username', username);
    await page.fill('#password', password);
    await page.click('button[type="submit"]');

    await expect(page).toHaveURL('/dashboard');
});

const {test, expect} = require('@playwright/test');
const bot = require('@loadster/bot');

test('login with dataset credentials', async ({page}) => {
    const [username, password] = bot.getVariable('credentials');
    // ...
});

Named Imports

You can also import specific functions:

import {getVariable, getBotNumber, getTime} from '@loadster/bot';

const user = getVariable('user');
const botNum = getBotNumber();
const elapsed = getTime();

API Reference

getVariable(name, [index])

Gets a variable value by name. Variables typically come from CSV datasets attached to your Loadster script.

Parameters:

  • name (string) — The variable name
  • index (number, optional) — Column index for multi-column datasets

Returns: string | string[] — Single value, specific column value, or array of column values

Examples:

// Single-column dataset - returns string "user@example.com"
const email = bot.getVariable('email');

// Multi-column dataset — returns array ["user001", "secret123"]
const [username, password] = bot.getVariable('credentials');

// Multi-column dataset — get specific column by index
const username = bot.getVariable('credentials', 0);
const password = bot.getVariable('credentials', 1);

getIteration()

Gets the current iteration number (0-based). Each bot runs through the script multiple times during a load test. This tells you which iteration is currently executing.

Returns: number — The current iteration number

Example:

const iteration = bot.getIteration();
console.log(`Running iteration ${iteration}`);

getBotNumber()

Gets the bot number within the population. Each bot in a load test has a unique bot number. When playing from the script editor the bot number will always be 0.

Returns: number — The bot number (0-based)

Example:

const botNum = bot.getBotNumber();
console.log(`I am bot #${botNum} in the group`);

getBotGroupNumber()

Gets the bot group number. Bots are organized into groups based on the scenario.

Returns: number — The bot group number

Example:

const groupNum = bot.getBotGroupNumber();

getBotIdentifier()

Gets a unique bot identifier string.

Returns: string — The bot identifier

Example:

const botId = bot.getBotIdentifier();

getTime()

Gets the relative time in milliseconds since the script iteration started. Useful for custom timing measurements.

Returns: number — Relative time in milliseconds

Example:

const startTime = bot.getTime();

await page.goto('https://example.com');
await page.click('#load-data');
await page.waitForSelector('.data-loaded');

const elapsed = bot.getTime() - startTime;

console.log(`Data loading took ${elapsed}ms`);

Differences from Code Blocks Bot Object

The @loadster/bot module for Playwright provides a subset of what’s available in the Code Blocks bot object for Protocol Bot and Browser Bot scripts. Some methods aren’t available yet in Playwright, such as:

  • setVariable() — Variables in Playwright scripts are read-only and come from datasets. You can’t set variables at runtime like you can in Code Blocks.
  • wait() / sleep() — Use Playwright’s built-in page.waitForTimeout() or other waiting methods instead.
  • Custom timers — startTimer(), stopTimer(), and timer() aren’t available yet.
  • trace() — Manual trace generation isn’t available; Playwright has its own tracing capabilities.
  • setHaltOnErrors() — Error handling is managed through Playwright Test’s built-in mechanisms.
  • exit() — To stop a test early, use Playwright Test’s test.skip() or throw an error.

If you need any of these capabilities in Playwright scripts, please contact help@loadster.app to let us know about your use case.

Notes

  • Variables are resolved once when the script starts and cached for the duration of the test.
  • If a variable is not defined, getVariable() returns an empty string and logs a warning.
  • The module is preloaded in the Loadster Playwright runtime; you don’t need to install it separately.