DEV Community

Alex Shev
Alex Shev

Posted on Originally published at terminalskills.io

Stop Testing APIs by Hand. Give Your AI Agent a Bruno Workflow.

#api #testing #devtools #ai

Most API testing workflows break in a boring way.

Not because the team does not care about testing.

Not because nobody knows how to send a request.

Because the API workflow lives in too many places at once.

One developer has a Postman collection.
Another has a few curl commands in shell history.
The backend repo has environment variables in .env.example.
CI has a smoke test that only checks one endpoint.
The docs say one thing.
The staging API behaves slightly differently.

Then an AI coding agent enters the repo and gets asked:

Can you check this API flow?
Enter fullscreen mode Exit fullscreen mode

The agent can read code.
It can write tests.
It can generate curl commands.
It can explain HTTP status codes.

But it still has the same problem a new human has.

Where is the API workflow?

If the answer is "somewhere in a GUI tool, someone's local history, and a few scattered docs," the agent has to reconstruct the whole thing from scratch.

That is not a tool problem.

That is a workflow packaging problem.

API collections should live near the code

This is why I like Bruno.

Bruno is an open-source API client that stores collections as plain text files in your Git repository.

That detail matters more than the UI.

If your API collection lives next to the application code, it becomes part of the engineering system:

  • request changes show up in pull requests
  • environment files can be reviewed
  • auth flows can be documented as runnable requests
  • test assertions can live with the request that needs them
  • CI can run the same collection humans use locally
  • new team members can learn the API by running the collection

The collection is not a private artifact hidden in a synced workspace.

It is a repo artifact.

That changes what an AI agent can do with it.

The real unit is not a request

A single API request is easy.

The useful workflow is usually a sequence:

  1. Login.
  2. Save the token.
  3. Create a resource.
  4. Read it back.
  5. Update it.
  6. Verify the response shape.
  7. Clean up or test the failure path.

When developers test this manually, they often remember the sequence in their head.

That works until the API changes.

It works until staging has different data.

It works until someone else needs to debug the same flow.

It works until an agent has to run it and cannot rely on tribal memory.

The important thing to encode is not:

Send a POST request.
Enter fullscreen mode Exit fullscreen mode

It is:

This is the auth flow.
These variables move from one request to the next.
These assertions prove the contract still works.
This command runs the flow in CI.
Enter fullscreen mode Exit fullscreen mode

That is where Bruno's file-based model becomes useful.

A .bru request can contain the request metadata, headers, body, scripts, and tests in a human-readable format.

An environment file can define baseUrl, test users, and secret placeholders.

Post-response scripts can save values for later requests.

The CLI can run the collection:

bru run --env staging
Enter fullscreen mode Exit fullscreen mode

or a folder:

bru run auth/ --env dev
Enter fullscreen mode Exit fullscreen mode

or output CI-friendly results:

bru run --env dev --output results.xml --format junit
Enter fullscreen mode Exit fullscreen mode

That is a much better artifact for an agent than a vague instruction like:

Test the API.
Enter fullscreen mode Exit fullscreen mode

What an AI agent should not improvise

I do not want an agent inventing an API testing workflow every time.

That is how you get impressive-looking activity and weak verification.

The agent might:

  • hit the happy path only
  • test against the wrong environment
  • forget auth state
  • use fake data that bypasses the real bug
  • skip assertions and only report that the request returned something
  • paste a curl command that nobody ever runs again

None of those failures look dramatic.

They look like work.

The agent says:

I tested the endpoint.
Enter fullscreen mode Exit fullscreen mode

But the team has no durable artifact, no diff, no reusable flow, and no CI hook.

That is the wrong end state.

For API work, I want the agent to leave behind something the repo can keep.

A better Bruno workflow for agents

The workflow I would want from an AI coding agent looks like this.

1. Discover the API surface

The agent should inspect routes, controllers, OpenAPI specs if they exist, existing tests, and any current API docs.

The output should be a short map:

  • auth endpoints
  • core resources
  • destructive actions
  • environment assumptions
  • test data requirements
  • flows that need chained state

No collection changes yet.

First understand the shape.

2. Create a Git-friendly collection structure

The collection should mirror the API, not the agent's thought process.

For example:

api-collection/
  bruno.json
  environments/
    dev.bru
    staging.bru
  auth/
    login.bru
    refresh-token.bru
  users/
    list-users.bru
    get-user.bru
    create-user.bru
  orders/
    create-order.bru
    process-refund.bru
Enter fullscreen mode Exit fullscreen mode

That structure is boring on purpose.

People can navigate it.

Agents can navigate it.

Reviewers can diff it.

3. Encode variables and secrets correctly

Environment files should carry normal config like:

baseUrl: http://localhost:3000
testEmail: test@example.com
Enter fullscreen mode Exit fullscreen mode

Secrets should be marked as secrets and not committed as plain values.

This is one of the places where an agent needs a rule, not vibes.

If a tool can run requests, it can also leak credentials by accident.

So the workflow has to define where config lives, which values can be committed, and what must stay local or injected by CI.

4. Chain requests deliberately

Many real API tests are stateful.

Login returns a token.

Create user returns an ID.

Create order depends on the user.

Refund depends on the order.

The agent should not fake those IDs when it can capture them from the real response.

That is where post-response scripts are useful.

The point is not clever scripting.

The point is making the API flow executable instead of explanatory.

5. Put assertions next to the request

A request without assertions is only a smoke signal.

The agent should add tests for the contract that matters:

  • status code
  • required fields
  • expected types
  • auth behavior
  • error shape
  • permission boundaries
  • idempotency or retry behavior when relevant

The test should answer:

What would make this endpoint unsafe to ship?
Enter fullscreen mode Exit fullscreen mode

Not:

Did the server return any JSON?
Enter fullscreen mode Exit fullscreen mode

6. Add a CI command

The workflow is not done until there is a command the team can run again.

For example:

bru run --env staging
Enter fullscreen mode Exit fullscreen mode

or:

bru run auth/ users/ --env ci --output results.xml --format junit
Enter fullscreen mode Exit fullscreen mode

The exact command depends on the project.

But the artifact should be clear enough that a developer, CI job, or future agent can repeat the same check.

Where Terminal Skills fits

This is exactly the kind of workflow that belongs in a skill.

The Terminal Skills catalog has a bruno skill for AI agents:

Bruno on Terminal Skills

The useful part is not "the agent has heard of Bruno."

That is not enough.

The useful part is giving the agent an operating procedure:

  • use Bruno as a Git-first API testing tool
  • store collections as reviewable repo files
  • organize requests by API structure
  • use environment files for config
  • keep secrets out of committed values
  • write assertions in requests
  • chain state between calls intentionally
  • run collections through the Bruno CLI
  • treat the collection as living API documentation

Install for Codex:

npx terminal-skills install bruno --agent codex
Enter fullscreen mode Exit fullscreen mode

Install for Gemini CLI:

npx terminal-skills install bruno --agent gemini
Enter fullscreen mode Exit fullscreen mode

Install for Claude Code:

npx terminal-skills install bruno
Enter fullscreen mode Exit fullscreen mode

The broader point is simple:

If an agent is going to touch your API workflow, do not ask it to improvise testing.

Give it a repeatable workflow it can follow, edit, run, and leave behind.

Why this matters for API teams

API testing is one of those areas where AI can create false confidence quickly.

An agent can generate a convincing explanation of an endpoint.

It can generate sample requests.

It can say the test passed.

But unless the workflow leaves a durable artifact, the value disappears after the chat.

The better outcome is:

  • the Bruno collection was updated
  • the change is visible in Git
  • the request has assertions
  • the environment is explicit
  • the command can run locally
  • CI can run it later
  • the next agent does not need to rediscover the flow

That is the difference between assistance and operational memory.

The agent did not just test the API.

It improved how the team tests the API.

My practical checklist

If I were reviewing an agent-generated Bruno workflow, I would ask:

  • Does the collection live in the repo?
  • Does the folder structure match the API shape?
  • Are environments separated cleanly?
  • Are secrets marked and excluded from committed values?
  • Do important requests include assertions?
  • Are auth tokens and IDs passed through real response state?
  • Can the collection run from the CLI?
  • Is there a CI-ready command?
  • Would a new teammate understand the API faster after reading and running it?

If the answer is yes, the agent left behind something useful.

If the answer is no, it probably just tested by hand with extra steps.

The broader lesson

AI agents are good at producing one-off work.

Engineering teams need repeatable work.

That is the gap skills are meant to close.

For API testing, the difference is especially visible.

Do you want the agent to send a request once?

Or do you want it to build the API workflow your team can keep using?

That is why Bruno is a good fit for Terminal Skills.

It turns API testing into files, diffs, commands, and checks.

And those are exactly the kinds of artifacts agents can use without asking everyone to trust a chat transcript.

Disclosure: AI assistance was used to draft and edit this article.

Top comments (4)

Collapse
 
coridev profile image
Cor E •

Hi Alex,

Really novel idea and an excellent approach. This idea that code snippets and tools, notes, etc. living in all those different places really hit home for me. I used to work on a team supporting Sun Solaris and there were about 30 of us. It was pretty much exactly as you described.

This idea of Bruno really simplifies things if people would all use it. I've come up with some really cool tools in my day but found you have to make it work with their workflow naturally so they would actually pick it up and use it.

Is Bruno yours?

Cheers!

Collapse
 
alexshev profile image
Alex Shev •

Thanks, Cor. Bruno is not mine; it is an open-source API client/workflow tool. What I like is exactly what you pointed out: it only works if it fits how teams already test and document APIs. The agent angle is about making that existing workflow reusable instead of inventing a parallel one.

Collapse
 
adeutou profile image
adeutou •

Hi Alex,

Great article! I really resonate with the core insight: the "workflow packaging problem" is what prevents AI agents from delivering reliable verification.

Following up on Cor's point about adoption and fitting existing developer workflows, I see a few practical considerations when putting this into production:

OpenAPI/Code-first alignment: For teams already auto-generating OpenAPI/Swagger specs from code (e.g., Spring Boot, NestJS, FastAPI), where do you see the boundary? Should the AI agent bootstrap/update the .bru collection directly from the OpenAPI spec, or extract it strictly by inspecting controller code?

State & Database Teardown: Stateful flows (Auth -> Create -> Refund) are great, but in CI environments, an unhandled failure mid-sequence can pollute test databases. Pairing bru run with explicit DB seeding/reset hooks seems essential to keep runs idempotent.

Secret Hygiene: Since agents have write access to repo files, establishing hard boundaries against committing resolved environment secrets into .bru files is crucial especially in team/CI settings.

Making the API workflow a first-class Git artifact is definitely the right move to bridge the gap between human context and AI execution. Thanks for sharing!

Collapse
 
heinrichneb profile image
Heinrich Neb •

"AI agents are good at producing one-off work. Engineering teams need repeatable work." — that's the clearest statement of the problem I've read, and it's why I keep coming back to your posts.

One layer I'd add to your review checklist, learned the expensive way: the assertions rot too.

A committed collection with assertions is a durable artifact right up until one of those assertions quietly stops being able to fail. We measured this on our own gates last week — for every check, when did it last reject something?

typecheck   192 runs  127 rejections   4 days ago
testTask     64 runs    0 rejections   never
Enter fullscreen mode Exit fullscreen mode

testTask skipped itself when a task had no acceptance file, and that skip was recorded as a pass. 50 of 64 runs tested nothing and reported green. The artifact was in the repo, reviewable, diffable, CI-wired — and wrong.

So I'd add one line to your list: does any assertion here still fail when the contract breaks? Your own denied-cases instinct from the gates thread is the answer — known-bad fixtures, committed next to the request. Then "the collection is green" means something.