# MongoDB

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

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

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

## `mongo.service`

```gherkin
Given a(n) {word} mongo database with the following properties:
  | ... | ... |
```

Register a MongoDB database. The first one registered in a scenario is the default.

Properties (all required, `${env:..}`/`${sys:..}` expanded): `url` (must include the database name; `authSource` defaults to it), `user`, `password`.

**Parameters:** `{word}` (one word, no spaces)

**Example:**

```gherkin
Given a tracking-db mongo database with the following properties:
```

## `mongo.seed`

```gherkin
Given a {filepath} mongo db seed
```

Insert documents into the default MongoDB database. The file is a JSON object mapping collection names to arrays of documents (Extended JSON such as `{"$oid": ...}` is supported).

**Parameters:** `{filepath}` (A file of the project, without whitespace: a path relative to the `resources` directories or to the directory of axx.yaml, or an absolute path. Editors link it to the file)

**Example:**

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

## `mongo.seed.named`

```gherkin
Given a {filepath} MongoDB seed for {word}
```

Insert documents into the named MongoDB database (same file format as the default-database seed).

**Parameters:** `{filepath}` (A file of the project, without whitespace: a path relative to the `resources` directories or to the directory of axx.yaml, or an absolute path. Editors link it to the file), `{word}` (one word, no spaces)

**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 documents into the named MongoDB database (same file format as the default-database seed).

**Parameters:** `{filepath}` (A file of the project, without whitespace: a path relative to the `resources` directories or to the directory of axx.yaml, or an absolute path. Editors link it to the file), `{word}` (one word, no spaces)

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

Find documents and keep them as the next selection for later assertions, like the SQL selection steps. Selections are numbered in the order they are retrieved; `the selection` means the first. Each row is a `field | value` condition (dotted field paths reach into nested documents). Values are read as JSON when they parse as JSON (`3`, `true`, `null`, `"3"`, `{"$oid": "..."}`) and as plain strings otherwise.

**Variants** (optional parts in `[[...]]` above):

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

**Parameters:** `{ordinal}` (A 1-based position such as `1st`, `2nd`, `3rd` or `4th`. Omitting an optional ordinal means the first), `{word}` (one word, no spaces), `{mongoService}` (The name of a MongoDB database registered in the scenario)

**Example:**

```gherkin
Then a selection of documents is retrieved from the scans collection where:
```

_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:
  | ... | ... |
```

Poll every 500ms until the find returns at least the given number of documents or the time is up. On timeout the last result (possibly empty) is kept, so assert on it with a document-count step. Each row is a `field | value` condition (dotted field paths reach into nested documents). Values are read as JSON when they parse as JSON (`3`, `true`, `null`, `"3"`, `{"$oid": "..."}`) and as plain strings otherwise.

**Variants** (optional parts in `[[...]]` above):

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

**Parameters:** `{duration}` (A duration in seconds or minutes, e.g. `5s` or `2m`), `{ordinal}` (A 1-based position such as `1st`, `2nd`, `3rd` or `4th`. Omitting an optional ordinal means the first), `{int}` (a 32-bit integer), `{word}` (one word, no spaces), `{mongoService}` (The name of a MongoDB database registered in the scenario)

**Example:**

```gherkin
Then within 10s a selection of at least 1 document is retrieved from the tracking collection where:
```

_Since 0.1.0._

## `mongo.docs.eq`

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

Assert that a selection of documents has exactly the given number of documents.

**Variants** (optional parts in `[[...]]` above):

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

**Parameters:** `{ordinal}` (A 1-based position such as `1st`, `2nd`, `3rd` or `4th`. Omitting an optional ordinal means the first), `{mongoService}` (The name of a MongoDB database registered in the scenario), `{int}` (a 32-bit integer)

**Example:**

```gherkin
Then the selection has 2 documents
```

_Since 0.1.0._

## `mongo.docs.gt`

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

Assert that a selection of documents has more than the given number of documents.

**Variants** (optional parts in `[[...]]` above):

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

**Parameters:** `{ordinal}` (A 1-based position such as `1st`, `2nd`, `3rd` or `4th`. Omitting an optional ordinal means the first), `{mongoService}` (The name of a MongoDB database registered in the scenario), `{int}` (a 32-bit integer)

**Example:**

```gherkin
Then the selection has more than 2 documents
```

_Since 0.1.0._

## `mongo.docs.lt`

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

Assert that a selection of documents has fewer than the given number of documents.

**Variants** (optional parts in `[[...]]` above):

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

**Parameters:** `{ordinal}` (A 1-based position such as `1st`, `2nd`, `3rd` or `4th`. Omitting an optional ordinal means the first), `{mongoService}` (The name of a MongoDB database registered in the scenario), `{int}` (a 32-bit integer)

**Example:**

```gherkin
Then the selection has fewer than 2 documents
```

_Since 0.1.0._

## `mongo.doc.are`

```gherkin
Then the {ordinal} document for the[[ {ordinal}]] selection[[ on {mongoService}]] properties are:
  | ... | ... |
```

Assert properties (JSONPath, e.g. `lastLocation` or `scans[0].status`) of one document of a selection. Documents are compared as JSON: ObjectIds become their hex string, dates become ISO-8601 UTC strings, and every scalar is compared as text. `null` means null and `undefined` means the field is absent.

**Variants** (optional parts in `[[...]]` above):

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

**Parameters:** `{ordinal}` (A 1-based position such as `1st`, `2nd`, `3rd` or `4th`. Omitting an optional ordinal means the first), `{mongoService}` (The name of a MongoDB database registered in the scenario)

**Example:**

```gherkin
Then the 1st document for the selection properties are:
```

_Since 0.1.0._

## `mongo.doc.match`

```gherkin
Then the {ordinal} document for the[[ {ordinal}]] selection[[ on {mongoService}]] properties match:
  | ... | ... |
```

Like the properties step, but every value is a regular expression (Java syntax) that must match the whole text.

**Variants** (optional parts in `[[...]]` above):

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

**Parameters:** `{ordinal}` (A 1-based position such as `1st`, `2nd`, `3rd` or `4th`. Omitting an optional ordinal means the first), `{mongoService}` (The name of a MongoDB database registered in the scenario)

**Example:**

```gherkin
Then the 1st document for the 2nd selection on tracking-db properties match:
```

_Since 0.1.0._