MongoDB

Register MongoDB databases, seed collections from JSON files, and query and assert on documents.

Add it to a project with axx pack add mongo.

Steps

mongo.service

Given a(n) {word} mongo database 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 a MongoDB database. The first one registered in a scenario is the default.

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

Property	Takes	Default
url	the connection string, which must name the database, like mongodb://localhost:27017/parcels; its authSource defaults to that database	required
user	the user Axx connects as	required
password	the user’s password	required

Every value can take ${env:…} and ${sys:…} references.

Example:

Given a tracking-db mongo database with the following properties:
  | url      | mongodb://localhost:27017/parcels?authSource=admin |
  | user     | parcels                                            |
  | password | parcels                                            |

mongo.seed

Given a {filepath} mongo db seed

Insert the documents of a JSON file into the default MongoDB database. The file maps each collection’s name to an array of its documents, in Extended JSON: {"$date": "2026-05-05T06:40:00Z"} is a date and {"$oid": ...} an ObjectId.

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

Example:

Given a seeds/scans-in-transit.json mongo db seed

mongo.seed.named

Given a {filepath} MongoDB seed for {word}

Insert the documents of a JSON file into the named MongoDB database; the file is as for the default database’s seed.

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

Example:

Given a seeds/scans-in-transit.json MongoDB seed for tracking-db

mongo.seed.named.alt

Given a {filepath} mongo db seed for {word}

Insert the documents of a JSON file into the named MongoDB database; the file is as for the default database’s seed.

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

Example:

Given a seeds/scans-in-transit.json mongo db seed for tracking-db

Since 0.1.0.

mongo.find

Then a[[ {ordinal}]] selection of documents is retrieved from the {word} collection[[ on {mongoService}]] where:
  | field | value |

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

Find the documents that match and keep them as the next selection, for the steps that check it. Selections are numbered in the order they are retrieved, whatever ordinal the step says; the selection means the first.

Parameter	Takes	For example
{ordinal}	a position, counting from 1; an optional ordinal left out is the first	1st, 2nd
{word}	one word, with no spaces	parcels, PX-4101
{mongoService}	the name of a MongoDB database registered in the scenario	tracking-db

Each row names a field, dotted (recipient.city) for one inside a document, and the value it holds: JSON when it reads as JSON (3, true, null, "3", {"$oid": "..."}), text otherwise.

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

• a selection of documents is retrieved from the {word} collection where:
• a {ordinal} selection of documents is retrieved from the {word} collection where:
• a selection of documents is retrieved from the {word} collection on {mongoService} where:
• a {ordinal} selection of documents is retrieved from the {word} collection on {mongoService} where:

Example:

Then a selection of documents is retrieved from the scans collection where:
  | parcelRef | PX-TRK-3001 |
  | status    | IN_TRANSIT  |

Since 0.1.0.

mongo.find.poll

Then within {duration} a[[ {ordinal}]] selection of at least {int} document(s) is retrieved from the {word} collection[[ on {mongoService}]] where:
  | field | value |

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

Find the documents that match, again every 500ms, until at least that many come back, and keep them as the next selection.

• The step fails when the time is up with fewer documents.
• An error from MongoDB fails the step only when the time is up.
• Selections are numbered in the order they are retrieved, whatever ordinal the step says; the selection means the first.

Parameter	Takes	For example
{duration}	a duration in seconds (s) or minutes (m)	5s, 2m
{ordinal}	a position, counting from 1; an optional ordinal left out is the first	1st, 2nd
{int}	a whole number	200, 3
{word}	one word, with no spaces	parcels, PX-4101
{mongoService}	the name of a MongoDB database registered in the scenario	tracking-db

Each row names a field, dotted (recipient.city) for one inside a document, and the value it holds: JSON when it reads as JSON (3, true, null, "3", {"$oid": "..."}), text otherwise.

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

• within {duration} a selection of at least {int} document(s) is retrieved from the {word} collection where:
• within {duration} a {ordinal} selection of at least {int} document(s) is retrieved from the {word} collection where:
• within {duration} a selection of at least {int} document(s) is retrieved from the {word} collection on {mongoService} where:
• within {duration} a {ordinal} selection of at least {int} document(s) is retrieved from the {word} collection on {mongoService} where:

Example:

Then within 10s a selection of at least 1 document is retrieved from the tracking collection where:
  | _id       | PX-TRK-3001 |
  | scanCount | 2           |

Since 0.1.0.

mongo.docs.eq

Then the[[ {ordinal}]] selection[[ on {mongoService}]] has {int} document(s)

Check that a selection of documents has exactly the given number of documents. the selection means the first selection of the scenario.

Parameter	Takes	For example
{ordinal}	a position, counting from 1; an optional ordinal left out is the first	1st, 2nd
{mongoService}	the name of a MongoDB database registered in the scenario	tracking-db
{int}	a whole number	200, 3

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

• the selection has {int} document(s)
• the {ordinal} selection has {int} document(s)
• the selection on {mongoService} has {int} document(s)
• the {ordinal} selection on {mongoService} has {int} document(s)

Example:

Then the selection has 2 documents
Then the 2nd selection on tracking-db has 1 document

Since 0.1.0.

mongo.docs.gt

Then the[[ {ordinal}]] selection[[ on {mongoService}]] has more than {int} document(s)

Check that a selection of documents has more than the given number of documents. the selection means the first selection of the scenario.

Parameter	Takes	For example
{ordinal}	a position, counting from 1; an optional ordinal left out is the first	1st, 2nd
{mongoService}	the name of a MongoDB database registered in the scenario	tracking-db
{int}	a whole number	200, 3

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

• the selection has more than {int} document(s)
• the {ordinal} selection has more than {int} document(s)
• the selection on {mongoService} has more than {int} document(s)
• the {ordinal} selection on {mongoService} has more than {int} document(s)

Example:

Then the selection has more than 2 documents
Then the 2nd selection on tracking-db has more than 1 document

Since 0.1.0.

mongo.docs.lt

Then the[[ {ordinal}]] selection[[ on {mongoService}]] has fewer than {int} document(s)

Check that a selection of documents has fewer than the given number of documents. the selection means the first selection of the scenario.

Parameter	Takes	For example
{ordinal}	a position, counting from 1; an optional ordinal left out is the first	1st, 2nd
{mongoService}	the name of a MongoDB database registered in the scenario	tracking-db
{int}	a whole number	200, 3

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

• the selection has fewer than {int} document(s)
• the {ordinal} selection has fewer than {int} document(s)
• the selection on {mongoService} has fewer than {int} document(s)
• the {ordinal} selection on {mongoService} has fewer than {int} document(s)

Example:

Then the selection has fewer than 2 documents
Then the 2nd selection on tracking-db has fewer than 1 document

Since 0.1.0.

mongo.doc.are

Then the {ordinal} document for the[[ {ordinal}]] selection[[ on {mongoService}]] properties are:
  | JSONPath | value |

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

Check the fields of one document of a selection, read as JSON: an ObjectId is its hex string, and a date is in ISO-8601 UTC, like 2026-05-05T06:40:00.000Z.

Parameter	Takes	For example
{ordinal}	a position, counting from 1; an optional ordinal left out is the first	1st, 2nd
{mongoService}	the name of a MongoDB database registered in the scenario	tracking-db

Each row names a JSONPath, like lastLocation or scans[0].status, and the value there as text, like true or 2: null for null, undefined for a field the document lacks.

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

• the {ordinal} document for the selection properties are:
• the {ordinal} document for the {ordinal} selection properties are:
• the {ordinal} document for the selection on {mongoService} properties are:
• the {ordinal} document for the {ordinal} selection on {mongoService} properties are:

Example:

Then the 1st document for the selection properties are:
  | status       | DELIVERED |
  | lastLocation | Leipzig   |
  | delivered    | true      |

Since 0.1.0.

mongo.doc.match

Then the {ordinal} document for the[[ {ordinal}]] selection[[ on {mongoService}]] properties match:
  | JSONPath | pattern |

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

Check the fields of one document of a selection, like the properties are step, with regular expressions (Java syntax) that must match the whole value, as text.

Parameter	Takes	For example
{ordinal}	a position, counting from 1; an optional ordinal left out is the first	1st, 2nd
{mongoService}	the name of a MongoDB database registered in the scenario	tracking-db

Each row names a JSONPath, like _id or scans[0].status, and a regular expression its value must match.

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

• the {ordinal} document for the selection properties match:
• the {ordinal} document for the {ordinal} selection properties match:
• the {ordinal} document for the selection on {mongoService} properties match:
• the {ordinal} document for the {ordinal} selection on {mongoService} properties match:

Example:

Then the 1st document for the 2nd selection on tracking-db properties match:
  | _id          | PX-TRK-\d{4} |
  | lastLocation | Hamburg.*    |

Since 0.1.0.

Parameter types

Parameter	Takes	Values	For example
{mongoService}	the name of a MongoDB database registered in the scenario		tracking-db