NATS

Publish messages to NATS subjects, and check the messages your services publish on subjects and into JetStream streams.

Register the server once, usually in the Background; every NATS step of the scenario uses it:

Given the tracking nats server with the following properties:
  | url   | nats://localhost:4222 |
  | token | ${env:NATS_TOKEN}     |

Steps name a subject or a stream: the deliveries.confirmed nats subject, the TRACKING nats stream. Messages carry headers (with the following headers:, and header <name> rows in checks). A message published to a subject a stream captures is published through JetStream, and the step waits for the stream to store it.

• A subject check subscribes for the run: for the subjects a run checks, Axx subscribes once the services are up. A subject in a check can have the wildcards * and >: the tracking.> nats subject, and a subject row checks the subject a message came on.
• A stream check reads only what is new: for the streams a run checks, Axx reads each with an ordered consumer of its own that starts with the messages stored after the services are up, so what earlier runs stored never counts. It takes nothing from the stream’s other consumers; a work-queue stream allows no other consumer, so check its subject instead.
• A check only looks at the messages received since its scenario started, so scenarios running in parallel check their own messages, by data unique to them.
• Secrets stay secret: ${env:..} values in the properties are masked in logs and failures.

Add it to a project with axx pack add nats.

Steps

nats.server

Given the {word} nats server with the following properties:
  | property | value |

The table may start with the row naming its columns, as above, or go straight to its rows.

Register the NATS server the steps talk to.

• The first server registered is the one the scenario’s NATS steps use.
• Give it at most one of a token, a username and password, and creds.
• Values expand ${env:..} and ${sys:..}; ${env:..} values are masked.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101

Property	Takes
url	the server’s URL, nats://host:4222 or tls:// for TLS; several, separated by commas, for a cluster
token	the token Axx connects with, like ${env:NATS_TOKEN}
username	the user Axx connects as
password	its password
creds	a credentials file (JWT and seed), relative to the directory of axx.yaml
asyncapi	an AsyncAPI document, a file of the project or a URL, that the subjects follow: every message a scenario sends there, and every message a check finds, is checked against it (with the asyncapi pack)

Example:

Given the tracking nats server with the following properties:
  | url | nats://localhost:4222 |
Given the tracking nats server with the following properties:
  | url   | tls://nats.parcels.example:4222 |
  | creds | nats/axx.creds                  |

Since 0.1.5.

nats.subject.send

When a message is published to the {word} nats subject:
  """
  ...
  """

Send a message to the nats subject; the doc string is its body.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101

Example:

When a message is published to the deliveries.confirmed nats subject:
  """
  {"reference": "PX-8301", "signedBy": "H. Wolf", "deliveredAt": "2026-09-28T10:12:00Z"}
  """

Since 0.1.5.

nats.subject.send.file

When the {filepath} message is published to the {word} nats subject[[ with the following headers:]]

Send a message whose body is the file to the nats subject, with the headers of the table when the step has one.

Parameter	Takes	For example
{filepath}	a file of the project: a path relative to the feature file’s directory, the resources directories or axx.yaml’s directory (looked for in that order), or an absolute path, quoted when it has a space	seeds/parcels.yaml, kafka/scan-delivered.json
{word}	one word, with no spaces	parcels, PX-4101

Each row is a header sent with the message, as text: its name and its value.

Variants, the parts in [[...]] said or left out:

• the {filepath} message is published to the {word} nats subject
• the {filepath} message is published to the {word} nats subject with the following headers:

Example:

When the nats/delivery-confirmed.json message is published to the deliveries.confirmed nats subject
When the nats/delivery-confirmed.json message is published to the deliveries.confirmed nats subject with the following headers:
  | courier | CR-LEJ-12 |

Since 0.1.5.

nats.subject.received

Then [[within {duration} ]]the {word} nats subject has a message where:
  | path | value |

The table may start with the row naming its columns, as above, or go straight to its rows.

Check that the nats subject has a message with those values, received since the scenario started.

• The check waits for it: 10 seconds, or within {duration}.
• Axx subscribes to a subject it checks for the run.

Parameter	Takes	For example
{duration}	a duration in seconds (s) or minutes (m)	5s, 2m
{word}	one word, with no spaces	parcels, PX-4101

Each row is a path into the message’s JSON body (a field name, a dotted path or a JSONPath) and the value it has, compared as text: null for null and undefined for absent. A row header <name> is instead on the header of that name sent with the message: undefined when there is none. A row subject is on the message itself, not its body.

Variants, the parts in [[...]] said or left out:

• the {word} nats subject has a message where:
• within {duration} the {word} nats subject has a message where:

Example:

Then within 30s the tracking.> nats subject has a message where:
  | subject       | tracking.PX-8301 |
  | status        | DELIVERED        |
  | header source | courier          |

Since 0.1.5.

nats.stream.received

Then [[within {duration} ]]the {word} nats stream has a message where:
  | path | value |

The table may start with the row naming its columns, as above, or go straight to its rows.

Check that the nats stream has a message with those values, received since the scenario started.

• The check waits for it: 10 seconds, or within {duration}.
• Axx reads a stream it checks with an ordered consumer of its own, from the messages stored after the services are up.

Parameter	Takes	For example
{duration}	a duration in seconds (s) or minutes (m)	5s, 2m
{word}	one word, with no spaces	parcels, PX-4101

Each row is a path into the message’s JSON body (a field name, a dotted path or a JSONPath) and the value it has, compared as text: null for null and undefined for absent. A row header <name> is instead on the header of that name sent with the message: undefined when there is none. A row subject is on the message itself, not its body.

Variants, the parts in [[...]] said or left out:

• the {word} nats stream has a message where:
• within {duration} the {word} nats stream has a message where:

Example:

Then within 30s the TRACKING nats stream has a message where:
  | subject | tracking.PX-8302 |
  | status  | OUT_FOR_DELIVERY |

Since 0.1.5.