On this page:
expect-list
expect-list-ref
expect-list-length
expect-vector
expect-vector-ref
expect-vector-length
expect-set
expect-set-member?
expect-set-not-member?
expect-superset
expect-subset
expect-set-count
expect-hash
expect-hash-ref
expect-hash-count
expect-hash-keys
expect-box
expect-syntax
5.1 Data Structure Contexts and Attributes
sequence-context
make-sequence-context
the-length-context
dict-context
make-dict-context
the-keys-context
the-box-context
syntax-context?
7.7

5 Data Structure Expectations

procedure

(expect-list item-exp ...)  expectation?

  item-exp : any/c
Returns an expectation that expects a value is a list whose elements satisfy the item-exp expectations. Each item-exp is converted to an expectation with ->expectation. The length of the list is also checked, and only the item-exp expectations for lists that contain enough items to include the corresponding item-exp are checked.

Examples:
> (define num+string-expectation
    (expect-list (expect-pred number?) (expect-pred string?)))
> (expect! '(10 "text") num+string-expectation)
> (expect! '(foo bar) num+string-expectation)

multiple failures

  subject: '(foo bar)

  fault: expected a different kind of value

   in: item at position 0

   expected: number?

   actual: 'foo

  fault: expected a different kind of value

   in: item at position 1

   expected: string?

   actual: 'bar

> (expect! '(foo) num+string-expectation)

multiple failures

  subject: '(foo)

  fault: expected a different value

   in: the number of items

   expected: eqv? to 2

   actual: 1

  fault: expected a different kind of value

   in: item at position 0

   expected: number?

   actual: 'foo

procedure

(expect-list-ref item-exp index)  expectation?

  item-exp : any/c
  index : exact-nonnegative-integer?
Returns an expectation that expects a value is a list with an item at position index, then checks that item against item-exp. The given item-exp is converted to an expectation with ->expectation.

Examples:
> (define expect-second-string? (expect-list-ref (expect-pred string?) 1))
> (expect! '(10 "text") expect-second-string?)
> (expect! '(10 20) expect-second-string?)

expected a different kind of value

  subject: '(10 20)

  in: item at position 1

  expected: string?

  actual: 20

procedure

(expect-list-length len-exp)  expectation?

  len-exp : (or/c exact-nonnegative-integer? expectation?)
Returns an expectation that expects a value is a list, then checks the number of items in the list against len-exp. If len-exp is an integer, it is converted to an expectation with ->expectation.

Examples:
> (define expect-even-list (expect-list-length (expect-pred even?)))
> (expect! '(a b) expect-even-list)
> (expect! '(a b c) expect-even-list)

expected a different kind of value

  subject: '(a b c)

  in: the number of items

  expected: even?

  actual: 3

procedure

(expect-vector item-exp ...)  expectation?

  item-exp : any/c
Returns an expectation that expects a value is a vector whose elements satisfy the item-exp expectations. Each item-exp is converted to an expectation with ->expectation. The length of the vector is also checked, and only the item-exp expectations for vectors that contain enough items to include the corresponding item-exp are checked.

Examples:
> (define num+foo-vec-expectation (expect-vector (expect-pred number?) 'foo))
> (expect! #(10 foo) num+foo-vec-expectation)
> (expect! #(10 bar) num+foo-vec-expectation)

expected a different value

  subject: '#(10 bar)

  in: item at position 1

  expected: equal? to 'foo

  actual: 'bar

> (expect! #(10) num+foo-vec-expectation)

expected a different value

  subject: '#(10)

  in: the number of items

  expected: eqv? to 2

  actual: 1

procedure

(expect-vector-ref item-exp index)  expectation?

  item-exp : any/c
  index : exact-nonnegative-integer?
Returns an expectation that expects a value is a vector with an item at position index, then checks that item against item-exp. The given item-exp is converted to an expectation with ->expectation.

Examples:
> (define expect-second-string? (expect-vector-ref (expect-pred string?) 1))
> (expect! #(10 "text") expect-second-string?)
> (expect! #(10 20) expect-second-string?)

expected a different kind of value

  subject: '#(10 20)

  in: item at position 1

  expected: string?

  actual: 20

Returns an expectation that expects a value is a vector, then checks the number of items in the vector against len-exp. If len-exp is an integer, it is converted to an expectation with ->expectation.

Examples:
> (define expect-even-vector (expect-vector-length (expect-pred even?)))
> (expect! #(a b) expect-even-vector)
> (expect! #(a b c) expect-even-vector)

expected a different kind of value

  subject: '#(a b c)

  in: the number of items

  expected: even?

  actual: 3

procedure

(expect-set v ...)  expectation?

  v : any/c
Returns an expectation that expects a value is a set that contains exactly the given v values and no other values. The expectation finds two faults: one describing that values were missing and one describing what values were unexpected. Each of these fault is constructed in the same way as in expect-superset and expect-subset, respectively. This function does not convert its arguments to expectations, see ->expectation.

Examples:
> (expect! (set 1 2 3) (expect-set 1 2 3))
> (expect! (set 1 'foo 'bar) (expect-set 1 2 3))

multiple failures

  subject: (set 1 'bar 'foo)

  fault: expected values to be contained

   expected: 2 and 3 contained with set-member?

   actual: (set 1 'bar 'foo)

  fault: expected values to not be contained

   expected: not 'foo or 'bar contained with set-member?

   actual: (set 1 'bar 'foo)

procedure

(expect-set-member? v)  expectation?

  v : any/c
Returns an expectation that expects a value is a set containing v.

Examples:
> (expect! (set 1 2) (expect-set-member? 1))
> (expect! (set 1 2) (expect-set-member? 'foo))

expected a value to be contained

  subject: (set 1 2)

  expected: 'foo contained with set-member?

  actual: (set 1 2)

procedure

(expect-set-not-member? v)  expectation?

  v : any/c
Returns an expectation that expects a value is a set that does not contain v.

Examples:
> (expect! (set 1 2) (expect-set-not-member? 'foo))
> (expect! (set 1 2) (expect-set-not-member? 1))

expected a value to not be contained

  subject: (set 1 2)

  expected: not 1 contained with set-member?

  actual: (set 1 2)

procedure

(expect-superset st)  expectation?

  st : set?
Returns an expectation that expects a value is a set that is a superset of st. The expectation finds one fault that describes what values were missing using make-contains-all-attribute.

Examples:
> (expect! (set 1 2 3 4 5) (expect-superset (set 1 2 3)))
> (expect! (set 1 5) (expect-superset (set 1 2 3)))

expected values to be contained

  subject: (set 1 5)

  expected: 2 and 3 contained with set-member?

  actual: (set 1 5)

procedure

(expect-subset st)  expectation?

  st : set?
Returns an expectation that expects a value is a set that is a subset of st. The expectation finds one fault that describes what unexpected values were present using make-contains-none-attribute.

Examples:
> (expect! (set 1 2) (expect-subset (set 1 2 3)))
> (expect! (set 1 2 'foo 'bar) (expect-subset (set 1 2 3)))

expected values to not be contained

  subject: (set 1 'bar 2 'foo)

  expected: not 'foo or 'bar contained with set-member?

  actual: (set 1 'bar 2 'foo)

procedure

(expect-set-count count-exp)  expectation?

  count-exp : (or/c exact-nonnegative-integer? expectation?)
Returns an expectation that expects a value is a set whose number of elements is then checked against count-exp. If count-exp is an integer, it is converted to an expectation with ->expectation.

Examples:
> (expect! (set 'foo 'bar) (expect-set-count 2))
> (expect! (set 1 2 3) (expect-set-count (expect-pred even?)))

expected a different kind of value

  subject: (set 1 3 2)

  in: the number of items

  expected: even?

  actual: 3

procedure

(expect-hash k value-exp ... ...)  expectation?

  k : any/c
  value-exp : any/c
Returns an expectation that expects a value is a hash that contains exactly the given k keys and, for each key, contains a value that is then checked against the corresponding value-exp. Each value-exp is converted to an expectation with ->expectation. Extra or missing keys result in faults.

Examples:
> (expect! (hash 'a 1 'b 2) (expect-hash 'a 1 'b 2))
> (expect! (hash 'a 1 'c 3) (expect-hash 'a 1 'b 2))

multiple failures

  subject: '#hash((a . 1) (c . 3))

  fault: expected values to be contained

   in: the set of keys

   expected: 'b contained with set-member?

   actual: (set 'a 'c)

  fault: expected values to not be contained

   in: the set of keys

   expected: not 'c contained with set-member?

   actual: (set 'a 'c)

> (expect! (hash 'a 1 'b 1000) (expect-hash 'a 1 'b 2))

expected a different value

  subject: '#hash((a . 1) (b . 1000))

  in: value for key 'b

  expected: equal? to 2

  actual: 1000

procedure

(expect-hash-ref k value-exp)  expectation?

  k : any/c
  value-exp : any/c
Returns an expectation that expects a value is a hash that contains k, then checks the value for k against value-exp. The given value-exp is converted to an expectation with ->expectation.

Examples:
> (expect! (hash 'a 1 'b 2) (expect-hash-ref 'a 1))
> (expect! (hash 'a 100) (expect-hash-ref 'a 1))

expected a different value

  subject: '#hash((a . 100))

  in: value for key 'a

  expected: equal? to 1

  actual: 100

> (expect! (hash 'b 2) (expect-hash-ref 'a 1))

hash-ref: no value found for key

  key: 'a

procedure

(expect-hash-count count-exp)  expectation?

  count-exp : (or/c exact-nonnegative-integer? expectation?)
Returns an expectation that expects a value is a hash whose number of key-value pairs is then checked against count-exp. If count-exp is an integer, it is converted to an expectation with ->expectation.

Examples:
> (expect! (hash 'a 1 'b 2) (expect-hash-count 2))
> (expect! (hash 'a 1) (expect-hash-count (expect-pred even?)))

expected a different kind of value

  subject: '#hash((a . 1))

  in: the number of items

  expected: even?

  actual: 1

procedure

(expect-hash-keys set-exp)  expectation?

  set-exp : (or/c set? expectation?)
Returns an expectation that expects a value is a hash whose set of keys is then checked against set-exp. If set-exp is a set, it is converted to an expectation with ->expectation.

Examples:
> (expect! (hash 'a 1 'b 2) (expect-hash-keys (set 'a 'b)))
> (expect! (hash 'a 1) (expect-hash-keys (set 'a 'b)))

expected values to be contained

  subject: '#hash((a . 1))

  in: the set of keys

  expected: 'b contained with set-member?

  actual: (set 'a)

procedure

(expect-box exp)  expectation?

  exp : any/c
Returns an expectation that expects a box whose value is then checked against exp. If exp is not an expectation, it is converted to one with ->expectation.

Examples:
> (expect! (box 1) (expect-box 1))
> (expect! (box 100) (expect-box 1))

expected a different value

  subject: '#&100

  in: the box's value

  expected: equal? to 1

  actual: 100

procedure

(expect-syntax value-exp)  expectation?

  value-exp : any/c
Returns an expectation that expects a syntax object whose contents (as returned by syntax-e) are then checked against datum-exp. If datum-exp is not an expectation, it is converted to one with ->expectation.

Examples:
> (expect! #'foo (expect-syntax 'foo))
> (expect! #'#(1 2 3) (expect-syntax (vector #'1 #'2 #'3)))
> (expect! #'foo (expect-syntax 'bar))

expected a different value

  subject: #<syntax:eval:3:0 foo>

  in: the return value of syntax-e

  expected: equal? to 'bar

  actual: 'foo

5.1 Data Structure Contexts and Attributes

struct

(struct sequence-context context (position)
    #:transparent)
  position : exact-nonnegative-integer?

procedure

(make-sequence-context position)  sequence-context?

  position : exact-nonnegative-integer?
A context and its constructor that represents the sequence item at position in a sequence, such as those returned by in-range. Like dict-context, thiscontext may be used in faults that operate on specific kinds of sequences. See expect-list-ref for an example.

A context value that represents the length of a sequence. More specifically, it is a splice-context containing three contexts:

This context is used by expect-list-length, expect-set-count, and similar procedures.

struct

(struct dict-context context (key)
    #:transparent)
  key : any/c

procedure

(make-dict-context key)  dict-context?

  key : any/c
A context and its constructor that represents the dictionary value for key in a dictionary, as defined by the gen:dict interface. This context may be used in faults that only operate on specialized dictionaries, see expect-hash-ref for an example.

A context value that expect-hash-keys adds to its faults.

A context value that represents the contents of a box value as returned by unbox.

procedure

(syntax-context? v)  boolean?

  v : any/c
Returns true if v is the context value that expect-syntax adds to its faults.