Quickstart

In this tutorial, we’ll install Axx, create a project, and write a scenario that tests a small web server running on your machine. We’ll run it and watch it pass, then break it on purpose to see what a failure looks like.

It takes about ten minutes. You’ll need a terminal, Go 1.27 or newer to install Axx, and Python 3, which we’ll use as the web server.

Install Axx

Install Axx with Go:

go install github.com/nimbusxr/axx/cmd/axx@latest

Check that your shell finds it:

axx version

Axx prints its version. If your shell says command not found, add Go’s bin directory to your PATH (export PATH="$PATH:$(go env GOPATH)/bin") and try again.

Create a project

Make a directory for the project and let Axx set it up:

mkdir hello-axx
cd hello-axx
axx init

axx: preparing rest (once; cached for later runs)
axx: ready in 31s
  create  axx.yaml
  create  axx-packs.yaml
  create  features/smoke/smoke.feature
  create  .github/workflows/acceptance.yml
  create  AGENTS.md
  create  .gitignore
  create  .gitattributes
  create  .agents/skills (5 skills)

Codex keeps its MCP servers in ~/.codex/config.toml; `axx mcp install --agent codex --scope user` adds axx there.
next: put your service's command, port and health check in axx.yaml and the smoke feature, then `axx doctor` and `axx run`

Axx created a configuration file, axx.yaml, and a first feature file, features/smoke/smoke.feature. We’ll change both. It also created axx-packs.yaml, the list of the packs of steps the project uses. It lists rest, whose steps send HTTP requests, and that’s all we need. The first time, Axx prepared itself with that pack, which it won’t need to do again. We won’t need the other files in this tutorial: they are for CI and for coding agents.

Give the web server something to serve

Our web server will serve the files in this directory. Create a small JSON file for it:

echo '{"message": "Hello, axx"}' > hello.json

Tell Axx how to start the server

Open axx.yaml. At the bottom, replace the whole services: section with this one:

axx.yaml

services:
  hello-axx:
    command: python3 -m http.server 8000
    ready:
      http:
        url: http://${sys:local.host}:8000/

Axx now knows how to start the server, and how to tell when it’s ready: when http://localhost:8000/ answers.

Write the scenario

Replace everything in features/smoke/smoke.feature with:

features/smoke/smoke.feature

Feature: Hello axx

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

  Scenario: The service says hello
    Given a GET request to /hello.json
    When the request is executed
    Then the response status code is 200
    And the response payload property message is 'Hello, axx'

Every line is a step Axx already knows. The Background registers the server as a service named hello-axx. The scenario sends it a request and checks the answer.

Check the scenario

Before running anything, ask Axx to check every line:

axx validate

1 file, 1 scenario, 5 steps: ok

Axx matched each line to one of its steps, without starting the server.

Run it

axx run

axx: starting hello-axx (logs: .axx/logs/services.log)
Feature: Hello axx

  Scenario: The service says hello  # features/smoke/smoke.feature:7
    ✓ Given the hello-axx service with the following properties:  (background)
        | url | http://${sys:local.host}:8000 |
    ✓ Given a GET request to /hello.json
    ✓ When the request is executed
        log: GET http://localhost:8000/hello.json -> 200 OK (4ms, 26 bytes)
        attachment: response body (application/json, 26 B)
          {"message": "Hello, axx"}
    ✓ Then the response status code is 200
    ✓ And the response payload property message is 'Hello, axx'

1 scenario (1 passed)
5 steps (5 passed)
Finished in 4ms

Notice what happened. Axx started the web server, waited until it answered, ran the scenario, and stopped the server again. Under the request step, the log: line shows the request Axx sent, and the attachment shows the response it got back.

Break it on purpose

Change the last line of features/smoke/smoke.feature so it expects a different message:

    And the response payload property message is 'Hello, world'

Run it again:

axx run

axx: starting hello-axx (logs: .axx/logs/services.log)
Feature: Hello axx

  Scenario: The service says hello  # features/smoke/smoke.feature:7
    ✓ Given the hello-axx service with the following properties:  (background)
        | url | http://${sys:local.host}:8000 |
    ✓ Given a GET request to /hello.json
    ✓ When the request is executed
        log: GET http://localhost:8000/hello.json -> 200 OK (2ms, 26 bytes)
        attachment: response body (application/json, 26 B)
          {"message": "Hello, axx"}
    ✓ Then the response status code is 200
    ✗ And the response payload property message is 'Hello, world'
        Response payload property message is not Hello, world
          expected: "Hello, world"
          actual:   "Hello, axx"

Failed scenarios:
  ✗ The service says hello  # features/smoke/smoke.feature:7
      rerun: axx run features/smoke/smoke.feature:7

1 scenario (1 failed)
5 steps (1 failed, 4 passed)
Finished in 3ms

Axx marks the step that failed and shows what it expected next to what it got. It also prints a command that reruns only this scenario.

Change the line back to 'Hello, axx' and run axx run once more. The scenario passes again.

What you’ve done

You installed Axx, told it how to start a service, wrote a scenario, ran it, and read a failure. That’s the loop you’ll use with every Axx suite.

Next, in Your first suite, we’ll test a real service with a database and a dependency it calls.