Schema Examples

Stub files covering the common shapes, simplest first.

Basic Examples

Single Stub (JSON)

{
  "$schema": "https://bavix.github.io/gripmock/schema/stub.json",
  "service": "UserService",
  "method": "GetUser",
  "input": {
    "equals": {
      "id": "user123"
    }
  },
  "output": {
    "data": {
      "id": "user123",
      "name": "John Doe",
      "email": "john@example.com"
    }
  }
}

Single Stub (YAML)

# yaml-language-server: $schema=https://bavix.github.io/gripmock/schema/stub.json

service: UserService
method: GetUser
input:
  equals:
    id: "user123"
output:
  data:
    id: "user123"
    name: "John Doe"
    email: "john@example.com"

Multiple Stubs (Array)

# yaml-language-server: $schema=https://bavix.github.io/gripmock/schema/stub.json

- service: UserService
  method: GetUser
  priority: 100
  input:
    equals:
      id: "admin"
  output:
    data:
      id: "admin"
      name: "Administrator"
      role: "admin"

- service: UserService
  method: GetUser
  priority: 1
  input:
    contains:
      id: "user"
  output:
    data:
      id: "unknown"
      name: "Unknown User"
      role: "user"

Input Matching Examples

Exact Match

input:
  equals:
    id: "user123"
    type: "premium"

Partial Match

input:
  contains:
    name: "john"  # Matches "john", "johnny", "johnson"

Regex Match

input:
  matches:
    email: "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
    phone: "^\\+?[1-9]\\d{1,14}$"

Array Order Ignoring

input:
  ignoreArrayOrder: true
  equals:
    tags: ["tag1", "tag2", "tag3"]  # Order doesn't matter

anyOf Alternatives v3.11.0

input:
  equals:
    role: "vip"
  anyOf:
    - equals:
        name: "Alice"
    - matches:
        name: "^admin_"

This matcher is evaluated as:

(role == vip) AND (name == Alice OR name matches ^admin_)

Header Matching Examples

Exact Header Match

headers:
  equals:
    "Authorization": "Bearer token123"
    "Content-Type": "application/json"

Partial Header Match

headers:
  contains:
    "User-Agent": "Chrome"  # Matches any Chrome user agent

Regex Header Match

headers:
  matches:
    "X-Request-ID": "^req-[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$"

Output Examples

Simple Data Response

output:
  data:
    success: true
    message: "Operation completed"
    timestamp: "2024-01-01T12:00:00Z"

Error Response

output:
  error: "User not found"
  code: 5  # NOT_FOUND

Response with Delay

output:
  data:
    result: "success"
  delay: "2.5s"  # 2.5 second delay

Response with Headers

output:
  data:
    token: "jwt-token-here"
  headers:
    "Set-Cookie": "session=abc123; HttpOnly"
    "X-Custom-Header": "custom-value"

Streaming Examples

Server-Side Streaming

output:
  stream:
    - message: "First message"
      timestamp: "2024-01-01T12:00:01Z"
    - message: "Second message"
      timestamp: "2024-01-01T12:00:02Z"
    - message: "Final message"
      timestamp: "2024-01-01T12:00:03Z"
  delay: "1s"  # Delay between messages

Streaming with Complex Data

output:
  stream:
    - user:
        id: "user1"
        name: "Alice"
        status: "online"
    - user:
        id: "user2"
        name: "Bob"
        status: "offline"
    - user:
        id: "user3"
        name: "Charlie"
        status: "away"
  delay: "500ms"

Priority Examples

Specific vs General

# High priority: Specific user
- service: UserService
  method: GetUser
  priority: 100
  input:
    equals:
      id: "admin"
  output:
    data:
      id: "admin"
      role: "administrator"

# Low priority: General fallback
- service: UserService
  method: GetUser
  priority: 1
  input:
    contains: {}  # Matches any input
  output:
    data:
      id: "unknown"
      role: "user"

Error Handling with Priority

# High priority: Specific error
- service: UserService
  method: GetUser
  priority: 100
  input:
    equals:
      id: "invalid"
  output:
    error: "Invalid user ID format"
    code: 3

# Medium priority: General validation
- service: UserService
  method: GetUser
  priority: 50
  input:
    contains:
      id: ""
  output:
    error: "User ID cannot be empty"
    code: 3

# Low priority: Generic error
- service: UserService
  method: GetUser
  priority: 1
  input:
    contains: {}
  output:
    error: "User not found"
    code: 5

Options Examples

Match Limit (times)

# Stub matches exactly once
- service: AuthService
  method: Login
  input:
    equals:
      username: "test"
  output:
    data:
      token: "jwt-token"
  options:
    times: 1

# Stub matches up to 5 times (for retry testing)
- service: PaymentService
  method: Charge
  input:
    contains:
      amount: 100
  output:
    data:
      transactionId: "tx-123"
  options:
    times: 5

Effects Examples v3.11.0

Upsert Transition

- service: AuthService
  method: Register
  input:
    equals:
      email: "john@example.com"
  output:
    data:
      ok: true
  effects:
    - action: upsert
      stub:
        id: "4ee3a94f-4ad7-4a8f-a31c-f7cf3ca1ad6a"
        service: AuthService
        method: Login
        input:
          equals:
            email: "john@example.com"
        output:
          data:
            token: "token-john"

Delete Transition

- service: AuthService
  method: Logout
  input:
    equals:
      email: "john@example.com"
  output:
    data:
      ok: true
  effects:
    - action: delete
      id: "4ee3a94f-4ad7-4a8f-a31c-f7cf3ca1ad6a"

Complex Examples

E-commerce Order Service

# yaml-language-server: $schema=https://bavix.github.io/gripmock/schema/stub.json

- service: OrderService
  method: CreateOrder
  priority: 100
  input:
    equals:
      userId: "premium_user"
      items:
        - productId: "prod123"
          quantity: 2
  output:
    data:
      orderId: "order_12345"
      status: "confirmed"
      total: 199.99
      discount: 20.00
    delay: "1s"

- service: OrderService
  method: CreateOrder
  priority: 50
  input:
    contains:
      userId: "user"
  output:
    data:
      orderId: "order_67890"
      status: "pending"
      total: 99.99
      discount: 0.00
    delay: "500ms"

- service: OrderService
  method: CreateOrder
  priority: 1
  input:
    contains: {}
  output:
    error: "Invalid order data"
    code: 3

Authentication Service

# yaml-language-server: $schema=https://bavix.github.io/gripmock/schema/stub.json

- service: AuthService
  method: Login
  priority: 100
  input:
    equals:
      username: "admin"
      password: "admin123"
  output:
    data:
      token: "admin-jwt-token"
      expiresIn: 3600
      user:
        id: "admin"
        role: "administrator"
    headers:
      "Set-Cookie": "session=admin-session; HttpOnly; Secure"

- service: AuthService
  method: Login
  priority: 50
  input:
    contains:
      username: "user"
  output:
    data:
      token: "user-jwt-token"
      expiresIn: 1800
      user:
        id: "user123"
        role: "user"
    headers:
      "Set-Cookie": "session=user-session; HttpOnly"

- service: AuthService
  method: Login
  priority: 1
  input:
    contains: {}
  output:
    error: "Invalid credentials"
    code: 16  # UNAUTHENTICATED

Notes

Priority only breaks ties between equally specific stubs — see Priority for the full ordering. YAML stubs take comments; JSON stubs do not, so a non-obvious matcher is worth a description field in the surrounding file or a comment in the YAML form.