# MongoDB

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

Source: https://axx.nimbusxr.us/references/packs/mongo/

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`

```gherkin
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:**

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

### `mongo.seed`

```gherkin
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:**

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

### `mongo.seed.named`

```gherkin
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:**

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

### `mongo.seed.named.alt`

```gherkin
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:**

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

_Since 0.1.0._

### `mongo.find`

```gherkin
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:**

```gherkin
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`

```gherkin
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:**

```gherkin
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`

```gherkin
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:**

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

_Since 0.1.0._

### `mongo.docs.gt`

```gherkin
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:**

```gherkin
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`

```gherkin
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:**

```gherkin
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`

```gherkin
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:**

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

_Since 0.1.0._

### `mongo.doc.match`

```gherkin
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:**

```gherkin
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` |