Test with an agent

In this tutorial, we’ll give a coding agent an acceptance criterion in plain words and watch it write a scenario, check it and run it with Axx. Then we’ll review what it wrote.

We’ll use Claude Code and the hello-axx project from the Quickstart. You’ll need both.

Teach the agent Axx

axx init installed Axx’s skills in .agents/skills in the Quickstart. The hello-axx directory had no sign of Claude Code then, so connect it now. In the hello-axx directory, give Claude Code the Axx MCP server and link the skills where it reads them:

axx mcp install --agent claude
axx skills install

create .mcp.json: the axx MCP server for Claude Code
installed 5 skills to .agents/skills (0 files updated)
linked for Claude Code in .claude/skills

The skills teach an agent how to find Axx’s steps, write a scenario, run it and read a failure. The MCP server gives it tools to do so, and the AGENTS.md that axx init wrote points agents at the same rules. In a repository that already uses Claude Code, axx init does all of this itself.

Ask for a test

Start Claude Code in the project:

claude

It asks whether to use the axx server from .mcp.json; allow it.

Give it the criterion, not step text:

Add an acceptance test for this: asking for a file that doesn't exist returns 404. Use axx, and run it.

Watch what it does

The agent’s wording will differ from run to run, but you’ll see it work through the same loop. Claude Code asks before each command and each tool call, so you can follow along. Notice that it:

1. reads the project’s steps with the steps_search tool (or axx steps) instead of guessing their text;
2. checks a line it’s unsure of with step_explain (axx explain);
3. writes a feature file;
4. starts the server with env (axx up), runs the scenarios with scenarios_run (axx run --compact), which also reports what axx validate and axx lint find, and stops the server again.

Review what it wrote

Open the feature file the agent created. In our run it was features/missing-file.feature:

features/missing-file.feature

Feature: Missing files
  Asking for a file the service does not have is answered with Not Found.

  Background:
    Given the hello-axx service with the following properties:
      | url | http://${sys:local.host}:8000 |

  Scenario: Asking for a file that does not exist returns 404
    Given a GET request to /no-such-file-404.json
    When the request is executed
    Then the response status code is 404

Read it against the criterion you gave. Each line says what it checks, so you can tell at a glance whether the agent tested what you asked for. That review is the part that stays yours.

Run it yourself

axx run

The end of the output shows both scenarios, the Quickstart’s and the agent’s:

2 scenarios (2 passed)
9 steps (9 passed)

What you’ve done

You gave an agent a criterion in plain words. It found the steps, wrote the scenario, checked it and ran it, and you confirmed it by reading it.

Set up agents connects other agents and Axx’s MCP server, and Axx for agents explains why Axx works this way.