# Server-sent events

> Open server-sent event streams (`text/event-stream`) of your services and check the events they send.

Source: https://axx.nimbusxr.us/references/packs/sse/

Open server-sent event streams (`text/event-stream`) of your services and check the events they send.

Register a stream with `the {word} event stream with the following properties:`: it opens there and then, with the headers the table gives, and belongs to the scenario, which closes it when it ends. A stream that does not answer 200 with `text/event-stream` fails that step and shows what it answered.

- **Events are checked like messages:** `has an event where:` takes a table of paths into the event's data, as JSON, and the values they have, with `event type` (the event's `event:` field, or `message` without one) and `event id` rows; `has an event containing {string}` looks for text in any event's data. The checks wait, 10 seconds unless `within {duration}` says otherwise.
- **A stream the server ends** fails a check that is still waiting at once, after looking at every event it sent.
- **Secrets stay secret:** `${env:..}` values in the URL and the headers are masked in logs and failures.

Add it to a project with `axx pack add sse`.

## Steps

### `sse.stream`

```gherkin
Given the {word} event stream with the following properties:
  | property | value |
```

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

Open a server-sent event stream under a name. It belongs to the scenario, which closes it when it ends.

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

| Property | Takes | Default |
|---|---|---|
| `url` | the stream's address | _required_ |
| `header.<name>` | a header of the request, such as `header.Authorization` | |
| `asyncapi` | an AsyncAPI document, a file of the project or a URL, that the events follow: every message a scenario sends there, and every message a check finds, is checked against it (with the asyncapi pack) | |

Values are expanded (`${env:..}`, `${sys:..}`); what `${env:..}` references expand to is masked everywhere.

**Example:**

```gherkin
Given the tracking event stream with the following properties:
  | url | http://localhost:8400/api/parcels/PX-LIV-5702/events |
```

_Since 0.1.5._

### `sse.event`

```gherkin
Then [[within {duration} ]]the {word} event stream has an event where:
  | path | value |
```

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

Check that the stream sent an event with those values. 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` |

Each row is a path into the event's data, as JSON (a field name, a dotted path or a JSONPath), and the value it has, compared as text: `null` for null and `undefined` for absent. The rows `event type` and `event id` are the event's type (its `event:` field, or `message`) and id.

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

- `the {word} event stream has an event where:`
- `within {duration} the {word} event stream has an event where:`

**Example:**

```gherkin
Then within 20s the tracking event stream has an event where:
  | event type | delivered   |
  | reference  | PX-LIV-5702 |
  | status     | DELIVERED   |
```

_Since 0.1.5._

### `sse.event.text`

```gherkin
Then [[within {duration} ]]the {word} event stream has an event containing {string}
```

Check that the stream sent an event whose data contains the text. 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` |
| `{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 {word} event stream has an event containing {string}`
- `within {duration} the {word} event stream has an event containing {string}`

**Example:**

```gherkin
Then the tracking event stream has an event containing 'OUT_FOR_DELIVERY'
```

_Since 0.1.5._