How It Works

Writing Code in Your IDE

You write TypeScript/JavaScript in your preferred IDE with full access to:

IDE features - IntelliSense, refactoring, debugging
AI assistants - Copilot, Cursor, Claude
npm packages - Any web-compatible library (Zod, date-fns, crypto-js, etc.)
Unit testing - Test your code locally before deploying

Two Types of Scripts

1. Components

Components are reusable building blocks that QA uses in visual test flows:

Component	What It Does	QA Uses It In
Assertion	Validates data (e.g., `isValidIBAN`, `matchesSchema`)	Assert Node dropdown
Value Generator	Creates test data (e.g., `generateUser`, `createOrder`)	Context Operations
API Hook	Modifies requests/responses (e.g., `signRequest`)	Flow/Node hooks
Utility	Shared helpers used by other components	Other scripts

Components extend QA’s capabilities without them writing code.

2. Test Cases (Advanced)

Test cases are complete test functions written entirely in code. This is where external libraries shine for developers who prefer code over visual builders.

Platform Integration

Your test code runs in ReAPI’s engine with access to platform globals:

// Available in your test code:
$vars        // Environment variables from the selected variable group
$secrets     // Decrypted secrets (API keys, passwords)
$server      // Server config: { baseUrl, name, id }
$auth        // Auth config with pre-built headers
$context     // Shared context across tests (read/write)
 
// Functions to integrate with platform:
$addAssertionResult({ passed, message, ... })  // Record test assertions
$log("info", "message", { data })              // Log for debugging
$reportApiRequest({ method, url, status, ... }) // Track API calls

Example Test Case

import { testCase } from '@reapi/test-sdk'
 
export const loginTest = testCase(
  {
    id: 'auth-login',
    name: 'User Login Test',
    tags: ['auth', 'smoke'],
    priority: 1,
  },
  async () => {
    // Make API request using platform variables
    const response = await fetch(`${$server.baseUrl}/api/auth/login`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        email: $vars.testUserEmail,
        password: $secrets.testUserPassword,  // Securely injected
      }),
    })
 
    const data = await response.json()
 
    // Record assertions - these appear in ReAPI's test report
    $addAssertionResult({
      passed: response.status === 200,
      message: `Login returned ${response.status}`,
      operator: 'status',
      leftValue: response.status,
      rightValue: 200,
    })
 
    $addAssertionResult({
      passed: !!data.token,
      message: data.token ? 'Token received' : 'No token in response',
      operator: 'hasToken',
      leftValue: !!data.token,
      rightValue: true,
    })
 
    // Store for subsequent tests
    $context.authToken = data.token
  }
)

Same Visualization as Web Tests

When this test runs on the platform, you get the exact same experience as visual tests:

Step-by-step execution visualization
Assertion results with pass/fail status
Request/response details
Logs and debugging info
Test reports and history

The only difference is where the test was written—your IDE vs the web editor.

The Process

Step 1: Register Your Library

Use the ReAPI CLI to upload your code:

npm run build
reapi lib sync --project <project-id>

This uploads your bundle to ReAPI’s CDN and registers it with your project.

Step 2: Platform Analyzes

ReAPI scans your library and discovers:

Exported assertions ($$AssertionFunctions)
Exported generators ($$ValueFunctions)
Exported hooks ($$ApiHooks)
Exported test cases ($$TestCases)

Each component’s metadata (id, name, tags, description) is indexed.

Step 3: Select in Web UI

In ReAPI’s test flow builder:

Components appear in dropdowns (Assert Node, Context Operations, etc.)
Test Cases appear in External Test Case Node

QA can:

Select specific test cases by name
Select multiple tests by tags (e.g., “run all smoke tests”)
Mix external test cases with visual API nodes

Step 4: Engine Runs Your Code

When the test executes:

Engine loads your library from the registered URL
Code runs in a secure VM with platform globals injected
$addAssertionResult() calls are captured
$log() calls are recorded
Results stream to the UI for real-time visualization
Final report shows all assertions, logs, and API calls

┌─────────────────────────────────────────────────────────────┐
│                    Test Execution                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Your Code              Platform Engine              UI     │
│  ─────────              ───────────────              ──     │
│                                                             │
│  loginTest.function()                                       │
│        │                                                    │
│        ├──▶ fetch()  ────▶  Executed  ────────────▶ Request │
│        │                                            shown   │
│        │                                                    │
│        ├──▶ $addAssertionResult()  ───────────────▶ ✅ Pass │
│        │                                            shown   │
│        │                                                    │
│        ├──▶ $log("info", ...)  ───────────────────▶ Log     │
│        │                                            shown   │
│        │                                                    │
│        └──▶ $context.authToken = ...  ────────────▶ Context │
│                                                     updated │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Quick Summary

You Write	Platform Provides	You Get
TypeScript in IDE	`$vars`, `$secrets`, `$server`	Environment integration
`fetch()` calls	Request tracking	API call visualization
`$addAssertionResult()`	Result aggregation	Pass/fail reports
`$log()`	Log capture	Debugging info
Tags on test cases	Tag-based selection	QA can filter and run

Next Steps

Ready to try? → Getting Started
Want the full template? → ReAPI External Library Template

Overview Getting Started