Bruno: a free, Git-friendly API client

In this tutorial you will rebuild the Brew & Bean checks from the Postman lesson in Bruno. Bruno is an open-source API client for desktop. Its main difference from Postman is that a collection is just a folder of plain text files on your disk. That means you can put it in Git, review changes in a pull request and share it with your team without any cloud account.

Prerequisites: the practice API running at http://127.0.0.1:8000 (see *Testing APIs by hand*), Bruno installed from usebruno.com, and Node.js if you want the command-line runner. At the time of writing (2026) Bruno has a free open-source edition and also paid editions with extra features. Check usebruno.com for what each includes. Everything in this lesson uses core features.

Neither is 'the best'. Many companies use Postman, so know it. Many teams like Bruno because the tests live next to the code. Learning one makes the other easy, as the ideas are the same.

Look in your folder with a file explorer. You will find bruno.json and an environments folder with Local.bru. This is the whole collection, with no hidden database. The environment file looks like this:

vars {
  baseUrl: http://127.0.0.1:8000
}

A Bruno environment file: a vars block with one variable.

Bruno's Assert tab is a no-code way to check things: left side is what to look at (res.status, res.body.total, res.headers), then an operator (eq, neq, gt, lt, contains and more) and the expected value. For anything more complex, use the Tests tab with JavaScript. Here is the saved request file Bruno wrote for you, with a JavaScript test added:

meta {
  name: Get menu
  type: http
  seq: 1
}

get {
  url: {{baseUrl}}/menu
  body: none
  auth: none
}

assert {
  res.status: eq 200
  res.body.length: eq 8
}

tests {
  test("every item has a positive price", function () {
    res.body.forEach(function (item) {
      expect(item.price).to.be.above(0);
    });
  });
}

A whole request in one small text file: URL, assertions and a test. res is the response and expect is the Chai assertion function.

Create a request Create order: POST {{baseUrl}}/orders. In the Body tab choose JSON and paste the order. In Assert add res.status eq 201, res.body.total eq 390 and res.body.status eq received. Then open the Vars tab, or the Script tab, to save the id for later requests. The script version is:

meta {
  name: Create order
  type: http
  seq: 2
}

post {
  url: {{baseUrl}}/orders
  body: json
  auth: none
}

body:json {
  {
    "customer_name": "Asha",
    "phone": "9876543210",
    "items": [
      {"item_id": "espresso", "qty": 2},
      {"item_id": "croissant", "qty": 1}
    ]
  }
}

assert {
  res.status: eq 201
  res.body.total: eq 390
  res.body.status: eq received
}

script:post-response {
  bru.setVar("orderId", res.body.id);
}

After the response, bru.setVar stores the order id as a runtime variable called orderId.

Create Get order: GET {{baseUrl}}/orders/{{orderId}}. Because the create request ran first and saved orderId, the URL now works. Add a test that reads the variable back:

assert {
  res.status: eq 200
  res.body.customer_name: eq Asha
}

tests {
  test("it is the order we created", function () {
    expect(res.body.id).to.equal(bru.getVar("orderId"));
  });
}

Runtime variables set with bru.setVar are read with bru.getVar, or as {{orderId}} inside a URL or body.

Add a request Bad phone: POST {{baseUrl}}/orders with the phone set to 12345, and an assertion res.status eq 422. Add another, Unknown order: GET {{baseUrl}}/orders/does-not-exist with res.status eq 404.

Think of each failing request as a guard. If someone later weakens the validation, the test turns red.

The Bruno CLI runs a collection without the app. Install it once, then run it from inside the collection folder (the one containing bruno.json).

npm install -g @usebruno/cli
cd brew-bean-tests
bru run --env Local

Runs every request in the folder against the Local environment and prints a pass/fail summary. The exit code tells CI whether the run passed.

The exact layout of the summary depends on the CLI version, but you should see passes and totals at the end. To run a single request, give its file name: bru run "Get menu.bru" --env Local. To run one sub-folder, pass its path.

Put the collection folder in your project's Git repository. Now:

- A teammate adding a test shows up in a pull request as a few readable lines in one file. - The tests live in the same repo as the code, so a change to the API and its tests ship together. - CI can run bru run --env Local on every push (a later lesson sets this up with GitHub Actions). - There is no shared account or cloud workspace to manage.

Convert this curl command into a Bruno .bru request file. Include meta (name, type http, seq), the method block with the URL using {{baseUrl}}, the body block, and an assert block that checks the status code is [expected status] and the main fields of the response.

[paste curl command]

What to expect: Compare with the examples in this lesson. Check the block names (get/post, body:json, assert, tests) and that the values match what your API really returns. If Bruno cannot open the file, fix the syntax by creating the same request in the app and comparing.