# Pub/Sub

> Publish messages to Pub/Sub topics and check the messages your services publish.

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

Publish messages to Pub/Sub topics and check the messages your services publish.

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

**Checking a topic** does not take messages from anyone: for the topics a run checks, Axx creates a subscription of its own (`axx-<run>-<topic>`) once the services are up, and deletes it when the run ends. A check only looks at the messages received since its scenario started; match on data unique to the scenario, since scenarios run in parallel. The conditions are paths into the message data (JSON) and `attribute <name>` rows for its attributes.

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

## Steps

### `gcp-pubsub.send`

```gherkin
When a message is published to the {word} pubsub topic:
  """
  ...
  """
```

Send a message to the pubsub topic; the doc string is its body.

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

**Example:**

```gherkin
When a message is published to the shipment-events pubsub topic:
  """
  {"parcel": "PX-5105", "carrier": "HERON", "service": "express", "weightKg": 3.2}
  """
```

_Since 0.1.0._

### `gcp-pubsub.send.file`

```gherkin
When the {filepath} message is published to the {word} pubsub topic[[ with the following attributes:]]
```

Send a message whose body is the file to the pubsub topic, with the attributes of the table when the step has one.

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

Each row is an attribute sent with the message, as text: its name and its value.

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

- `the {filepath} message is published to the {word} pubsub topic`
- `the {filepath} message is published to the {word} pubsub topic with the following attributes:`

**Example:**

```gherkin
When the messages/px-5105-weighed.json message is published to the shipment-events pubsub topic
When the messages/px-5105-weighed.json message is published to the shipment-events pubsub topic with the following attributes:
  | eventType | ShipmentWeighed |
```

_Since 0.1.0._

### `gcp-pubsub.received`

```gherkin
Then [[within {duration} ]]the {word} pubsub topic has a message where:
  | path | value |
```

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

Check that the pubsub topic has a message with those values, received since the scenario started.

- The check waits for it: 10 seconds, or `within {duration}`.
- Axx creates a subscription of its own to the topic for the run.

| Parameter | Takes | For example |
|---|---|---|
| `{duration}` | a duration in seconds (`s`) or minutes (`m`) | `5s`, `2m` |
| `{word}` | one word, with no spaces | `parcels`, `PX-4101` |

Each row is a path into the message's JSON body (a field name, a dotted path or a JSONPath) and the value it has, compared as text: `null` for null and `undefined` for absent. A row `attribute <name>` is instead on the attribute of that name sent with the message: `undefined` when there is none.

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

- `the {word} pubsub topic has a message where:`
- `within {duration} the {word} pubsub topic has a message where:`

**Example:**

```gherkin
Then within 30s the invoice-events pubsub topic has a message where:
  | attribute eventType | InvoiceReconciled |
  | invoice             | INV-2026-09-KES1  |
  | status              | RECONCILED        |
```

_Since 0.1.0._