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

axx

module
v0.1.0 Latest Latest
Warning

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

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

README

axx

Status: pre-release. axx is being built toward its first public beta, v0.1.0. Until then, interfaces may change without notice. 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
PASS 1  FAIL 0  SKIP 0  0.4s

examples/parcels is a complete suite for a parcel-delivery service: its API and OpenAPI contract, a mocked dependency, PostgreSQL, MongoDB and Kafka. 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, and the logs your services write (files, syslog, TCP and HTTP).
  • 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 installable agent skills (axx skills install).
  • 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

Pre-release builds (the stable channels below go live with v0.1.0):

go install github.com/nimbusxr/axx/cmd/axx@latest     # from source

Coming with v0.1.0: brew install nimbusxr/tap/axx, curl -fsSL https://axx.nimbusxr.us/install.sh | sh, ghcr.io/nimbusxr/axx, and the nimbusxr/setup-axx GitHub Action.

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
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 the cloud service packs in tests, against local cloud emulators started in containers.
 Package cloudtest runs the steps of the cloud service packs in tests, against local cloud emulators started in containers.
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.
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, and the maps from validation keys (validation.request.body.schema.required, ...) to levels.
 Package oaslevel holds OpenAPI validation levels: the ERROR, WARN, INFO and IGNORE a finding is reported at, and the maps from validation keys (validation.request.body.schema.required, ...) to levels.
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.
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).

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.