# Cloud Storage

> Upload files to Cloud Storage buckets and check the objects your services write there.

Source: https://axx.nimbusxr.us/next/references/packs/gcp-storage/

Upload files to Cloud Storage buckets and check the objects your services write there.

The steps use the scenario's project (`the {word} gcp project with the following properties:`, from gcp-core). Checks wait for the object (10 seconds unless `within {duration}` says otherwise), since services write asynchronously: an upload that triggers processing (a Pub/Sub notification or an Eventarc trigger, say) and the object that processing writes.

Add it to a project with `axx pack add gcp-storage`; it builds on [`gcp-core`](https://axx.nimbusxr.us/next/references/packs/gcp-core/), which comes with it.

## Steps

### `gcp-storage.upload`

```gherkin
When the {filepath} file is uploaded to the {word} gcs bucket[[ as {path}]]
```

Upload a file to the gcs bucket, under the file's name or the name given. Its content type follows the file's extension.

| 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` |
| `{path}` | a path in a folder or a store, like `manifests/M-1/report.csv`, quoted when it has a space. A `*` stands for any characters but a slash, for a name a check cannot know (`snap-*.json`, named by the time): the path then names the one file it matches | `manifests/M-KESTREL-0412/report.csv`, `"Parcels/Depot desk/arrivals.json"` |

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

- `the {filepath} file is uploaded to the {word} gcs bucket`
- `the {filepath} file is uploaded to the {word} gcs bucket as {path}`

**Example:**

```gherkin
When the invoices/kestrel-2026-09.csv file is uploaded to the carrier-invoices gcs bucket
When the invoices/kestrel-2026-09.csv file is uploaded to the carrier-invoices gcs bucket as incoming/kestrel-2026-09.csv
```

_Since 0.1.0._

### `gcp-storage.has`

```gherkin
Then [[within {duration} ]]the {word} gcs bucket has a(n) object named {path}
```

Check that the gcs bucket has an object with that name. The check waits for it: 10 seconds, or `within {duration}`.

| Parameter | Takes | For example |
|---|---|---|
| `{duration}` | a duration in seconds (`s`) or minutes (`m`) | `5s`, `2m` |
| `{word}` | one word, with no spaces | `parcels`, `PX-4101` |
| `{path}` | a path in a folder or a store, like `manifests/M-1/report.csv`, quoted when it has a space. A `*` stands for any characters but a slash, for a name a check cannot know (`snap-*.json`, named by the time): the path then names the one file it matches | `manifests/M-KESTREL-0412/report.csv`, `"Parcels/Depot desk/arrivals.json"` |

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

- `the {word} gcs bucket has a(n) object named {path}`
- `within {duration} the {word} gcs bucket has a(n) object named {path}`

**Example:**

```gherkin
Then within 30s the carrier-invoices gcs bucket has an object named disputes/kestrel-2026-09.csv
```

_Since 0.1.0._

### `gcp-storage.identical`

```gherkin
Then [[within {duration} ]]the {path} object in the {word} gcs bucket is identical to the {filepath} file
```

Check that the object exists with exactly the content of the file. The check waits for it: 10 seconds, or `within {duration}`.

| Parameter | Takes | For example |
|---|---|---|
| `{duration}` | a duration in seconds (`s`) or minutes (`m`) | `5s`, `2m` |
| `{path}` | a path in a folder or a store, like `manifests/M-1/report.csv`, quoted when it has a space. A `*` stands for any characters but a slash, for a name a check cannot know (`snap-*.json`, named by the time): the path then names the one file it matches | `manifests/M-KESTREL-0412/report.csv`, `"Parcels/Depot desk/arrivals.json"` |
| `{word}` | one word, with no spaces | `parcels`, `PX-4101` |
| `{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` |

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

- `the {path} object in the {word} gcs bucket is identical to the {filepath} file`
- `within {duration} the {path} object in the {word} gcs bucket is identical to the {filepath} file`

**Example:**

```gherkin
Then the disputes/kestrel-2026-09.csv object in the carrier-invoices gcs bucket is identical to the expected/kestrel-disputes.csv file
```

_Since 0.1.0._

### `gcp-storage.properties`

```gherkin
Then [[within {duration} ]]the {path} object in the {word} gcs bucket has the following properties:
  | path | value |
```

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

Check that the object holds JSON with those values at those paths. The check waits for it: 10 seconds, or `within {duration}`.

| Parameter | Takes | For example |
|---|---|---|
| `{duration}` | a duration in seconds (`s`) or minutes (`m`) | `5s`, `2m` |
| `{path}` | a path in a folder or a store, like `manifests/M-1/report.csv`, quoted when it has a space. A `*` stands for any characters but a slash, for a name a check cannot know (`snap-*.json`, named by the time): the path then names the one file it matches | `manifests/M-KESTREL-0412/report.csv`, `"Parcels/Depot desk/arrivals.json"` |
| `{word}` | one word, with no spaces | `parcels`, `PX-4101` |

Each row is a path into the JSON (a property name, a dotted path or a JSONPath) and the value it has, compared as text: `null` for null and `undefined` for absent, as in the other JSON property steps.

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

- `the {path} object in the {word} gcs bucket has the following properties:`
- `within {duration} the {path} object in the {word} gcs bucket has the following properties:`

**Example:**

```gherkin
Then the summaries/kestrel-2026-09.json object in the carrier-invoices gcs bucket has the following properties:
  | carrier         | KESTREL |
  | lines           | 14      |
  | totals.disputed | 5.25    |
```

_Since 0.1.0._

### `gcp-storage.contains`

```gherkin
Then [[within {duration} ]]the {path} object in the {word} gcs bucket contains {string}
```

Check that the text of the object contains the text.

- The check waits for it: 10 seconds, or `within {duration}`.
- Case matters; runs of spaces and line breaks count as one space.
- The text is read by the object's type: the text of a PDF's pages, the paragraphs and tables of a Word document (.docx), the cells of every sheet of an Excel workbook (.xlsx), the text content (or the markup) of XML and HTML, or the text itself.

| Parameter | Takes | For example |
|---|---|---|
| `{duration}` | a duration in seconds (`s`) or minutes (`m`) | `5s`, `2m` |
| `{path}` | a path in a folder or a store, like `manifests/M-1/report.csv`, quoted when it has a space. A `*` stands for any characters but a slash, for a name a check cannot know (`snap-*.json`, named by the time): the path then names the one file it matches | `manifests/M-KESTREL-0412/report.csv`, `"Parcels/Depot desk/arrivals.json"` |
| `{word}` | one word, with no spaces | `parcels`, `PX-4101` |
| `{string}` | text in double or single quotes, which the step leaves out | `"Get a quote"`, `'Express'` |

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

- `the {path} object in the {word} gcs bucket contains {string}`
- `within {duration} the {path} object in the {word} gcs bucket contains {string}`

**Example:**

```gherkin
Then the invoices/kestrel-2026-09.pdf object in the carrier-invoices gcs bucket contains "Total due: 1284.50 EUR"
```

_Since 0.1.1._

### `gcp-storage.row`

```gherkin
Then [[within {duration} ]]the {path} object in the {word} gcs bucket has a row where:
  | column | value |
```

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

Check that the table of the object has a row with those values in those columns.

- The check waits for it: 10 seconds, or `within {duration}`.
- The object is a CSV or TSV file, or an Excel workbook (.xlsx; its first sheet), whose first row names the columns.
- Cells compare as text, as the workbook shows them, with runs of spaces as one space; an empty value matches an empty cell.

| Parameter | Takes | For example |
|---|---|---|
| `{duration}` | a duration in seconds (`s`) or minutes (`m`) | `5s`, `2m` |
| `{path}` | a path in a folder or a store, like `manifests/M-1/report.csv`, quoted when it has a space. A `*` stands for any characters but a slash, for a name a check cannot know (`snap-*.json`, named by the time): the path then names the one file it matches | `manifests/M-KESTREL-0412/report.csv`, `"Parcels/Depot desk/arrivals.json"` |
| `{word}` | one word, with no spaces | `parcels`, `PX-4101` |

Each row names a column, as the object's first row names it, and the value in that column.

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

- `the {path} object in the {word} gcs bucket has a row where:`
- `within {duration} the {path} object in the {word} gcs bucket has a row where:`

**Example:**

```gherkin
Then within 30s the disputes/kestrel-2026-09.csv object in the carrier-invoices gcs bucket has a row where:
  | parcel | PX-5199          |
  | status | UNKNOWN_SHIPMENT |
  | billed | 4.10             |
```

_Since 0.1.1._