bolla documentation
Everything you need to go from zero to a full API testing + load testing setup.
What is bolla?
bolla is a git-native API client with built-in load testing, mocking, and CI gating — all driven from a single plain-text YAML file per request. It runs as a local server that serves both a web UI and a JSON API, with an optional headless CI mode.
The core idea: define a request once, use it for manual testing, multi-step load scenarios, mock serving, and CI quality gates. No duplication between tools, no sync issues, always in git.
New here? Start with the Quickstart guide — you'll have bolla running and your first load test executing in under 5 minutes.
Architecture
bolla is a single Rust binary. When you run it, it starts a local HTTP server (default port 3077) that serves:
- A React web UI at
/ - A JSON REST API at
/api/* - Your collection mock routes (when the mock server is started)
All state lives in your project directory under .bolla/ — a SQLite database for history, a specs directory for imported OpenAPI files, and run reports. Your request definitions are plain .bolla.yaml files alongside your source code.
Module system
bolla is built around a modularity constraint: every capability beyond the core client lives in an independent Rust crate and can be toggled off without recompiling. When a module is disabled, its routes are not registered and its nav entry disappears.
| Module | Default | What it adds |
|---|---|---|
| Core always on | — | Request builder, collections, environments, assertions, history |
| Load & Scenarios always on | — | Scenario runner, ramp/constant/spike profiles, live metrics, CI gates |
| Mock Server optional | off | HTTP mock from your collection; smart faker for unexampled fields |
| OAuth2 optional | off | Client credentials, PKCE, device flow; encrypted token cache |
| Contracts optional | off | OpenAPI import, collection generation, response drift detection |
| History & Reports optional | off | Filtered search, CSV/HTML export, run-to-run comparison |
| Polish Bundle optional | off | Code snippets, cURL/HAR import, security lint, docs site, dashboard |
| AI Assist optional | off | BYO Anthropic key; assertion suggestions, report summarization |
Directory layout
my-project/
├── src/ # your application code
├── api/
│ ├── get-users.bolla.yaml # request definition
│ ├── create-user.bolla.yaml
│ └── smoke.scenario.yaml # load scenario
├── staging.env.yaml # environment variables
└── .bolla/
├── history.db # SQLite — runs, load runs, drift events
├── specs/ # imported OpenAPI specs + manifests
└── runs/ # CI report output