Help us shape the future of Go! Take the 2026 Go Developer Survey

axx

module
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 27, 2026 License: Apache-2.0

README

axx

Status: beta. Every 0.x release is a GitHub pre-release: until v1.0.0, flags and configuration may change between minor versions. Step text never changes. Nightly builds are published from main.

axx ("axxeptance") is human-readable acceptance testing for the agentic era. Your acceptance criteria become the tests: scenarios that people can read and coding agents can write, run black-box against the services you build, fast on a laptop and fast in CI.

Feature: Price quotes

  Background:
    Given the parcels service with the following properties:
      | url     | http://localhost:8400              |
      | openapi | http://localhost:8400/openapi.json |

  Scenario: Express delivery abroad
    Given a POST request to /api/quotes
    And a request payload using an application/json content example named 'Express abroad'
    When the request is executed
    Then the response status code is 200
    And the response payload properties are:
      | zone         | FR-1 |
      | priceCents   | 1790 |
      | deliveryDays | 2    |

$ axx run --compact
PASS 1  380ms

examples/parcels is a complete suite for a parcel-delivery service: its API and OpenAPI contract, a mocked dependency, PostgreSQL, MongoDB and Kafka, the logs it writes, the files it exports and its shop portal in real browsers. Three more examples test services built on the clouds, with the clouds running locally:

Why axx

  • One small binary. No JVM, Gradle or test-runner wiring. axx run starts your apps, waits until they're healthy, runs scenarios in parallel, and cleans up afterwards.
  • Batteries included. REST with OpenAPI request/response validation, WireMock verification, SQL (PostgreSQL first-class; MySQL, SQLite and SQL Server supported), MongoDB, Kafka with Avro + Schema Registry, the logs your services write (files, syslog, TCP and HTTP), and the files they write: the text of a PDF, Word document or spreadsheet, the rows of a CSV or Excel file.
  • Web apps in real browsers. Open pages, fill in forms, click buttons, answer dialogs, download files and check what the page shows, in Chromium, Firefox or WebKit through Playwright, as a desktop or a phone; then check in the same scenario what your service stored and published. Watch the browsers as they go, pause a scenario in Playwright's Inspector, and record what you do on the page as steps. Compare screenshots, audit accessibility, control what pages fetch, check Lighthouse scores and measure JavaScript coverage with the packs that build on it.
  • The clouds your services run on. S3, SQS, SNS, EventBridge and DynamoDB on AWS; Cloud Storage, Pub/Sub, BigQuery and Firestore on Google Cloud; Blob Storage and Service Bus on Azure. Every pack talks to the real service through its official SDK, so the same features run against a cloud account or a local emulator.
  • Extensible. Pick the packs a project uses (axx pack add rest sql), write your own steps as a Go pack that works on the same context as the steps of axx's packs (axx pack new ./steps).
  • Built for agents. axx steps search, axx explain, --json on every command, stable exit codes, an MCP server (axx mcp) and agent skills, which axx init sets up for the agents a repository uses.
  • Test data you can trust. axx lint catches colliding test data before parallel runs flake, and axx fixtures generates schema-checked fixtures and detects drift.

Install

brew install nimbusxr/tap/axx                          # Homebrew (macOS, Linux)
curl -fsSL https://axx.nimbusxr.us/install.sh | sh     # install script (Linux, macOS)
go install github.com/nimbusxr/axx/cmd/axx@latest      # from source

On Windows: irm https://axx.nimbusxr.us/install.ps1 | iex. There are also the container image ghcr.io/nimbusxr/axx, the nimbusxr/setup-axx GitHub Action, and the archives on GitHub releases, with a rolling nightly built from main.

Documentation

https://axx.nimbusxr.us, with a Markdown copy of every page for agents and llms.txt.

Contributing

axx is Apache-2.0 licensed and welcomes contributions. See CONTRIBUTING.md (DCO sign-off required) and AGENTS.md if you work with a coding agent. Report security issues privately; see SECURITY.md.

Directories

Path Synopsis
Package app runs the axx command line.
 Package app runs the axx command line.
cmd
axx command
Command axx runs human-readable acceptance tests against services.
 Command axx runs human-readable acceptance tests against services.
Package core is the public API for axx step packs.
 Package core is the public API for axx step packs.
internal
agents
Package agents connects coding agents to axx: it finds the agents a project uses and adds the axx MCP server to the configuration they read, merged into what is there, never replacing it.
 Package agents connects coding agents to axx: it finds the agents a project uses and adds the axx MCP server to the configuration they read, merged into what is there, never replacing it.
avrojson
Package avrojson reads and writes Avro values the way the Apache Avro Java library does, for the steps and tools that exchange Avro data with people: payload files written in Avro's JSON encoding, and assertions over the text Java printed for a record.
 Package avrojson reads and writes Avro values the way the Apache Avro Java library does, for the steps and tools that exchange Avro data with people: payload files written in Avro's JSON encoding, and assertions over the text Java printed for a record.
axxerr
Package axxerr provides axx's structured error type.
 Package axxerr provides axx's structured error type.
check
Package check matches the steps of parsed feature files against a step registry and reports every step that cannot run: undefined, ambiguous, or given the wrong argument.
 Package check matches the steps of parsed feature files against a step registry and reports every step that cannot run: undefined, ambiguous, or given the wrong argument.
cli
Package cli wires axx's command-line interface.
 Package cli wires axx's command-line interface.
cloudstep
Package cloudstep holds what the cloud service packs share: waiting for something the services under test do asynchronously, matching rows, items, documents and messages against a step's table with the text comparison of the other packs' JSON property steps, and reading seed files.
 Package cloudstep holds what the cloud service packs share: waiting for something the services under test do asynchronously, matching rows, items, documents and messages against a step's table with the text comparison of the other packs' JSON property steps, and reading seed files.
cloudstep/cloudtest
Package cloudtest runs the steps of packs in tests, as a run does: the cloud service packs against local cloud emulators, the web pack against a site the test serves.
 Package cloudtest runs the steps of packs in tests, as a run does: the cloud service packs against local cloud emulators, the web pack against a site the test serves.
compat/internal/oracletest
Package oracletest loads the behavior oracles in testdata/oracles and compares Go results against them.
 Package oracletest loads the behavior oracles in testdata/oracles and compares Go results against them.
compat/javafmt
Package javafmt reproduces how Java renders and parses numbers and values, so text axx produces matches what Java produces for the same value.
 Package javafmt reproduces how Java renders and parses numbers and values, so text axx produces matches what Java produces for the same value.
compat/javare
Package javare implements Java (java.util.regex) regular expressions on top of github.com/dlclark/regexp2, a pure-Go backtracking engine.
 Package javare implements Java (java.util.regex) regular expressions on top of github.com/dlclark/regexp2, a pure-Go backtracking engine.
compat/jsonx
Package jsonx reads, queries and modifies JSON exactly as Jayway JsonPath 2.9.0 does on top of json-smart 2.5.2, in their default configuration.
 Package jsonx reads, queries and modifies JSON exactly as Jayway JsonPath 2.9.0 does on top of json-smart 2.5.2, in their default configuration.
compat/jvalue
Package jvalue holds the value semantics the step packs share: how the text of a feature file becomes typed values, how they are compared, and how values render back to text.
 Package jvalue holds the value semantics the step packs share: how the text of a feature file becomes typed values, how they are compared, and how values render back to text.
compat/jyaml
Package jyaml reads and writes YAML exactly like Jackson's YAML dataformat on top of SnakeYAML.
 Package jyaml reads and writes YAML exactly like Jackson's YAML dataformat on top of SnakeYAML.
config
Package config defines and loads axx.yaml.
 Package config defines and loads axx.yaml.
config/internal/genschema command
Command genschema writes the axx.yaml JSON Schema generated from the Go types.
 Command genschema writes the axx.yaml JSON Schema generated from the Go types.
engine
Package engine assembles configuration, step packs, the match registry and the shared suite.
 Package engine assembles configuration, step packs, the match registry and the shared suite.
exitcode
Package exitcode defines axx's process exit codes.
 Package exitcode defines axx's process exit codes.
feature
Package feature loads Gherkin feature files and compiles them to pickles.
 Package feature loads Gherkin feature files and compiles them to pickles.
filecontent
Package filecontent reads what a file holds, by its type: the text of a plain text, CSV, TSV, JSON, XML, HTML, PDF, Word (.docx) or Excel (.xlsx) file, and the table of a CSV, TSV or Excel file.
 Package filecontent reads what a file holds, by its type: the text of a plain text, CSV, TSV, JSON, XML, HTML, PDF, Word (.docx) or Excel (.xlsx) file, and the table of a CSV, TSV or Excel file.
fixtures
gotool
Package gotool provides the Go toolchain axx builds itself with when a project lists packs.
 Package gotool provides the Go toolchain axx builds itself with when a project lists packs.
ide
Package ide generates IDE run and debug configurations from axx.yaml, so debugging an app under test is one click in IntelliJ or VS Code.
 Package ide generates IDE run and debug configurations from axx.yaml, so debugging an app under test is one click in IntelliJ or VS Code.
interp
Package interp expands ${prefix:name} references in strings.
 Package interp expands ${prefix:name} references in strings.
jsonassert
Package jsonassert implements the JSON property assertions shared by the packs: JSONPath lookups with Jayway semantics and text comparison of scalars.
 Package jsonassert implements the JSON property assertions shared by the packs: JSONPath lookups with Jayway semantics and text comparison of scalars.
lifecycle
Package lifecycle starts and stops the applications under test.
 Package lifecycle starts and stops the applications under test.
lint
Package lint implements `axx lint`: test-data isolation rules plus builtin feature-file checks.
 Package lint implements `axx lint`: test-data isolation rules plus builtin feature-file checks.
lsp
Package lsp is axx's language server (`axx lsp`).
 Package lsp is axx's language server (`axx lsp`).
match
Package match compiles step definitions into Cucumber expressions and matches step text against them.
 Package match compiles step definitions into Cucumber expressions and matches step text against them.
mcp
Package mcp serves axx to coding agents over the Model Context Protocol (stdio).
 Package mcp serves axx to coding agents over the Model Context Protocol (stdio).
oaslevel
Package oaslevel holds OpenAPI validation levels: the ERROR, WARN, INFO and IGNORE a finding is reported at, the maps from validation keys (validation.request.body.schema.required, ...) to levels, and the keys a validator reports, which levels are set on (Keys).
 Package oaslevel holds OpenAPI validation levels: the ERROR, WARN, INFO and IGNORE a finding is reported at, the maps from validation keys (validation.request.body.schema.required, ...) to levels, and the keys a validator reports, which levels are set on (Keys).
packbuild
Package packbuild builds a copy of axx with a project's packs compiled in, and caches it.
 Package packbuild builds a copy of axx with a project's packs compiled in, and caches it.
packset
Package packset reads and writes axx-packs.yaml, the list of packs a project uses, and axx-packs.lock, which pins the versions of packs that come from Go modules.
 Package packset reads and writes axx-packs.yaml, the list of packs a project uses, and axx-packs.lock, which pins the versions of packs that come from Go modules.
render/md
Package md renders axx's generated reference documentation as Markdown.
 Package md renders axx's generated reference documentation as Markdown.
report
Package report implements axx's run reporters: human output (pretty, progress), the token-efficient compact and agent formats for coding agents, and the interchange formats CI systems understand (JUnit XML, Cucumber Messages, legacy Cucumber JSON and the Cucumber HTML report).
 Package report implements axx's run reporters: human output (pretty, progress), the token-efficient compact and agent formats for coding agents, and the interchange formats CI systems understand (JUnit XML, Cucumber Messages, legacy Cucumber JSON and the Cucumber HTML report).
runner
Package runner executes pickles against registered step definitions.
 Package runner executes pickles against registered step definitions.
shellwords
Package shellwords splits command lines without a shell, exactly like the original implementation: double-quoted segments become one word (quotes removed); everything else splits on whitespace.
 Package shellwords splits command lines without a shell, exactly like the original implementation: double-quoted segments become one word (quotes removed); everything else splits on whitespace.
skills
Package skills builds and installs axx's agent skills: hand-written SKILL.md files embedded in the binary plus reference files generated from the step registry at install time (so a project's custom packs are included and nothing can drift).
 Package skills builds and installs axx's agent skills: hand-written SKILL.md files embedded in the binary plus reference files generated from the step registry at install time (so a project's custom packs are included and nothing can drift).
tools/axxall command
Command axxall is axx built with every pack axx publishes.
 Command axxall is axx built with every pack axx publishes.
version
Package version reports the build version of axx.
 Package version reports the build version of axx.
packs
all
Package all lists every pack axx publishes, by name: for tests and tools that need all of them at once (the step reference, the skills).
 Package all lists every pack axx publishes, by name: for tests and tools that need all of them at once (the step reference, the skills).
aws/core
Package awscore is the aws-core pack: the AWS account the aws-* packs talk to, set up as the AWS SDK sets it up for the real services, and the SDK configuration those packs build their clients from.
 Package awscore is the aws-core pack: the AWS account the aws-* packs talk to, set up as the AWS SDK sets it up for the real services, and the SDK configuration those packs build their clients from.
aws/dynamodb
Package awsdynamodb is the aws-dynamodb pack: items seeded into DynamoDB tables and the items the services under test write.
 Package awsdynamodb is the aws-dynamodb pack: items seeded into DynamoDB tables and the items the services under test write.
aws/eventbridge
Package awseventbridge is the aws-eventbridge pack: events put on EventBridge buses and the events the services under test put there.
 Package awseventbridge is the aws-eventbridge pack: events put on EventBridge buses and the events the services under test put there.
aws/internal/queue
Package queue receives messages from SQS queues for the aws-* packs' checks: the queues the services under test write to, and the queues axx subscribes to SNS topics and EventBridge buses for a run.
 Package queue receives messages from SQS queues for the aws-* packs' checks: the queues the services under test write to, and the queues axx subscribes to SNS topics and EventBridge buses for a run.
aws/s3
Package awss3 is the aws-s3 pack: files uploaded to S3 buckets and the objects the services under test write there.
 Package awss3 is the aws-s3 pack: files uploaded to S3 buckets and the objects the services under test write there.
aws/sns
Package awssns is the aws-sns pack: messages published to SNS topics and the messages the services under test publish.
 Package awssns is the aws-sns pack: messages published to SNS topics and the messages the services under test publish.
aws/sqs
Package awssqs is the aws-sqs pack: messages sent to SQS queues and the messages the services under test send to them.
 Package awssqs is the aws-sqs pack: messages sent to SQS queues and the messages the services under test send to them.
azure/blob
Package azureblob is the azure-blob pack: files uploaded to Blob Storage containers and the blobs the services under test write there.
 Package azureblob is the azure-blob pack: files uploaded to Blob Storage containers and the blobs the services under test write there.
azure/servicebus
Package azureservicebus is the azure-servicebus pack: messages sent to Service Bus queues and topics, and the messages the services under test send there.
 Package azureservicebus is the azure-servicebus pack: messages sent to Service Bus queues and topics, and the messages the services under test send there.
files
Package files is the files pack: the files services write to a folder, such as an export directory or a volume they share with axx.
 Package files is the files pack: the files services write to a folder, such as an export directory or a volume they share with axx.
gcp/bigquery
Package gcpbigquery is the gcp-bigquery pack: rows seeded into BigQuery tables and the rows the services under test write.
 Package gcpbigquery is the gcp-bigquery pack: rows seeded into BigQuery tables and the rows the services under test write.
gcp/core
Package gcpcore is the gcp-core pack: the Google Cloud project the gcp-* packs talk to, set up as the Google Cloud client libraries are set up for the real services, and the client options those packs build their clients with.
 Package gcpcore is the gcp-core pack: the Google Cloud project the gcp-* packs talk to, set up as the Google Cloud client libraries are set up for the real services, and the client options those packs build their clients with.
gcp/firestore
Package gcpfirestore is the gcp-firestore pack: documents seeded into Firestore and the documents the services under test write.
 Package gcpfirestore is the gcp-firestore pack: documents seeded into Firestore and the documents the services under test write.
gcp/pubsub
Package gcppubsub is the gcp-pubsub pack: messages published to Pub/Sub topics and the messages the services under test publish.
 Package gcppubsub is the gcp-pubsub pack: messages published to Pub/Sub topics and the messages the services under test publish.
gcp/storage
Package gcpstorage is the gcp-storage pack: files uploaded to Cloud Storage buckets and the objects the services under test write there.
 Package gcpstorage is the gcp-storage pack: files uploaded to Cloud Storage buckets and the objects the services under test write there.
kafka
Package kafka provides the Kafka steps: services, topic clients (Java client properties translated to franz-go), event drafts published as plain text or Confluent Avro, and consumer assertions over every record of a topic.
 Package kafka provides the Kafka steps: services, topic clients (Java client properties translated to franz-go), event drafts published as plain text or Confluent Avro, and consumer assertions over every record of a topic.
logs
Package logs checks what services logged: a positive way to prove that something did not happen, by asserting the entry that says so ("line ML-KES-0413-1 rejected: duplicate reference").
 Package logs checks what services logged: a positive way to prove that something did not happen, by asserting the entry that says so ("line ML-KES-0413-1 rejected: duplicate reference").
mock
Package mock verifies requests received by WireMock mocks through the WireMock admin API.
 Package mock verifies requests received by WireMock mocks through the WireMock admin API.
mongo
Package mongo provides MongoDB steps: service registration and seeding.
 Package mongo provides MongoDB steps: service registration and seeding.
rest
Package rest provides the REST steps: service registration, requests (method and path, headers, payloads from OpenAPI examples or an empty template, payload properties, form encoding), execution with OpenAPI validation of the request and the response, and response assertions.
 Package rest provides the REST steps: service registration, requests (method and path, headers, payloads from OpenAPI examples or an empty template, payload properties, form encoding), execution with OpenAPI validation of the request and the response, and response assertions.
sql
Package sql provides database steps: services, seeds, selections (with polling and JSONB containment), JSON column assertions, row locks and before-insert trigger fault injection (PostgreSQL).
 Package sql provides database steps: services, seeds, selections (with polling and JSONB containment), JSON column assertions, row locks and before-insert trigger fault injection (PostgreSQL).
web/a11y
Package a11y is the web-a11y pack: pages people can use whatever their abilities.
 Package a11y is the web-a11y pack: pages people can use whatever their abilities.
web/core
Package web is the web-core pack: web apps used through real browsers, the way the people who use them do.
 Package web is the web-core pack: web apps used through real browsers, the way the people who use them do.
web/coverage
Package coverage is the web-coverage pack: how much of the web apps' JavaScript the scenarios ran.
 Package coverage is the web-coverage pack: how much of the web apps' JavaScript the scenarios ran.
web/coverage/internal/v8cov
Package v8cov turns the JavaScript coverage V8 counts into Istanbul's coverage and reports, as Node's tools do, byte for byte: it merges the coverage of a script taken several times as @bcoe/v8-coverage 1.0.2 does, converts a script, through its source map if it has one, as v8-to-istanbul 9.3.0 does, and merges, sums up and writes files as istanbul-lib-coverage 3.2.2 and istanbul-reports 3.2.0 do (lcovonly, json and json-summary).
 Package v8cov turns the JavaScript coverage V8 counts into Istanbul's coverage and reports, as Node's tools do, byte for byte: it merges the coverage of a script taken several times as @bcoe/v8-coverage 1.0.2 does, converts a script, through its source map if it has one, as v8-to-istanbul 9.3.0 does, and merges, sums up and writes files as istanbul-lib-coverage 3.2.2 and istanbul-reports 3.2.0 do (lcovonly, json and json-summary).
web/internal/driver
Package driver prepares the Playwright driver the web-core pack runs: a Node.js binary and the playwright-core package, laid out the way playwright-go expects (<dir>/node and <dir>/package/cli.js), patched so that Playwright's Inspector and recorder speak the web-core pack's steps (patch.go).
 Package driver prepares the Playwright driver the web-core pack runs: a Node.js binary and the playwright-core package, laid out the way playwright-go expects (<dir>/node and <dir>/package/cli.js), patched so that Playwright's Inspector and recorder speak the web-core pack's steps (patch.go).
web/lighthouse
Package lighthouse is the web-lighthouse pack: a web app's pages audited with Lighthouse, Google's tool for the quality of web pages, in the browser the scenario already uses: their performance, accessibility, best practices and SEO scores, and how fast they load by the Core Web Vitals.
 Package lighthouse is the web-lighthouse pack: a web app's pages audited with Lighthouse, Google's tool for the quality of web pages, in the browser the scenario already uses: their performance, accessibility, best practices and SEO scores, and how fast they load by the Core Web Vitals.
web/network
Package network is the web-network pack: what a web app's pages fetch, seen and changed from the browser.
 Package network is the web-network pack: what a web app's pages fetch, seen and changed from the browser.
web/screenshots
Package screenshots is the web-screenshots pack: pages that look as designed, compared with screenshots taken before, pixel by pixel.
 Package screenshots is the web-screenshots pack: pages that look as designed, compared with screenshots taken before, pixel by pixel.
plugins
axx
Package axx is axx's plugin for Claude Code.
 Package axx is axx's plugin for Claude Code.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.