API Testing & Benchmarking
Engineered for Humans

Quick Start Guide

A Lunar testing workspace is built around the configuration layout defined in `lunar.config.json` inside your root directory.

1. Initialize Project Workspace

Run the initialization wizard to guide you through creating your project config:

lunar init

You will be prompted to enter the API base URL (e.g., https://api.example.com) and an optional HuggingFace token for LLM operations.

2. Manage Active Configurations

Review active keys, routes, and credentials loaded by Lunar:

lunar config show

Change your configuration variables dynamically via setter command prompts:

lunar config set base_url https://api.my-app.com
lunar config set hf_token hf_abc123XyZ

AI-Powered suite generation

Lunar leverages serverless LLM logic to introspect endpoint structures, map nested payload shapes, and craft logical testing scripts.

Endpoint Probing and Mapping

By hitting live endpoints with schema analyzer hooks, Lunar identifies if the endpoint structure supports REST queries, filters out boilerplate schemas, and sets up validation assertions.

Generate Test Suites

Execute tests generation on any route path registered under your base URL configuration:

lunar gen /users

This probes /users, translates schema components with LLMs, and registers a CRUD testing lifecycle (GET, POST, PUT, DELETE) inside lunar_tests/users.json.

Method Filtering

Restrict generation suites to look for specific target operations:

lunar gen /users POST

Executing Test Suites

Run locally registered test cases to validate endpoints schema, query parameters, payloads, and execution latency thresholds.

Launch Workspace Suites

Triggers execution workflows across all files matching target formats inside `lunar_tests/` folder:

lunar run

Interactive CLI Console Audits

During the run operation, Lunar renders high-contrast terminal grids summarizing check assertions:

• HTTP Status Code validations (e.g. 200 OK vs 404 Not Found)
• Response Body validations (text matching check, JSON key inspections)
• Data type verification (checks that id is int, username is string)
• SLA Latency checks (warns if response times cross threshold tolerances)

Stress Benchmarking (lunar stress)

Benchmark system capacities, bottlenecks, and performance statistics utilizing multi-threaded HTTP request loops.

Executing Stress Benchmarks

Specify the target endpoint route path, the total request count to execute, and concurrency workers count:

lunar stress [route] [requests_count] [concurrency]

Example Usage

Distribute 100 HTTP operations across 20 concurrent threads against /users endpoint:

lunar stress /users 100 20

Aggregated Benchmarking Metrics

Once completion progress bar terminates, Lunar returns detailed profiling results:

• Throughput (RPS): Realized actions processed per second.
• Latency Percentiles: Median response time (p50) along with SLA p90, p95, and p99 metrics.
• Status Codes ratios: Distribution statistics mapping success codes vs server-failure issues.

Visual Dashboard Reporting

Export historical test runs and CLI performance outputs to local responsive HTML dashboard reports.

Generate Dashboard Reports

Run the report generator to parse your execution sqlite databases and generate dashboards:

lunar report

Core Features of the Visual Dashboard

• Interactive Charts: Visual line and bar charts tracking performance changes.
• Details Grid: Dropdown modules detailing individual request headers, assertions status, and payloads.
• Failure Filter: Quickly filter test metrics to spot failed requests or latency outliers.
• Auto Launch: Instantly opens in your native system browser on command completion.

Advanced Assertions Configuration

Customize assertion schemas manually inside JSON workspace test cases to lock down critical REST APIs properties.

Sample Configuration Schema

{
  "name": "Verify user details update",
  "endpoint": "/users/1",
  "method": "PUT",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer sample-token"
  },
  "body": {
    "username": "jane_doe",
    "email": "jane@example.com"
  },
  "assertions": {
    "status_code": 200,
    "content_type": "application/json",
    "contains_text": ["jane_doe"],
    "json_keys": ["id", "username", "email"],
    "json_types": {
      "id": "int",
      "username": "string"
    },
    "max_response_time_ms": 1500
  }
}

Live JSON assertion schema validator

Paste or edit your assertion config below to validate it against the Lunar Engine assertion spec.

CLI Command Map

Quick index of all commands supported by the Lunar CLI framework. Use the filter to search commands.