Formats Reference

The formats object is available within Loadster Code Blocks and provides utilities for encoding, decoding, data transformation, and random data generation. These utilities let you handle various data formats, generate test data, and transform strings programmatically.

Understanding Data Formats in Loadster

In Loadster, data often needs to be transformed between different formats for HTTP requests, authentication, URL parameters, and API payloads. The formats object provides essential utilities for common transformations like URL encoding, Base64 encoding, HTML/XML escaping, and random data generation.

All format methods are synchronous and work consistently across both Protocol Scripts and Browser Scripts. The object is designed to handle the most common data transformation needs in load testing scenarios.

Each bot has access to the same formats object, but random data generation produces unique values for each bot, making it ideal for creating realistic test scenarios with varied data. All methods handle Unicode characters correctly and encoding methods are safe for use in URLs, XML, HTML, and HTTP headers.

String Case Transformation

These methods transform string case, useful for normalizing data or meeting specific API requirements.

formats.uppercase(string)

Convert a string to uppercase.

formats.uppercase("hello"); // "HELLO"
formats.uppercase("Test User"); // "TEST USER"
formats.uppercase("user@example.com"); // "USER@EXAMPLE.COM"

Parameters:

  • string - The string to convert to uppercase

This method converts all characters in a string to uppercase, useful for normalizing usernames, email addresses, or other data that needs consistent casing.

formats.lowercase(string)

Convert a string to lowercase.

formats.lowercase("HELLO"); // "hello"
formats.lowercase("Test User"); // "test user"
formats.lowercase("USER@EXAMPLE.COM"); // "user@example.com"

Parameters:

  • string - The string to convert to lowercase

This method converts all characters in a string to lowercase, commonly used for normalizing email addresses, usernames, or search terms before sending to APIs.

URL Encoding and Decoding

These methods handle URL encoding and decoding, essential for properly formatting query parameters and URL components in HTTP requests.

formats.urlencode(string)

URL encode a string.

formats.urlencode("user@example.com"); // "user%40example.com"
formats.urlencode("hello world"); // "hello%20world"
formats.urlencode("search=value&other=data"); // "search%3Dvalue%26other%3Ddata"

Parameters:

  • string - The string to URL encode

This method encodes special characters in a string to make it safe for use in URLs. Characters like spaces, @, =, & are converted to their percent-encoded equivalents (%20, %40, %3D, %26).

Note: All encoding methods handle Unicode characters correctly and are safe for use in HTTP headers and URL parameters.

formats.urldecode(string)

URL decode a string.

formats.urldecode("user%40example.com"); // "user@example.com"
formats.urldecode("hello%20world"); // "hello world"
formats.urldecode("search%3Dvalue%26other%3Ddata"); // "search=value&other=data"

Parameters:

  • string - The URL-encoded string to decode

This method decodes percent-encoded characters back to their original form. It’s useful for processing URL parameters or data that has been URL-encoded.

Base64 Encoding and Decoding

These methods handle Base64 encoding and decoding, commonly used for authentication headers, binary data transmission, and API tokens.

formats.base64encode(string)

Base64 encode a string.

formats.base64encode("user:pass"); // "dXNlcjpwYXNz"
formats.base64encode("admin:secret123"); // "YWRtaW46c2VjcmV0MTIz"
formats.base64encode("Hello World!"); // "SGVsbG8gV29ybGQh"

Parameters:

  • string - The string to Base64 encode

This method encodes a string using Base64 encoding, commonly used for HTTP Basic Authentication headers where credentials are encoded as “username:password”.

Note: Base64 methods handle both string and binary data appropriately. When working with binary data, the methods accept and return Uint8Array objects.

formats.base64decode(string)

Base64 decode a string.

formats.base64decode("dXNlcjpwYXNz"); // "user:pass"
formats.base64decode("YWRtaW46c2VjcmV0MTIz"); // "admin:secret123"
formats.base64decode("SGVsbG8gV29ybGQh"); // "Hello World!"

Parameters:

  • string - The Base64-encoded string to decode

This method decodes a Base64-encoded string back to its original form. It’s useful for processing encoded data received from APIs or decoding authentication tokens.

Working with Binary Data

For binary data, base64 methods work with Uint8Array:

const originalBase64 = 'iVBORw0KGgoAAAANSUhEUgAAAZAAAACQCAIAAAA=';
const byteArray = formats.base64decode(originalBase64); // returns a Uint8Array
const encodedBase64 = formats.base64encode(byteArray);

if (encodedBase64 === originalBase64) {
    console.log('Good! Re-encoding the byte array got the same Base64 string we started with.');
}

Converting Base64 to String

If the Base64 encoded data is actually a string, convert the byte array to a string:

const decodedByteArray = formats.base64decode('dXNlcjpwYXNz');
const decodedString = String.fromCharCode.apply(null, decodedByteArray);
const [username, password] = decodedString.split(/:/, 2);

console.log(username); // "user"
console.log(password); // "pass"

XML Encoding and Decoding

These methods handle XML entity escaping and unescaping, essential for safely including special characters in XML content.

formats.xmlescape(string)

Escape special characters for XML.

formats.xmlescape("11 > 10"); // "11 > 10"
formats.xmlescape("<tag>content</tag>"); // "&lt;tag&gt;content&lt;/tag&gt;"
formats.xmlescape('Say "hello" & goodbye'); // "Say &quot;hello&quot; &amp; goodbye"

Parameters:

  • string - The string to escape for XML

This method escapes special XML characters (<, >, &, “, ‘) to their XML entity equivalents, making the string safe to include in XML content without breaking the XML structure.

formats.xmlunescape(string)

Unescape XML entities.

formats.xmlunescape("11 &gt; 10"); // "11 > 10"
formats.xmlunescape("&lt;tag&gt;content&lt;/tag&gt;"); // "<tag>content</tag>"
formats.xmlunescape("Say &quot;hello&quot; &amp; goodbye"); // 'Say "hello" & goodbye'

Parameters:

  • string - The XML-escaped string to unescape

This method converts XML entities back to their original characters. It’s useful for processing XML content that has been escaped and needs to be converted back to readable text.

HTML Encoding and Decoding

These methods handle HTML entity escaping and unescaping, essential for safely including special characters in HTML content.

formats.htmlescape(string)

Escape special characters for HTML.

formats.htmlescape("<p>"); // "&lt;p&gt;"
formats.htmlescape("<script>alert('xss')</script>"); // "&lt;script&gt;alert(&#39;xss&#39;)&lt;/script&gt;"
formats.htmlescape('Price: $50 & up'); // "Price: $50 &amp; up"

Parameters:

  • string - The string to escape for HTML

This method escapes special HTML characters to prevent them from being interpreted as HTML tags or entities. It’s essential for safely displaying user-generated content in HTML contexts.

formats.htmlunescape(string)

Unescape HTML entities.

formats.htmlunescape("&lt;p&gt;"); // "<p>"
formats.htmlunescape("&lt;script&gt;alert(&#39;xss&#39;)&lt;/script&gt;"); // "<script>alert('xss')</script>"
formats.htmlunescape("Price: $50 &amp; up"); // "Price: $50 & up"

Parameters:

  • string - The HTML-escaped string to unescape

This method converts HTML entities back to their original characters. It’s useful for processing HTML content that has been escaped and needs to be converted back to readable text.

Timestamp Generation

These methods generate formatted timestamps, useful for creating realistic test data with current dates and times.

formats.timestamp(format)

Generate a formatted timestamp.

formats.timestamp("%Y-%M-%d"); // "2020-07-04"
formats.timestamp("%Y-%M-%d %H:%m:%s"); // "2020-07-04 15:30:45"
formats.timestamp("%M/%d/%Y"); // "07/04/2020"
formats.timestamp("%Y%M%d_%H%m%s"); // "20200704_153045"

Parameters:

  • format - String containing format specifiers for the timestamp

This method generates a timestamp string using the current date and time, formatted according to the specified format string.

Common format specifiers:

  • %Y - 4-digit year (2020)
  • %y - 2-digit year (20)
  • %M - 2-digit month (07)
  • %d - 2-digit day (04)
  • %H - 2-digit hour 24-hour format (15)
  • %h - 2-digit hour 12-hour format (03)
  • %m - 2-digit minutes (30)
  • %s - 2-digit seconds (45)

Timestamps are generated in the bot’s local timezone and reflect the current time when called. This makes them useful for creating realistic test data with current dates and times that change with each test run.

Random Data Generation

These methods generate random data of various types, essential for creating realistic test scenarios with unique data for each bot.

formats.randomalpha(length)

Generate a random alphabetic string.

formats.randomalpha(12); // "zmLkWMwtEhOD"
formats.randomalpha(5); // "FkMpQ"
formats.randomalpha(8); // "AbCdEfGh"

Parameters:

  • length - The length of the random string to generate

This method generates a random string containing only alphabetic characters (a-z, A-Z). It’s useful for creating random usernames, passwords, or other text data that should contain only letters.

Note: Random data generation uses cryptographically secure random number generation. Each bot generates unique random data, ensuring realistic test scenarios with varied data.

formats.randomalphanumeric(length)

Generate a random alphanumeric string.

formats.randomalphanumeric(10); // "F6kEq53p3W"
formats.randomalphanumeric(6); // "A1b2C3"
formats.randomalphanumeric(16); // "K9mN2pQ7sT4vW8xY"

Parameters:

  • length - The length of the random string to generate

This method generates a random string containing both letters and numbers (a-z, A-Z, 0-9). It’s the most commonly used random string generator for creating usernames, session tokens, or general-purpose test data.

formats.randomnumeric(length)

Generate a random numeric string.

formats.randomnumeric(8); // "62331478"
formats.randomnumeric(4); // "1234"
formats.randomnumeric(12); // "987654321098"

Parameters:

  • length - The length of the random numeric string to generate

This method generates a random string containing only digits (0-9). It’s useful for creating random phone numbers, account numbers, or other numeric identifiers.

formats.uuid()

Generate a UUID (Universally Unique Identifier).

formats.uuid(); // "8ffdb4ef-9e87-4b58-9415-f4c454f0a2ee"
formats.uuid(); // "f47ac10b-58cc-4372-a567-0e02b2c3d479"
formats.uuid(); // "6ba7b810-9dad-11d1-80b4-00c04fd430c8"

This method generates a Version 4 UUID (random UUID) that is guaranteed to be unique across all bots and test runs. UUIDs are ideal for creating unique record IDs, session identifiers, or any scenario where you need globally unique values.

Common Usage Patterns

These examples demonstrate how to combine different format methods for common load testing scenarios.

Generate Test Data

const testUser = {
    id: formats.uuid(),
    username: formats.randomalphanumeric(8),
    email: `test_${formats.randomnumeric(6)}@example.com`,
    created: formats.timestamp("%Y-%M-%d %H:%m:%s"),
    phone: `555-${formats.randomnumeric(3)}-${formats.randomnumeric(4)}`
};

URL Building with Parameters

const searchTerm = "user@example.com";
const category = "premium & basic";
const encodedSearch = formats.urlencode(searchTerm);
const encodedCategory = formats.urlencode(category);
const searchUrl = `https://api.example.com/search?q=${encodedSearch}&category=${encodedCategory}`;

Authentication Header

const username = "admin";
const password = "secret123";
const credentials = formats.base64encode(`${username}:${password}`);
const authHeader = `Basic ${credentials}`;

XML/HTML Content Generation

const userInput = "<script>alert('test')</script>";
const safeXmlContent = `<message>${formats.xmlescape(userInput)}</message>`;
const safeHtmlContent = `<p>User said: ${formats.htmlescape(userInput)}</p>`;