Scripting

Yasumu includes a powerful scripting system powered by Tanxium, a custom JavaScript runtime built on Deno. Scripts allow you to manipulate requests, process responses, and create dynamic testing workflows using TypeScript.

What is Tanxium?

Tanxium is Yasumu’s embedded JavaScript runtime that executes scripts in a secure, isolated environment:

TypeScript native

Write scripts in TypeScript without compilation steps.

Deno-powered

Built on deno_runtime for security and modern APIs.

Isolated execution

Scripts run in Web Workers for safety and performance.

Node.js compatible

Supports common Node.js modules and APIs.

Script lifecycle

Scripts can execute at three different stages:

onRequest
onResponse
onTest

Pre-request scripts run before the HTTP request is sent:

export function onRequest(req, res) {
  // Modify request before sending
  req.headers.set('X-Timestamp', Date.now().toString());
  req.headers.set('X-Request-ID', crypto.randomUUID());
  
  // Access environment variables
  const apiKey = req.environment.get('API_KEY');
  req.headers.set('Authorization', `Bearer ${apiKey}`);
  
  console.log('Request prepared:', req.url);
}

Use cases:

Generate authentication tokens
Add dynamic headers or parameters
Modify request body
Log request details

Post-response scripts run after receiving the HTTP response:

export function onResponse(req, res) {
  // Process response data
  const data = JSON.parse(res.body);
  console.log('Response data:', data);
  
  // Store values in environment for later requests
  if (data.token) {
    req.environment.set('AUTH_TOKEN', data.token);
  }
  
  // Check response status
  if (res.status >= 400) {
    console.error('Request failed:', res.statusText);
  }
}

Use cases:

Extract data from responses
Update environment variables
Chain requests with dynamic data
Log response details

Test scripts run for assertions and validation:

export function onTest(req, res) {
  // Run test assertions
  console.assert(res.status === 200, 'Expected status 200');
  
  const data = JSON.parse(res.body);
  console.assert(data.id, 'Response should have ID');
  console.assert(data.email, 'Response should have email');
  
  console.log('All tests passed!');
}

Use cases:

Validate response status
Assert response structure
Verify data integrity
Run acceptance tests

Script context

Scripts receive two main objects:

Request object (`req`)

The request object provides access to request data and methods:

export function onRequest(req, res) {
  // Request properties
  console.log(req.method);    // HTTP method (GET, POST, etc.)
  console.log(req.url);        // Request URL
  console.log(req.headers);    // Headers Map
  console.log(req.body);       // Request body
  
  // Modify request
  req.headers.set('Custom-Header', 'value');
  req.headers.delete('Old-Header');
  
  // Access environment
  const apiUrl = req.environment.get('API_URL');
  const apiKey = req.environment.get('API_KEY');
  
  // Set environment values
  req.environment.set('LAST_REQUEST', Date.now());
  
  // Access workspace info
  console.log(req.workspace.name);
  console.log(req.workspace.id);
}

Response object (`res`)

The response object provides access to response data:

export function onResponse(req, res) {
  // Response properties
  console.log(res.status);      // HTTP status code
  console.log(res.statusText);  // Status message
  console.log(res.headers);     // Response headers Map
  console.log(res.body);        // Response body (string)
  
  // Parse JSON response
  const data = JSON.parse(res.body);
  console.log('Parsed data:', data);
  
  // Check response type
  const contentType = res.headers.get('Content-Type');
  if (contentType?.includes('application/json')) {
    const json = JSON.parse(res.body);
    // Process JSON data
  }
}

Creating custom responses

You can return custom responses without making actual HTTP requests:

export function onRequest(req, res) {
  // Return a mock response
  const mockResponse = new YasumuResponse(
    JSON.stringify({
      id: 123,
      name: 'Mock User',
      email: '[email protected]'
    }),
    {
      status: 200,
      statusText: 'OK',
      headers: {
        'Content-Type': 'application/json'
      }
    }
  );
  
  return mockResponse;
}

When a script returns a YasumuResponse, the actual HTTP request is skipped, and the mock response is used instead.

Script examples

Authentication
Data extraction
Request signing
Response validation
Conditional logic

Generate authentication tokens dynamically:

export function onRequest(req, res) {
  // Basic authentication
  const username = req.environment.get('USERNAME');
  const password = req.environment.get('PASSWORD');
  
  if (username && password) {
    const credentials = `${username}:${password}`;
    const encoded = btoa(credentials);
    req.headers.set('Authorization', `Basic ${encoded}`);
  }
  
  // Bearer token
  const token = req.environment.get('AUTH_TOKEN');
  if (token) {
    req.headers.set('Authorization', `Bearer ${token}`);
  }
}

Extract and store response data:

export function onResponse(req, res) {
  if (res.status === 200) {
    const data = JSON.parse(res.body);
    
    // Store user ID for subsequent requests
    if (data.user?.id) {
      req.environment.set('USER_ID', data.user.id);
    }
    
    // Store pagination token
    if (data.nextToken) {
      req.environment.set('NEXT_TOKEN', data.nextToken);
    }
    
    // Store authentication token
    if (data.accessToken) {
      req.environment.set('ACCESS_TOKEN', data.accessToken);
    }
    
    console.log('Stored variables for next request');
  }
}

Sign requests with HMAC:

import { createHmac } from 'node:crypto';

export function onRequest(req, res) {
  const secret = req.environment.get('API_SECRET');
  const timestamp = Date.now().toString();
  const method = req.method;
  const path = new URL(req.url).pathname;
  
  // Create signature
  const message = `${method}${path}${timestamp}`;
  const signature = createHmac('sha256', secret)
    .update(message)
    .digest('hex');
  
  // Add signature headers
  req.headers.set('X-Timestamp', timestamp);
  req.headers.set('X-Signature', signature);
}

Validate response structure and data:

export function onTest(req, res) {
  // Check status code
  console.assert(
    res.status === 200,
    `Expected status 200, got ${res.status}`
  );
  
  // Parse response
  let data;
  try {
    data = JSON.parse(res.body);
  } catch (error) {
    console.error('Failed to parse JSON:', error);
    return;
  }
  
  // Validate structure
  console.assert(data.id, 'Response should have id field');
  console.assert(data.name, 'Response should have name field');
  console.assert(data.email, 'Response should have email field');
  
  // Validate data types
  console.assert(
    typeof data.id === 'string',
    'ID should be a string'
  );
  console.assert(
    data.email.includes('@'),
    'Email should be valid'
  );
  
  console.log('✓ All validations passed');
}

Execute different logic based on conditions:

export function onRequest(req, res) {
  const env = req.environment.get('ENVIRONMENT');
  
  if (env === 'development') {
    // Use development settings
    req.headers.set('X-Debug', 'true');
    req.headers.set('X-Source', 'yasumu-dev');
  } else if (env === 'production') {
    // Use production settings
    req.headers.delete('X-Debug');
    req.headers.set('X-Source', 'yasumu-prod');
  }
  
  // Add retry header for failed requests
  const retryCount = req.environment.get('RETRY_COUNT') || '0';
  if (parseInt(retryCount) > 0) {
    req.headers.set('X-Retry-Count', retryCount);
  }
}

Environment access in scripts

Scripts have full access to environment variables and secrets:

export function onRequest(req, res) {
  // Get variables
  const apiUrl = req.environment.get('API_URL');
  const version = req.environment.get('API_VERSION');
  
  // Get secrets (same API)
  const apiKey = req.environment.get('API_KEY');
  
  // Set new values
  req.environment.set('LAST_REQUEST_TIME', Date.now());
  req.environment.set('REQUEST_COUNT', '1');
  
  // Check if variable exists
  if (req.environment.get('DEBUG') === 'true') {
    console.log('Debug mode enabled');
  }
}

Changes to environment variables in scripts are temporary and only persist for the current request execution. To make permanent changes, update the environment through the API.

Available APIs

Tanxium provides access to common JavaScript and Node.js APIs:

Console APIs

console.log('Message');
console.error('Error message');
console.warn('Warning');
console.info('Info');
console.debug('Debug');
console.assert(condition, 'Assertion message');

Crypto APIs

// Generate UUID
const id = crypto.randomUUID();

// Generate random values
const bytes = crypto.getRandomValues(new Uint8Array(16));

Node.js Modules

import { Buffer } from 'node:buffer';
import { createHmac } from 'node:crypto';

// Use Buffer
const encoded = Buffer.from('text').toString('base64');

// Use crypto
const hash = createHmac('sha256', 'secret')
  .update('data')
  .digest('hex');

URL APIs

const url = new URL(req.url);
console.log(url.hostname);
console.log(url.pathname);
console.log(url.searchParams.get('key'));

Date APIs

const now = Date.now();
const date = new Date();
const timestamp = date.toISOString();

Script execution flow

Parse script

The script is parsed and validated for syntax errors.

Create worker

A new Web Worker is created for isolated execution.

Load context

Request, response, and environment data are loaded into the worker.

Execute function

The appropriate function (onRequest, onResponse, or onTest) is called.

Extract changes

Changes to the request or environment are extracted from the worker.

Terminate worker

The worker is terminated after execution completes or times out.

Error handling

Script errors are captured and returned in the execution result:

const result = await entity.executePreRequestScript(context);

if (result.success) {
  console.log('Script executed successfully');
  console.log('Updated context:', result.context);
} else {
  console.error('Script error:', result.error);
  console.error('Stack trace:', result.error.stack);
}

Best practices

Keep scripts focused: Each script should have a single, clear purpose. Avoid complex logic that’s hard to debug.

Use environment variables: Don’t hardcode values in scripts. Store configuration in environment variables.

Log strategically: Use console.log() to debug scripts, but remove excessive logging in production.

Handle errors gracefully: Use try-catch blocks for operations that might fail, like JSON parsing.

Scripts have a 30-second execution timeout. Ensure your scripts complete quickly to avoid timeout errors.

Performance considerations

Worker pooling

Tanxium reuses workers when possible to improve performance.

Heartbeat monitoring

Workers send heartbeat signals to detect frozen scripts.

Automatic cleanup

Workers are automatically terminated after execution.

Timeout protection

Scripts that exceed 30 seconds are automatically terminated.

Next steps

REST API Testing

Use scripts in REST requests

Environments

Manage variables accessed by scripts

Schema Language

Learn about script block syntax

Workspaces

Understand workspace structure

Get Started

Core Concepts

Features

Guides

What is Tanxium?

TypeScript native

Deno-powered

Isolated execution

Node.js compatible

Script lifecycle

Script context

Request object (`req`)

Response object (`res`)

Creating custom responses

Script examples

Environment access in scripts

Available APIs

Script execution flow

Error handling

Best practices

Performance considerations

Worker pooling

Heartbeat monitoring

Automatic cleanup

Timeout protection

Next steps

REST API Testing

Environments

Schema Language

Workspaces

Build docs developers (and LLMs) love

Get Started

Core Concepts

Features

Guides

​What is Tanxium?

TypeScript native

Deno-powered

Isolated execution

Node.js compatible

​Script lifecycle

​Script context

​Request object (req)

​Response object (res)

​Creating custom responses

​Script examples

​Environment access in scripts

​Available APIs

​Script execution flow

​Error handling

​Best practices

​Performance considerations

Worker pooling

Heartbeat monitoring

Automatic cleanup

Timeout protection

​Next steps

REST API Testing

Environments

Schema Language

Workspaces

Build docs developers (and LLMs) love

What is Tanxium?

Script lifecycle

Script context

Request object (`req`)

Response object (`res`)

Creating custom responses

Script examples

Environment access in scripts

Available APIs

Script execution flow

Error handling

Best practices

Performance considerations

Next steps