View on GitHub

Webrunner Documentation

Documentation for the Webrunner project.

Webrunner Documentation

A lightweight browser tool for testing API

Technical overview

Features

  • Request tree with folders and request nodes (HTTP or gRPC).
  • HTTP requests with method, URL, body, and headers executed via the backend.
  • gRPC requests with target/service/method and metadata executed via the backend.
  • Request status persistence for logs, last response, request body/headers, and Before/After scripts.
  • Before Request / After Request scripts written in JS with access to vars, log, request, and response.
  • Variable templating in request body/headers using ``, including JSON-safe replacements.

Architecture

  • Backend (Spring Boot): persists the request tree and status in SQLite, executes HTTP and gRPC requests, and serves the built frontend from static resources.
  • Frontend (Vite): UI for managing the request tree, editing request body/scripts, and viewing response/logs. Production builds output to app/src/main/resources/static.

Running the app

Backend only

  1. Ensure Java 21 is installed (or Gradle toolchain is available).
  2. Run:
./gradlew :app:bootRun

The backend starts on http://localhost:9999.

Frontend only

  1. Install dependencies:
cd ui
npm install
  1. Start the dev server:
npm run dev

Tip: if your backend is on a different origin, set VITE_API_BASE (for example http://localhost:9999).

Frontend + backend together

  1. Build the frontend into Spring Boot static resources:
cd ui
npm install
npm run build
  1. Start the backend:
./gradlew :app:bootRun

Then open http://localhost:9999.

Build a .exe (native)

  1. Install GraalVM JDK 21.
  2. Create a gradle.properties file at the project root and set the GraalVM path:
org.gradle.java.home=C:\path\to\graalvm
  1. Build the native binary (Windows):
gradlew.bat nativeCompile

Before Request and After Request

Scripts run in the frontend before sending a request and after receiving a response.

  • Before Request: can modify request.body and request.headers, populate vars, and log messages.
  • After Request: has access to the response object (HTTP/gRPC) and can log or post-process results.

Scripts are executed with new Function(...) and receive vars, log, request, and (for After) response.

Script context

  • vars.add(name, value) — store a variable.
  • vars.get(name) — read a variable.
  • vars.entries() — read all variables as an object.
  • log(...) — append to the execution log.
  • assert(actual, expected?, message?) — log a failed assertion without stopping the request.
  • uuid() — generate a UUID v4 string.
  • request.body, request.headers — current request payload and headers.
  • response (After Request only) — HTTP/gRPC response payload.

Templates in body and headers

After Before Request finishes, the app applies `` templating to the request body and headers using the variables stored in vars.

  • JSON bodies support recursive replacement in objects/arrays.
  • Plain text bodies use simple `` substitution.

Example

// Before Request
vars.add('token', 'abc123');
vars.add('userId', 42);
log('Token prepared', vars.get('token'));

// Variables can be referenced in the body/headers:
// {
//   "id": 
// }

// After Request
log('Status:', response?.statusCode);

Tools used

  • Java 21 + Spring Boot for the backend.
  • SQLite for local persistence.
  • Vite + TypeScript for the frontend.
  • CodeMirror for request/script editors.
  • Gradle for builds (plus GraalVM for native Windows builds).

Working with requests

Create and organize

  1. Use New Folder to group requests.
  2. Use New Request and choose HTTP or gRPC.
  3. Select a request in the tree to edit its details in the top bar.

HTTP requests

  • Set the method and URL in the top bar.
  • Edit the Body and Headers tabs as needed.
  • Use Before Request for preparing data and After Request for validation.
  • Click Send (or Ctrl + Enter) to execute.

gRPC requests

  • Set the target, service, and method in the top bar.
  • Use Reload to refresh services from the target.
  • Provide request payload and metadata in Body and Headers.
  • Click Send (or Ctrl + Enter) to execute.

Logs and responses

  • Response Body and Response Headers show the latest execution.
  • Logs collects output from log() and errors from scripts.

Chain requests

Chain requests run multiple existing requests in order, sharing the same vars store.

Create a chain

  1. Create a Chain request in the tree.
  2. Open the chain request to reveal the chain editor.
  3. Use Add request to append requests from the tree.

Run mode

  • Click Run to execute the chain from top to bottom.
  • Logs from all steps are aggregated in Logs.
  • Current State shows the latest request/response and the current variable snapshot.

Debug mode

  • Click Debug to execute the first request only.
  • The active request row shows a Next button.
  • Click Next to execute the next request.
  • On the last step, the button becomes Finish to end the debug session.

Current State content

Current State includes:

  • Request metadata (name, type, and target/method info).
  • Request body and headers for the executed step.
  • Response payload (when available).
  • All variables in vars.