Quickstart

Install bolla, open a project, write your first request, and run a load test — in under 5 minutes.

1. Install

curl -fsSL https://bolla.cikubo.it/install.sh | sh

Works on macOS, Linux, and Windows (via WSL). Detects your OS and architecture automatically.

Verify: bolla --version should print bolla 0.1.0.

2. Start bolla

Navigate to your project root (any directory works — bolla creates a .bolla/ folder there to store history).

cd my-project
bolla

bolla starts a local server and opens the UI at http://localhost:3077. Click Open project and point it at your project directory.

Server-only mode: use bolla --server to skip the native window and open http://localhost:3077 in your browser of choice.

3. Write your first request

Create a file anywhere in your project. Convention: api/ or next to the code it tests.

# api/list-users.bolla.yaml
id: list-users
name: List users
method: GET
url: https://jsonplaceholder.typicode.com/users

assertions:
  - check: status_code
    value: 200
  - check: body_contains
    text: '"id"'

In the bolla UI, open your project, and the request appears automatically (bolla scans for *.bolla.yaml recursively). Click Send — you'll see the response with assertion results.

4. Add an environment

Environments let you swap {{base_url}}, tokens, and other variables without editing request files.

# staging.env.yaml
name: staging
variables:
  base_url: https://staging.api.example.com
  TOKEN: eyJhbG...

Update your request to use variables:

url: "{{base_url}}/users"

auth:
  type: bearer
  token: "{{TOKEN}}"

5. Run a load test

Create a scenario file referencing your request:

# api/smoke.scenario.yaml
id: smoke
name: API smoke test

load:
  type: constant
  concurrency: 10
  duration_s: 30

steps:
  - request_id: list-users

gates:
  p95_ms:
    max: 500
  error_rate_pct:
    max: 1.0

In the UI, open the Scenarios tab, select smoke, and click Run. You'll see live p50/p95/p99 latency and RPS charts update in real time.

6. Add it to CI

bolla's --ci mode exits 0 (all gates pass) or 1 (any gate fails). It outputs JUnit XML and JSON reports.

bolla --ci --scenario smoke --env staging --project /path/to/project

GitHub Actions example

- name: API smoke test
  run: bolla --ci --scenario smoke --env staging
  # exits 1 and fails the job if p95 > 500ms or error rate > 1%

- name: Upload test report
  uses: actions/upload-artifact@v4
  with:
    name: bolla-report
    path: .bolla/runs/

GitLab CI example

api-smoke:
  script:
    - bolla --ci --scenario smoke --env staging
  artifacts:
    reports:
      junit: .bolla/runs/**/junit.xml

That's it. You now have a request, an environment, a load test, and a CI gate — all from the same YAML file. No extra tools required.

Next steps

← Previous Overview Next Full reference →