# @loadster/bot

> The @loadster/bot module for Playwright scripts — access dataset variables, bot metadata, and timing functions in your Playwright tests.

Source: https://loadster.com/manual/playwright-scripts/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](https://loadster.com/manual/code-blocks/bot/) 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](https://loadster.com/manual/dynamic-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.

```javascript
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');
});
```

```javascript
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:

```javascript
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](https://loadster.com/manual/dynamic-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:**

```javascript
// 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:**

```javascript
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:**

```javascript
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:**

```javascript
const groupNum = bot.getBotGroupNumber();
```

### getBotIdentifier()

Gets a unique bot identifier string.

**Returns:** `string` — The bot identifier

**Example:**

```javascript
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:**

```javascript
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](https://loadster.com/manual/code-blocks/bot/) 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.com](mailto:help@loadster.com)
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.