HTTP Reference

The http object is available within Loadster Code Blocks and provides methods for making HTTP requests programmatically. This allows you to use JavaScript to control HTTP requests with loops, conditionals, and custom logic.

Understanding HTTP Requests in Loadster

In Loadster, HTTP requests are the foundation of Protocol Scripts. While regular HTTP steps provide a visual, step-by-step approach to building requests, the http object in code blocks gives you programmatic control over the same functionality.

The http object provides methods for all standard HTTP methods (GET, POST, PUT, etc.) and can handle authentication, headers, validation, and error handling. All HTTP methods are synchronous - no need for await or promise chains - and the HTTP client automatically maintains cookies and session state just like a real browser would.

Each bot has its own independent HTTP client, so requests made by one bot don’t affect others. This allows you to test realistic scenarios where multiple users interact with your application simultaneously.

HTTP Request Methods

These methods make HTTP requests using the standard HTTP verbs. Each method returns a response object that you can use for validation, variable capturing, or further processing. All methods accept an optional args parameter for customization - see HTTP Request Arguments for details.

http.get(url, args)

Make an HTTP GET request.

const response = http.get('https://api.example.com/users');

// With arguments for headers and validation
const response = http.get('https://api.example.com/users', {
    headers: { 'Authorization': 'Bearer token123' },
    validators: [(response) => response.status === 200]
});

Parameters:

GET requests are used to retrieve data from a server and are the most common type of HTTP request. They should not modify server state and are typically used for fetching web pages, API data, or resources.

http.post(url, body, args)

Make an HTTP POST request with a body.

const response = http.post('https://api.example.com/users', {
    name: 'John Doe',
    email: 'john@example.com'
});

// With arguments for headers and validation
const response = http.post('https://api.example.com/users', requestBody, {
    headers: { 'Content-Type': 'application/json' },
    validators: [(response) => response.status === 201]
});

Parameters:

  • url - The URL to request
  • body - The request body data (JSON object, string, or other data)
  • args - Optional configuration object (see HTTP Request Arguments)

POST requests are used to send data to a server, typically to create new resources or submit forms. The request body can be JSON, form data, or any other content type your API expects.

http.put(url, body, args)

Make an HTTP PUT request with a body.

const response = http.put('https://api.example.com/users/123', {
    name: 'John Smith',
    email: 'johnsmith@example.com'
});

// With arguments for error handling
const response = http.put('https://api.example.com/users/123', updateData, {
    ignoreHttpErrors: true
});

Parameters:

  • url - The URL to request
  • body - The request body data (JSON object, string, or other data)
  • args - Optional configuration object (see HTTP Request Arguments)

PUT requests are used to update or replace entire resources on the server. They’re commonly used in RESTful APIs to update existing records with complete new data.

http.patch(url, body, args)

Make an HTTP PATCH request with a body.

const response = http.patch('https://api.example.com/users/123', {
    email: 'newemail@example.com'
});

// With arguments for timeout and validation
const response = http.patch('https://api.example.com/users/123', patchData, {
    timeout: 5000,
    validators: [(response) => response.status === 200]
});

Parameters:

  • url - The URL to request
  • body - The request body data (JSON object, string, or other data)
  • args - Optional configuration object (see HTTP Request Arguments)

PATCH requests are used to make partial updates to resources. Unlike PUT, which replaces the entire resource, PATCH only updates the specific fields you provide.

http.delete(url, args)

Make an HTTP DELETE request.

const response = http.delete('https://api.example.com/users/123');

// With arguments for authentication and validation
const response = http.delete('https://api.example.com/users/123', {
    headers: { 'Authorization': 'Bearer token123' },
    validators: [(response) => response.status === 204]
});

Parameters:

DELETE requests are used to remove resources from the server. They’re commonly used in RESTful APIs to delete records or cancel operations.

http.options(url, args)

Make an HTTP OPTIONS request.

const response = http.options('https://api.example.com/users');

// With arguments for CORS headers
const response = http.options('https://api.example.com/users', {
    headers: { 'Access-Control-Request-Method': 'POST' }
});

Parameters:

OPTIONS requests are used to retrieve information about the communication options available for a resource or server. They’re commonly used in CORS (Cross-Origin Resource Sharing) preflight requests.

http.trace(url, args)

Make an HTTP TRACE request.

const response = http.trace('https://api.example.com/users');

// With arguments for debugging
const response = http.trace('https://api.example.com/users', {
    timeout: 10000
});

Parameters:

TRACE requests are used for diagnostic purposes to see what changes or additions are made by intermediate servers. They’re rarely used in typical web applications but may be needed for specific debugging scenarios.

HTTP Header Management

These methods manage HTTP headers that are sent with requests. Headers can be set globally for all requests, for specific hosts, or per-request using the args parameter.

http.addHostHeader(host, name, value)

Add a header to all future requests to a specific host.

http.addHostHeader('petstore.loadster.app', 'Authorization', 'Bearer 5a830a310b5ca38a');

This is useful for setting authentication tokens or other headers that should be sent to a specific API or domain throughout your test. The header will be automatically included in all subsequent requests to that host.

http.removeHostHeaders(host, name, value)

Remove host headers matching a host/name/value combination.

// Remove all headers for a host
http.removeHostHeaders('petstore.loadster.app');

// Remove all headers with a specific name for a host
http.removeHostHeaders('petstore.loadster.app', 'Authorization');

// Remove a specific header with exact name/value for a host
http.removeHostHeaders('petstore.loadster.app', 'Authorization', 'Bearer 5a830a310b5ca38a');

This provides flexible control over previously set host headers. You can remove all headers for a host, all headers with a specific name, or headers with exact name/value combinations.

http.addGlobalHeader(name, value)

Add a global header for all requests to all hosts.

http.addGlobalHeader('X-Automated-Testing', 'yes');

Global headers are sent with every HTTP request made by this bot, regardless of the destination host. This is useful for headers that should identify your load test traffic or provide consistent metadata across all requests.

http.removeGlobalHeader(name)

Remove a global header.

http.removeGlobalHeader('X-Automated-Testing');

This removes a previously set global header from all future requests. Useful for changing test behavior or removing headers that are no longer needed.

HTTP Request Arguments

The optional args parameter allows you to customize HTTP requests with headers, validation, error handling, and timeouts. This provides the same functionality as regular HTTP steps but with programmatic control. The args parameter is available on all HTTP request methods.

The args parameter for HTTP methods can include:

  • headers: Object or array of custom headers
  • validators: Array of validation functions
  • ignoreHttpErrors: Boolean to ignore HTTP 4xx/5xx errors
  • timeout: Request timeout in milliseconds

Using args with Different HTTP Methods

// GET request with headers and validation
http.get('https://api.example.com/data', {
    headers: { 'Authorization': 'Bearer token' },
    validators: [(response) => response.status === 200]
});

// POST request with headers and error handling
http.post('https://api.example.com/users', userData, {
    headers: { 'Content-Type': 'application/json' },
    ignoreHttpErrors: true
});

// PUT request with timeout
http.put('https://api.example.com/users/123', updateData, {
    timeout: 5000
});

// DELETE request with multiple options
http.delete('https://api.example.com/users/123', {
    headers: { 'Authorization': 'Bearer token' },
    validators: [(response) => response.status === 204],
    ignoreHttpErrors: true
});

Example with Custom Headers

// Headers as object
const response = http.get('https://api.example.com/data', {
    headers: {
        'Authorization': 'Bearer token123',
        'Content-Type': 'application/json'
    }
});

// Headers as array
const response = http.post('https://api.example.com/data', requestBody, {
    headers: [
        ['Authorization', 'Bearer token123'],
        ['Content-Type', 'application/json']
    ]
});

Example with Validators

const response = http.get('https://api.example.com/users', {
    validators: [
        (response) => response.status === 200,
        (response) => {
            const data = JSON.parse(response.string());
            return data.users.length > 0;
        }
    ]
});

Example with Error Handling

const response = http.get('https://api.example.com/might-fail', {
    ignoreHttpErrors: true
});

if (response.status >= 400) {
    console.log('Request failed with status:', response.status);
}

HTTP Response Object

All HTTP methods return a response object that provides access to the server’s response data, headers, and status information.

HTTP methods return a response object with the following properties and methods:

  • response.status: HTTP status code
  • response.headers: Response headers
  • response.string(): Response body as string
  • response.json(): Response body parsed as JSON
  • response.size: Response size in bytes

HTTP Object Usage Notes

  • All HTTP methods are synchronous - no need for await or promise chains
  • The HTTP client maintains cookies and session state automatically throughout the bot’s execution
  • Use validators for response validation and variable capturing, just like regular HTTP steps
  • Set ignoreHttpErrors: true to handle HTTP error codes manually instead of treating them as failures
  • The http object is available in both Protocol Scripts and Browser Scripts
  • Each bot has its own independent HTTP client with separate session state