Matcher Library

Gherkio includes a powerful, built-in library of 25+ assertion matchers. These matchers allow you to perform rich semantic validations—ranging from format verification (like UUIDs, email addresses, and datetimes) to mathematical range boundaries, string manipulations, and collection inspection—without writing any code or custom assertions.

📚 Complete Matcher Quick-Reference

🔍 Category Deep-Dive & Syntax Examples

1. Existence Checkers

These matchers verify whether a key is present or absent in the response payload structure.

• exists: Evaluates to true if the field is present, regardless of its value (including empty values).
• not exists: Evaluates to true only if the key is completely omitted from the JSON payload.

expect:
  body.id: exists
  body.deletedAt: not exists
```text

---

### 2. Type Enforcers & Booleans
Ensures response elements conform strictly to expected JSON data types.

*   **`string`**: Fails if the value is a number, boolean, array, or object.
*   **`number`**: Validates integers, floats, and scientific JSON numbers.
*   **`boolean`**: Matches either `true` or `false` booleans.
*   **`array`**: Verifies the field is a JSON list.
*   **`object`**: Verifies the field is a structured map/object.
*   **`null`**: Verifies the value is `null`.
*   **`true` / `false`**: Value-specific boolean enforcers.

```yaml
expect:
  body.profile.bio: string
  body.profile.age: number
  body.profile.isVerified: boolean
  body.tags: array
  body.preferences: object
  body.finished: true
  body.error: null
```text

---

### 3. String & Membership Operations (Argument-based)
Performs text and list membership assertions on target fields.

*   **`contains <value>`**: Checks if the target string contains the substring `<value>` (case-sensitive).
*   **`startsWith <value>`**: Checks if the target string begins with the prefix `<value>`.
*   **`endsWith <value>`**: Checks if the target string ends with the suffix `<value>`.
*   **`regex <pattern>`**: Matches the string against a standard Go regular expression.
*   **`oneOf <opts>`**: Checks if the value matches any of the comma-separated options.
*   **`in <opts>`**: Alias for `oneOf`. Checks if the value matches any of the comma-separated options.

```yaml
expect:
  body.description: contains Mechanical
  body.sku: startsWith KBD-
  body.supportEmail: endsWith @example.com
  body.productCode: regex ^[A-Z]{3}-\d{4}$
  body.role: oneOf admin, editor, moderator
  body.status: in active, pending
```text

---

### 4. Mathematical Bounds (Argument-based)
Used to enforce numeric restrictions. Gherkio automatically coerces both the target response field and the matcher argument into `float64` floating points for maximum comparison precision.

*   **`gt <value>`**: Greater than (`>`).
*   **`gte <value>`**: Greater than or equal to (`>=`).
*   **`lt <value>`**: Less than (`<`).
*   **`lte <value>`**: Less than or equal to (`<=`).

```yaml
expect:
  body.rating: gt 4.2
  body.stock: gte 0
  body.discount: lt 1.0
  body.itemsCount: lte 100
```text

---

### 5. Format & Protocol Validators
Performs regex-based and parser-based syntax verification on strings to enforce RFC protocols.

*   **`uuid`**: Asserts strict compliance with UUID v4 syntax.
*   **`email`**: Validates structural email address syntax (presence of `@`, valid domain blocks).
*   **`datetime`**: Parses string against standard RFC3339 / ISO8601 structures (e.g. `2026-05-29T10:12:15Z`).
*   **`uri`**: Verifies that the string is a valid absolute URI.
*   **`ipv4` / `ipv6`**: Enforces valid IP structures, ensuring IPv4 segments fall between `0-255` and IPv6 fields support compressed forms.
*   **`base64`**: Attempts standard base64 decoding and falls back to URL-safe raw base64 to ensure absolute compatibility.
*   **`mac`**: Validates standard colon-separated or hyphen-separated MAC addresses (e.g., `00:1a:2b:3c:4d:5e`).

```yaml
expect:
  body.userId: uuid
  body.contactEmail: email
  body.createdAt: datetime
  body.imageLink: uri
  body.serverIp: ipv4
  body.payloadHash: base64
  body.deviceMac: mac
```text

---

### 6. Emptiness Checker
The **`empty`** matcher is a unified helper designed to handle collections, strings, and missing records consistently:
*   Returns `true` if target is a string equal to `""`.
*   Returns `true` if target is a JSON list containing `0` items.
*   Returns `true` if target is a JSON object map containing `0` properties.
*   Returns `true` if target is `null`.

```yaml
expect:
  # Validates that list is empty
  body.items: empty
  # Validates that custom message string is blank
  body.alertMessage: empty
```text

---

## 🔄 Matchers inside Universal Collections (`all`)

Matchers are fully integrated into Gherkio's collection engine. When performing assertions on arrays, you can pass **any matcher keyword** as the target check inside an `all()` block:

```yaml
expect:
  # Enforces that every element in the permissions array is a valid UUID
  all(body.users.id): uuid

  # Enforces that every transaction amount is positive
  all(body.transactions.amount): gt 0

  # Enforces that every tags list is a valid array
  all(body.products.tags): array
```text