> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ellomas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Assertions

> Validating outcomes with JSONPath-based assertions in Replay.

# Assertions

Assertions validate that step outputs match expected values. They catch regressions early and document the expected behaviour of your system.

## Basic Syntax

Each assertion rule specifies a path to target, an operator, and an expected value.

```yaml theme={null}
assert:
  - ["$.status", "eq", 200]
  - ["$.data.name", "eq", "Alice"]
  - ["$.data.items", "not_null"]
```

You can also use the object form:

```yaml theme={null}
assert:
  - path: $.status
    op: eq
    value: 200
  - path: $.data.email
    op: not_null
```

## Assertion Operators

| Operator   | Aliases    | Type    | Description                    |
| ---------- | ---------- | ------- | ------------------------------ |
| `eq`       | `==`, `=`  | Any     | Equal (type-aware for numbers) |
| `ne`       | `!=`, `<>` | Any     | Not equal                      |
| `gt`       | `>`        | Numeric | Greater than                   |
| `lt`       | `<`        | Numeric | Less than                      |
| `ge`       | `>=`       | Numeric | Greater than or equal          |
| `le`       | `<=`       | Numeric | Less than or equal             |
| `contains` |            | String  | Target contains substring      |
| `in`       |            | Array   | Value exists in array          |
| `not_null` |            | Any     | Value is not null              |

## JSONPath in Assertions

Assertions use the same JSONPath syntax as extraction:

```yaml theme={null}
- name: validate-response
  type: http
  request:
    method: GET
    url: /users/42
  assert:
    - ["$.status", "eq", 200]
    - ["$.data.email", "contains", "@"]
    - ["$.data.verified", "eq", true]
    - ["$.data.roles", "contains", "admin"]
    - ["$.data.roles", "in", "admin"]
    - ["$.data.loginCount", "gt", 0]
```

## Variables in Expected Values

Expected values can reference state variables:

```yaml theme={null}
- name: set-expected
  type: shell
  command: 'echo "{\"expected_name\": \"Bob\"}"'
  extract:
    target_name: $.expected_name

- name: check-assertion
  type: shell
  command: 'echo "{\"name\": \"Bob\"}"'
  assert:
    - ["$.name", "eq", "{{ target_name }}"]
```

## Assertions on Different Step Types

### HTTP

```yaml theme={null}
- name: api-check
  type: http
  request:
    method: GET
    url: /health
  assert:
    - ["$.status", "eq", 200]
    - ["$.data.status", "eq", "healthy"]
```

### Shell

```yaml theme={null}
- name: output-check
  type: shell
  command: 'echo "{\"status\": \"ok\", \"count\": 5}"'
  assert:
    - ["$.status", "eq", "ok"]
    - ["$.count", "lt", 10]
```

### Database

```yaml theme={null}
- name: db-check
  type: db
  query: "SELECT count(*) as cnt FROM users"
  assert:
    - ["$[0].cnt", "gt", 0]
```

## Ignoring Assertion Failures

Combine with `ignore_error` to allow optional assertions:

```yaml theme={null}
- name: optional-check
  type: http
  request:
    method: GET
    url: /optional-endpoint
  assert:
    - ["$.status", "eq", 200]
  ignore_error: true
```

## How Assertions Work

1. The step executes and produces a result value
2. The assertion engine resolves `{{ variables }}` in expected values
3. If a `path` is specified, it resolves the JSONPath against the result
4. The operator compares the resolved value against the expected value
5. If the comparison fails, the step is marked as failed (unless `ignore_error`)

The assertion engine is type-aware for numeric comparisons: `"5" == 5` evaluates to true.

## What's Next?

* Transform data with [templating and functions](/replay/guides/templating-and-functions)
* Deep-dive into [working with JSON](/replay/guides/working-with-json)