# Firestore

> Seed Firestore and check the documents your services write.

Source: https://axx.nimbusxr.us/references/steps/gcp-firestore/

Seed Firestore and check the documents your services write.

The steps use the scenario's project (`the {word} gcp project with the following properties:`, from gcp-core) and its default database.

A **seed** is a YAML or JSON file that maps collections to their documents, by ID (a collection can be nested: `shipments/SHP-1/scans`):

```yaml
shipments:
  SHP-1001:
    carrier: KESTREL
    weightKg: 2.5
    agreedPrice: 3.38
```

**Checks** wait (10 seconds unless `within {duration}` says otherwise): for a document at a path (`invoices/INV-2026-09-KESTREL`) to have properties, or for a collection to have a document meeting every condition. Conditions and properties are `field | value` rows, with a dotted path into maps (`totals.billed`), compared as text: timestamps in RFC 3339, `null` for null and `undefined` for absent. A collection check reads up to 5,000 of its documents.

## `gcp-firestore.seed`

```gherkin
Given a {filepath} firestore seed
```

Write the documents of a seed file (resolved against `resources`): YAML or JSON mapping collections to documents by ID.

**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/shipments.yaml firestore seed
```

_Since 0.1.0._

## `gcp-firestore.document`

```gherkin
Then [[within {duration} ]]the {word} firestore document has the following properties:
  | ... | ... |
```

Wait (10s, or the given time) until the document at the path exists with every `field | value` property.

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

- `the {word} firestore document has the following properties:`
- `within {duration} the {word} firestore document has the following properties:`

**Parameters:** `{duration}` (A duration in seconds or minutes, e.g. `5s` or `2m`), `{word}` (one word, no spaces)

**Example:**

```gherkin
Then within 30s the invoices/INV-2026-09-KESTREL firestore document has the following properties:
```

_Since 0.1.0._

## `gcp-firestore.collection`

```gherkin
Then [[within {duration} ]]the {word} firestore collection has a document where:
  | ... | ... |
```

Wait (10s, or the given time) until the collection has a document meeting every `field | value` row.

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

- `the {word} firestore collection has a document where:`
- `within {duration} the {word} firestore collection has a document where:`

**Parameters:** `{duration}` (A duration in seconds or minutes, e.g. `5s` or `2m`), `{word}` (one word, no spaces)

**Example:**

```gherkin
Then the disputes firestore collection has a document where:
```

_Since 0.1.0._