#moonrockz/expect

#Install

moon add moonrockz/expect

import {
  "moonrockz/expect",
} for "test"

#Usage

test "basic assertions" {
  // Equality
  @expect.expect(1 + 1).to_equal(2)
  @expect.expect(1).to_not_equal(2)

  // Booleans
  @expect.expect(true).to_be_true()
  @expect.expect(false).to_be_false()

  // Ordering (any type that implements Compare)
  @expect.expect(5).to_be_greater_than(3)
  @expect.expect(5).to_be_greater_than_or_equal(5)
  @expect.expect(3).to_be_less_than(5)
  @expect.expect(3).to_be_less_than_or_equal(3)
  @expect.expect(3).to_be_between(1, 5) // inclusive
  @expect.expect(4).to_be_between(1, 5, high_inclusive=false)

  // Signs (Int, Int16, Int64, UInt, UInt16, UInt64, Double, Float)
  @expect.expect(3).to_be_positive()
  @expect.expect(-3).to_be_negative()
  @expect.expect(0).to_be_zero()

  // Floating-point numbers (Double and Float)
  @expect.expect(0.1 + 0.2).to_be_close_to(0.3) // default tolerance 1e-9
  @expect.expect(1.0).to_be_close_to(1.05, tolerance=0.1) // absolute
  @expect.expect(1000.0).to_be_close_to(1001.0, relative=0.01) // 1%
  @expect.expect(1.0).to_be_close_to(1.0000000000000002, ulps=1)
  @expect.expect(0.0 / 0.0).to_be_nan()
  @expect.expect(1.0).to_be_finite()

  // Options
  @expect.expect(Some(42)).to_be_some()
  @expect.expect((None : Int?)).to_be_none()

  // Results
  let ok : Result[Int, String] = Ok(1)
  @expect.expect(ok).to_be_ok()
  @expect.expect((Err("boom") : Result[Int, String])).to_be_err()

  // Strings
  @expect.expect("hello world").to_contain("world")
  @expect.expect("hello world").to_start_with("hello")
  @expect.expect("hello world").to_end_with("world")
  @expect.expect("order 42").to_match("[[:digit:]]+") // regex search
  @expect.expect("42").to_match_fully("[[:digit:]]+") // whole string
  @expect.expect("Hello").to_equal_ignoring_case("hello")
  @expect.expect("a b\nc").to_equal_ignoring_whitespace("abc")
  @expect.expect(" \t").to_be_blank()
  @expect.expect("a-b-c").to_contain_times("-", 2)
  @expect.expect("one two three").to_contain_substrings_in_order(["one", "three"])

  // Arrays
  @expect.expect([1, 2, 3]).to_contain_element(2)
  @expect.expect([1, 2, 3]).to_contain_all([3, 1])
  @expect.expect([3, 1, 2]).to_equal_ignoring_order([1, 2, 3])
  @expect.expect([2, 4, 6]).to_all_satisfy(x => x % 2 == 0)
  @expect.expect([1, 2, 3]).to_contain_exactly([1, 2, 3]) // same order
  @expect.expect([1, 2, 2]).to_contain_only([2, 1]) // any order, repeats allowed
  @expect.expect([1, 2, 3]).to_contain_in_order([1, 3]) // gaps allowed
  @expect.expect([1, 2, 3]).to_start_with_elements([1, 2])
  @expect.expect([1, 2, 3]).to_end_with_elements([3])
  @expect.expect([1, 2, 3]).to_contain_none_of([4, 5])
  @expect.expect([1, 2, 3]).to_any_satisfy(x => x > 2)
  @expect.expect([1, 2, 3]).to_none_satisfy(x => x > 3)
  @expect.expect([1, 2, 3, 4]).to_have_count_satisfying(2, x => x % 2 == 0)
  @expect.expect([1, 2, 2]).to_be_sorted()
  @expect.expect(["a", "bb"]).to_be_sorted_by(s => s.length())
  @expect.expect([1, 2, 3]).to_have_no_duplicates()
  @expect.expect([1, 5]).to_satisfy_respectively([
    it => it.to_equal(1),
    it => it.to_be_greater_than(2),
  ])

  // Maps
  @expect.expect({ "a": 1 }).to_contain_key("a")
  @expect.expect({ "a": 1 }).to_contain_value(1)
  @expect.expect({ "a": 1, "b": 2 }).to_contain_entry("a", 1)
  @expect.expect({ "a": 1, "b": 2 }).to_contain_entries({ "b": 2 })

  // Length (String, Array, Map, Set, views, Deque, List, and the other core collections)
  @expect.expect("").to_be_empty()
  @expect.expect([1, 2, 3]).to_have_length(3)

  // Any value
  @expect.expect(4).to_satisfy(x => x % 2 == 0, description="is even")
  @expect.expect(2).to_be_one_of([1, 2, 3])
  @expect.expect(2).to_be_in(Set([1, 2, 3]))

  // Chars (ASCII, except to_be_whitespace)
  @expect.expect('7').to_be_digit()
  @expect.expect('a').to_be_letter()
  @expect.expect(' ').to_be_whitespace()
  @expect.expect('A').to_be_upper_case()
  @expect.expect('a').to_be_lower_case()
}

#Negation

@expect.expect(3).not().to_equal(5)
@expect.expect([1, 2]).not().to_be_empty()

#Chaining on inner values

@expect.expect(Some(42)).unwrap_some().to_be_greater_than(40)
@expect.expect(parse("1")).unwrap_ok().to_equal(1)
@expect.expect(parse("x")).unwrap_err().to_equal(ParseError::Invalid)

#Navigation

// Fails with: user.address.city: expect(received).to_equal(expected) ...
@expect.expect(user, label="user")
.get("address", u => u.address)
.get("city", a => a.city)
.to_equal("Paris")

#Matcher values

@expect.expect(age).to(@expect.all_of([
  @expect.satisfying(a => a >= 18, description=">= 18"),
  @expect.is_not(@expect.equal_to(99)),
]))

@expect.expect(users).to_contain_element_matching(
  @expect.field("name", u => u.name, @expect.equal_to("Ada")),
)

@expect.expect(users).to_contain_element_matching(
  @expect.field("age", u => u.age, @expect.matching("an adult", it => {
    it.to_be_greater_than_or_equal(18)
  })),
)

expect(received).to(matcher)
Expected: all of (> 1, < 5, even)
Received: 7
Mismatch:
  < 5: was 7
  even: was 7

pub fn even() -> @expect.Matcher[Int] {
  {
    describe: () => "even",
    check: x => if x % 2 == 0 { None } else { Some("was odd") },
  }
}

#Show the expression

import {
  "moonrockz/expect",
  "moonrockz/expect/with_source",
} for "test"

@with_source.expect(user.age + 1).to_equal(20)

expect(user.age + 1).to_equal(expected)
Expected: 20
Received: 18

• The file is read only when an assertion fails, and only once per file.
• If the file cannot be read, for example because the tests run from a different directory, the headline shows received as before.
• Navigation shows the path from there on, as with @expect.expect.
• Soft scopes (s.expect) still show received.

#Snapshots

test "order summary" {
  // Inline snapshot of the `Show` output. `--update` fills in `content`.
  inspect(summary(order), content="3 items, $12.50")
  // Inline snapshot of the `Debug` output, for any type that derives Debug.
  @debug.debug_inspect(order.items, content="...")
}

test "report" (it : @test.T) {
  // File snapshot, stored in __snapshot__/report.txt.
  it.writeln(render_report(data))
  it.snapshot(filename="report.txt")
}

#Property-based tests

@expect.for_all((xs : Array[Int]) => {
  @expect.expect(xs.rev().rev()).to_equal(xs)
})

for_all(property) failed after 3 test(s)
Counterexample: 50
Shrinks:        26 successful, 37 attempted
Failure:
  src/math_test.mbt:3:46-3:75@me/app: expect(received).to_be_less_than(expected)
  Expected: < 50
  Received: 50

#Async code

import {
  "moonrockz/expect",
  "moonrockz/expect/async_expect",
} for "test"

async test "worker drains the queue" {
  start_worker(queue)
  @async_expect.eventually(() => @expect.expect(queue.length()).to_equal(0))
  // timeout=1000 and interval=50 milliseconds by default
}

eventually(block) did not pass within 1000 ms (20 attempts)
Last failure:
  src/worker_test.mbt:3:45-3:78@me/app: expect(received).to_equal(expected)
  Expected: 0
  Received: 2

#Soft assertions

@expect.expect_all(s => {
  s.expect(user.name).to_equal("Ada")
  s.expect(user.age).to_be_greater_than(18)
  s.expect(user.tags).first().to_equal("admin")
})

2 of 3 assertions failed

(1) src/user_test.mbt:12:3-12:40@me/app: expect(received).to_equal(expected)
    Expected: "Ada"
    Received: "Bob"

(2) src/user_test.mbt:13:3-13:45@me/app: expect(received).to_be_greater_than(expected)
    Expected: > 18
    Received: 17

• The scope carries through not(), because, navigation and all, and custom matchers built on assert_that collect their failures too.
• A failure that leaves no value to go on with, such as unwrap_some on None, stops the block. So does any other error, for example a plain @expect.expect that fails in the block. The report says which failure stopped the block.
• s.expect_all(inner => ...) runs a nested scope. Its failures join the outer list, and when the nested block stops, the outer block goes on.

#Equivalence

@expect.expect(saved).to_be_equivalent_to(
  draft,
  excluding=["id", "items[*].id"], // skip these paths; [*] matches any index
  ignoring_order=true, // compare arrays as multisets, at every depth
  tolerance=0.01, // numbers may differ by up to 0.01
)

expect(received).to_be_equivalent_to(expected)
Expected: equivalent to { id: 1, owner: "Ada", balance: { cents: 1050 } }
Received: { id: 1, owner: "Ada", balance: { cents: 1005 } }
Differences:
  balance.cents: expected 1050, received 1005

#Many matchers on one value

@expect.expect(age).all(it => {
  it.to_be_greater_than(0)
  it.to_be_less_than(150)
})

#Errors

@expect.expect_call(() => parse("x")).to_raise()
@expect.expect_call(() => parse("x")).to_raise(containing="invalid")
@expect.expect_call(() => parse("1")).not().to_raise()

// Check the type of the error with an `is` pattern
@expect.expect_call(() => parse("x")).to_raise_matching(
  e => e is ParseError::Invalid(_),
  description="an Invalid error",
)

// Chain on the error or on the returned value
@expect.expect_call(() => parse("x")).to_raise_error().message().to_contain("invalid")
@expect.expect_call(() => parse("1")).to_return().to_equal(1)

#Json

let order : Json = { "id": 7, "items": [{ "sku": "A1", "qty": 2 }] }
@expect.expect(order).at("items[0].sku").to_equal("A1")
@expect.expect(order).to_contain_json({ "items": [{ "qty": 2 }] })

expect(received).at(path)
Expected: a value at "items[3].sku"
Received: {"id":7,"items":[{"sku":"A1","qty":2}]}
Found:    items is an array of length 1

#Regular expressions

#Labels

// Fails with: user id: expect(received).to_equal(expected) ...
@expect.expect(3, label="user id").to_equal(5)

#Reasons

// Fails with:
// retries: expect(received).to_equal(expected)
// Expected: 4
// Received: 3
// Because:  the client retries three times
@expect.expect(3, label="retries")
.because("the client retries three times")
.to_equal(4)

#Other collections

@expect.expect_elements(deque.iter()).to_contain_element(3)
@expect.expect_elements(sorted_set.iter()).first().to_equal(1)

#Custom types with a length

struct Bag {
  items : Array[Int]
} derive(Debug)

impl @expect.HasLength for Bag with length(self) {
  self.items.length()
}

#Custom matchers

#callsite(autofill(loc))
fn @expect.Expectation::to_be_even(
  self : @expect.Expectation[Int],
  loc~ : SourceLoc,
) -> Unit raise Error {
  self.assert_that(
    self.actual % 2 == 0,
    "to_be_even",
    expected=() => "an even number",
    received=() => @debug.to_string(self.actual),
    loc~,
  )
}

test "custom matcher" {
  @expect.expect(4).to_be_even()
  @expect.expect(3).not().to_be_even()
}

expect(received).to_be_even()
Expected: an even number
Received: 3

• expected describes what the matcher wants. After not(), the message adds not in front of it.
• received shows the value under test.
• args names the arguments in the headline, for example args="total" gives to_have_total(total).
• details adds lines after Received, for example details=() => [("Total", total.to_string())].

test "to_be_even message" {
  inspect(
    @expect.failure_message(() => @expect.expect(3).to_be_even()),
    content=(
      #|expect(received).to_be_even()
      #|Expected: an even number
      #|Received: 3
    ),
  )
  @expect.expect_failure(() => @expect.expect(3).to_be_even())
  .to_contain("Expected: an even number")
}

#Failure messages

src/point_test.mbt:10:3-10:58@me/app FAILED: expect(received).to_equal(expected)
Expected: { x: 1, y: 3 }
Received: { x: 1, y: 2 }
Diff (- expected, + received):
  @@ -1,4 +1,4 @@
   {
     x: 1,
  -  y: 3,
  +  y: 2,
  ?     ^
   }

• The location is the matcher call, so a test with many assertions shows which one failed.
• to_equal adds a git-style line diff when a value spans more than one line once it is pretty-printed. That includes structs, arrays and multi-line strings. The values are pretty-printed with one field or element per line, so the diff shows exactly which fields changed. Unchanged lines far from a change are left out, and each group of changes gets its own @@ hunk header. For long values, only the diff is shown.
• When one line replaces another and most of it is the same, a ? line puts carets under the characters that changed.
• When to_equal fails on two single-line strings, a caret points at the first difference. Long strings are cut to the text around it:

  Expected: "hello world"
  Received: "hello wurld"
                    ^ first difference at index 7

• Bytes values show as a hex dump, as hexdump -C does. When to_equal fails on two Bytes values, a Difference line shows the first differing offset.
• When to_equal fails on two maps, the message lists the Missing, Extra and Changed keys instead of a line diff. Maps are equal in any order, so a line diff could show changes that are only a different order.
• Values that span more than one line start on their own line. Values longer than 30 lines are shortened.
• A negated matcher shows .not in the first line and not in the Expected line.

struct Point {
  x : Int
  y : Int
} derive(Eq, Debug)

#Custom formatting

struct Money {
  cents : Int
} derive(Eq)

impl @debug.Debug for Money with fn to_repr(self) {
  let dollars = self.cents / 100
  let cents = self.cents % 100
  let padding = if cents < 10 { "0" } else { "" }
  Repr::literal("$\{dollars}.\{padding}\{cents}")
}

struct Account {
  owner : String
  password : String
  balance : Money
} derive(Eq)

impl @debug.Debug for Account with fn to_repr(self) {
  Repr::record({
    "owner": Repr(self.owner),
    "password": Repr::omitted(),
    "balance": Repr(self.balance),
  })
}

expect(received).to_equal(expected)
Expected: { owner: "Ada", password: ..., balance: $10.50 }
Received: { owner: "Ada", password: ..., balance: $10.05 }
Diff (- expected, + received):
  @@ -1,5 +1,5 @@
   {
     owner: "Ada",
     password: ...,
  -  balance: $10.50,
  +  balance: $10.05,
  ?               ^^
   }

#Development

#License