API Client Manager

​

Why use the web UI?

• Explore an API visually with instant feedback
• Debug assertion failures by inspecting response bodies, headers, and status codes side by side
• Export requests to cURL, Fetch, wget, Python, or HTTPie with one click
• Monitor stress tests with live latency percentile charts
• Record real API traffic through a reverse proxy and export it as .http files
• Review persistent run history with drill-down to individual assertions

​

Starting the server

hitspec serve

hitspec serve ./tests/api/

​

Flags

​

Examples

# Serve on a custom port without opening the browser
hitspec serve --port 8080 --open=false

# API-only mode for a custom frontend or scripted access
hitspec serve --api-only --cors --port 3001

# Read-only mode for shared staging environments
hitspec serve --read-only --env staging

# Verbose JSON logs for production debugging
hitspec serve --log-format json --log-level debug

# Allow shell hooks and database assertions
hitspec serve --allow-shell --allow-db

​

Workspace layout

​

Top bar

• Sidebar toggle — show or hide the left panel
• Breadcrumb — shows the active request method and URL
• Command palette trigger — click or press Cmd+K to open
• Theme toggle — switch between light, dark, and system themes
• Environment selector — dropdown to switch the active environment
• Run All button — executes every request in the active file

​

Left sidebar

​

Center: Request panel

1. URL bar — Displays the HTTP method badge and full URL. Contains a Share button to export the request and a Send button to execute just this request.
2. Description — If the request has an @description annotation, it appears below the URL bar.
3. Tabs:
   • Source — A CodeMirror editor showing the raw .http file content for this request. Edit the source directly and press Cmd+S (Ctrl+S on Windows/Linux) to save changes back to disk. A dot indicator appears on the tab when there are unsaved changes. The file watcher suppresses the reload notification for your own save to avoid UI flicker.
   • Headers — Read-only view of request headers, with a count badge
   • Body — Request body content (JSON, form data, multipart, etc.)
   • Assertions — All assertion rules defined for the request, with a count badge
   • Captures — Variable captures (name, source, path)

​

Right: Response panel

1. Status bar — HTTP status badge (color-coded), response duration, response size, and a pass/fail indicator
2. Tabs:
   • Results — Appears after “Run All”; lists every request result with pass/fail status (failed first, then passed, then skipped). Use checkboxes to select results, Shift+click for range selection. Click a result to inspect it.
   • Body — Response body rendered in a CodeMirror read-only editor with syntax highlighting, line numbers, and built-in search (Cmd+F). Large payloads are virtualized for smooth scrolling.
   • Headers — Response headers as key-value pairs
   • Assertions — Each assertion with pass/fail status, expected vs. actual values
   • Compare — Compare responses from previous runs side-by-side. A sidebar lists historical results for the current request; select two to see a unified or split diff view with syntax-highlighted additions and removals.

​

Status bar

• WebSocket connection status (green dot = connected)
• Active environment name
• Current file name
• Watch mode indicator (appears when a file change is detected)
• Execution progress or last response time

​

Running requests

• A progress bar showing completed/total requests
• The name of the currently executing request
• A streaming list of completed results with pass/fail status and duration

​

Environments

​

Export

• cURL — Shell command
• Fetch — JavaScript fetch() call
• wget — Shell command
• Python — requests library
• HTTPie — Shell command

​

Import

​

Command palette

• Actions — Run current file, view keyboard shortcuts
• Navigation — Jump to any view (Workspace, Stress Test, Mock, etc.)
• Files — Open any .http or .hitspec file in the workspace
• Requests — Jump directly to a specific request by name, method, or URL

​

Keyboard shortcuts

​

General

​

Navigation

​

Sidebar

​

History

• File name
• Environment used
• Pass/fail/skip counts with color-coded icons
• Total duration
• Relative timestamp (e.g., “2 minutes ago”)

• HTTP method and request name
• Status code (color-coded: green for 2xx, yellow for 3xx, red for 4xx/5xx)
• Duration
• Pass/fail indicator

• Subject, operator, and expected value for each assertion
• Actual value for failed assertions
• Custom assertion messages

​

Stress testing

• Total Requests — Cumulative count
• RPS — Current requests per second
• P95 Latency — 95th percentile response time
• Errors — Error count
• Latency Percentiles — P50, P95, P99 breakdown

​

Results

• Summary cards — Total requests, average RPS, success rate, and error count
• Latency percentiles — Min, P50, P95, P99, Max, Mean, Standard Deviation (fractional milliseconds)
• Per-request breakdown — A table with each request’s count, success/error split, and individual latency metrics
• Threshold pass/fail — Badges for each configured threshold showing whether it passed or failed

​

Managing stress profiles

• Create: Configure your desired parameters and click Save as Profile. Enter a name and the profile is saved to hitspec.yaml.
• Edit: Select a profile from the dropdown, modify its parameters, and click Update Profile.
• Delete: Select a profile and click the delete icon to remove it from hitspec.yaml.

​

Mock server

​

Recording proxy

​

Contract testing

​

Settings

​

Appearance

​

Request defaults

​

Notifications

​

Database assertions

• Database Type — PostgreSQL, MySQL, or SQLite
• Connection String — Database connection URL

​

System info

​

Real-time updates

• File changes — When a .http or .hitspec file is modified on disk (with --watch enabled), the UI automatically reloads the file tree and re-parses the active file. A “Watch” indicator appears in the status bar.
• Execution progress — During a “Run All” operation, per-request progress updates stream to the UI in real time, powering the progress bar and result list.
• Stress metrics — During a stress test, live metrics (RPS, latency percentiles, error count) are pushed to the dashboard via the stress_update event.
• Heartbeat — The client sends a ping every 30 seconds to keep the connection alive. If the connection drops, it automatically reconnects with exponential backoff (up to 30 seconds).