# Service Bus

> Send messages to Service Bus queues and topics, and check the messages your services send there.

Source: https://axx.nimbusxr.us/next/references/packs/azure-servicebus/

Send messages to Service Bus queues and topics, and check the messages your services send there.

Register the namespace once, set up as the Azure SDK is set up for the real service; every Service Bus step of the scenario uses it:

```gherkin
Given the customs service bus namespace with the following properties:
  | connection string | ${env:SERVICEBUS_CONNECTION_STRING} |
```

Steps name a **queue** or a **topic**: `the customs-filings service bus queue`, `the customs-events service bus topic`. Messages carry application properties (`with the following properties:`, and `property <name>` rows in checks).

**Checking a queue receives from it**: Axx completes each message it receives, as any consumer would, so check the queues your services **write** to. **Checking a topic** takes nothing from anyone: for the topics a run checks, Axx creates a subscription of its own (`axx-<run>`, through the management API, so it needs the Manage right) once the services are up, and deletes it when the run ends. A check only looks at the messages received since its scenario started.

Add it to a project with `axx pack add azure-servicebus`.

## Steps

### `azure-servicebus.namespace`

```gherkin
Given the {word} service bus namespace 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 the Service Bus namespace the steps talk to.

- The first namespace registered is the default.
- Give it a `connection string` or a `namespace`, not both.
- Values expand `${env:..}` and `${sys:..}`.

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

| Property | Takes |
|---|---|
| `connection string` | the namespace's connection string, or a local emulator's (with `UseDevelopmentEmulator=true`), like `${env:SERVICEBUS_CONNECTION_STRING}` |
| `namespace` | the fully qualified namespace, like `<name>.servicebus.windows.net`, signed in with the Azure default credential chain |
| `management endpoint` | where the namespace's management API is when it is not the namespace's own host, as with local emulators |
| `asyncapi` | an AsyncAPI document, a file of the project or a URL, that the queues and topics follow: every message a scenario sends there, and every message a check finds, is checked against it (with the asyncapi pack) |

**Example:**

```gherkin
Given the customs service bus namespace with the following properties:
  | connection string | ${env:SERVICEBUS_CONNECTION_STRING} |
Given the customs service bus namespace with the following properties:
  | namespace | ${env:SERVICEBUS_NAMESPACE} |
```

_Since 0.1.0._

### `azure-servicebus.send`

```gherkin
When a message is sent to the {word} service bus queue:/topic:
  """
  ...
  """
```

Send a message to the service bus queue or 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 sent to the customs-filings service bus queue:
  """
  {"declaration": "DEC-7103", "parcel": "PX-7103", "invoice": "DEC-7103.json"}
  """
```

_Since 0.1.0._

### `azure-servicebus.send.file`

```gherkin
When the {filepath} message is sent to the {word} service bus queue/topic[[ with the following properties:]]
```

Send a message whose body is the file to the service bus queue or topic, with the properties 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 a property sent with the message, as text: its name and its value.

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

- `the {filepath} message is sent to the {word} service bus queue/topic`
- `the {filepath} message is sent to the {word} service bus queue/topic with the following properties:`

**Example:**

```gherkin
When the messages/filing-DEC-7101.json message is sent to the customs-filings service bus queue
When the messages/filing-DEC-7101.json message is sent to the customs-filings service bus queue with the following properties:
  | broker | ACME-CUSTOMS |
```

_Since 0.1.0._

### `azure-servicebus.received`

```gherkin
Then [[within {duration} ]]the {word} service bus queue/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 service bus queue or topic has a message with those values, received since the scenario started.

- The check waits for it: 10 seconds, or `within {duration}`.
- Axx completes the messages of a queue it checks, and subscribes to a 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 `property <name>` is instead on the property of that name sent with the message: `undefined` when there is none.

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

- `the {word} service bus queue/topic has a message where:`
- `within {duration} the {word} service bus queue/topic has a message where:`

**Example:**

```gherkin
Then within 30s the duty-payments service bus queue has a message where:
  | declaration     | DEC-7102     |
  | amount          | 96           |
  | currency        | EUR          |
  | property broker | ACME-CUSTOMS |
```

_Since 0.1.0._