5 Data Structure Expectations

8.12

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

procedure
(expect-vector-length len-exp) → expectation?
len-exp : (or/c exact-nonnegative-integer? expectation?)

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: 3 and 2 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: 3 and 2 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 2 'bar 'foo)
  expected: not 'foo or 'bar contained with set-member?
  actual: (set 1 2 'bar '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 2 3)
  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 'c 'a)
  fault: expected values to not be contained
   in: the set of keys
   expected: not 'c contained with set-member?
   actual: (set 'c 'a)
> (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.

value
the-length-context : splice-context?

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

An apply-context containing the procedure used to extract the length of the sequence, e.g. vector-length.
the-return-context
A sequence-context with position 0, representing the first (and only) return value.

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.

value
the-keys-context : splice-context?

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

value
the-box-context : context?

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.

1	Data Model
2	Using Expectations with Rack Unit
3	Comparison and Equality Expectations
4	Boolean and Logic Expectations
5	Data Structure Expectations
6	Text and String Expectations
7	Structure Expectations
8	Procedure Expectations
9	Macro Expansion Expectations
10	Expectation Combinators
11	Meta Expectations
12	Conversion to Expectations