Assertions

Assertions verify that your machine behaves correctly. They're marked with the = prefix and appear in expect: blocks.

Basic Syntax

expect:
  = order is in #paid
  = $total equals 1200
  = @customer received :confirmation

State Assertions

Current State

expect:
  = order is in #paid
  = order is in #awaiting_payment
  = application is in #pending

Not in State

expect:
  = order is not in #cancelled
  = order is not in #failed

State History

expect:
  = order has entered #processing
  = order has been in #pending
  = order has never been in #cancelled

Context Assertions

Equality

expect:
  = $total equals 1200
  = $status equals "active"
  = $is_premium equals true

Comparisons

expect:
  = $total is greater than 100
  = $total is less than 2000
  = $total is at least 100
  = $total is at most 500
  = $discount is between 10 and 50

Not Equal

expect:
  = $status is not "cancelled"
  = $retry_count is not 0

Empty/Not Empty

expect:
  = $customer_name is not empty
  = $errors is empty
  = $items is not empty

Collection Assertions

Contains

expect:
  = $items contains "Laptop"
  = $tags contains "urgent"
  = $roles contains "admin"

Count

expect:
  = $items has 3 items
  = $items_count equals 3
  = $errors has 0 items

Empty/Not Empty

expect:
  = $items is not empty
  = $errors is empty
  = $cart has items

Event Assertions

Event Received

expect:
  = @customer received :order_confirmed
  = @payment received :refund_request
  = @warehouse received :ship_order

Event Emitted

expect:
  = :payment_request was emitted to @payment
  = :notification was sent to @customer

Event Not Received

expect:
  = @customer did not receive :error
  = :refund was not emitted

Event with Data

expect:
  = @payment received :payment_request with $total
  = :order_confirmed was emitted with order_id: $order_id

Boolean Assertions

expect:
  = $is_active is true
  = $is_cancelled is false
  = $has_discount is true

Timestamp Assertions

expect:
  = $created_at is not empty
  = $updated_at is after $created_at
  = $completed_at is today

Negation

Use not or is not for negative assertions:

expect:
  = order is not in #cancelled
  = $total is not 0
  = $items does not contain "Expired Item"
  = @customer did not receive :error

Multiple Assertions

All assertions in an expect: block must pass:

expect:
  = order is in #paid              // AND
  = $total equals 1200             // AND
  = @customer received :confirmation  // AND
  = $items has 3 items             // All must pass

Event-Level vs Scenario-Level

Event-Level (after specific event)

on> :checkout from @customer
  order moves to #awaiting_payment

  expect:
    = order is in #awaiting_payment    // Checked after :checkout

Scenario-Level (after all events)

scenario: complete purchase

  on> :checkout from @customer
    ...

  on :payment_success from @payment
    ...

  expect:
    = order is in #paid               // Checked after all events

Assertion Patterns

Verify State Transition

scenario: order payment

  given:
    order is in #pending

  on> :payment_received from @payment
    order moves to #paid

  expect:
    = order is not in #pending
    = order is in #paid

Verify Context Update

scenario: apply discount

  given:
    $total: number is 100
    $discount: number is 0

  on> :apply_coupon from @customer
    $discount becomes 10
    $total decreases by $discount

  expect:
    = $discount equals 10
    = $total equals 90

Verify Event Communication

scenario: order triggers payment

  on> :checkout from @customer
    emit :payment_request to @payment

  expect:
    = :payment_request was emitted to @payment
    = @payment received :payment_request

Verify Error Handling

scenario: handle invalid cart

  given:
    cart is empty

  on> :checkout from @customer
    ? cart is empty
      emit :checkout_error to @customer

  expect:
    = order is not in #processing
    = @customer received :checkout_error

Custom Assertions

For complex assertions, use natural language that maps to bindings:

expect:
  = payment was processed successfully
  = inventory was updated correctly
  = email was sent to customer

These map to custom assertion classes in your binding code.

Assertion Debugging

When assertions fail, you get detailed output:

✗ order is in #paid
  Expected: #paid
  Actual:   #awaiting_payment

  Event trace:
    1. :checkout → #awaiting_payment
    2. :payment_failed → #awaiting_payment (no transition)

Best Practices

Be Specific

// Good - specific
expect:
  = $total equals 1200
  = order is in #paid

// Avoid - vague
expect:
  = order is valid
  = everything worked

Test What Matters

// Good - testing the outcome
expect:
  = order is in #paid
  = @customer received :confirmation

// Avoid - testing implementation details
expect:
  = internal_counter equals 5
  = temp_flag is true

Cover Edge Cases

scenario: empty cart checkout

  given:
    cart is empty

  on> :checkout from @customer
    ...

  expect:
    = order is not in #paid
    = @customer received :empty_cart_error

Group Related Assertions

expect:
  // State assertions
  = order is in #completed

  // Context assertions
  = $total equals 1200
  = $items_count equals 3

  // Event assertions
  = @customer received :confirmation
  = @warehouse received :ship_order