Ocha | API

expect()

Use the expect() mixin to write an assertion. Pass a value to check, and then a series of language functions. Most assertions also require a final value to compare with.

@import 'true';
@import 'ocha';

@include test-module('Test Module') {
  @include test('Test') {
    $value: 5;
    @include expect($value to equal 5);
  }
}

Language Chains

These functions don't do anything—they just make your assertion more readable.

to
be
been
is
which
and
has
have
with
at
of
same

Flags

not

Throw the word not in an assertion to check for the opposite result.

Note that, since not is a special keyword in Sass, you have to put it in quotes.

@include expect(5 to 'not' equal 6);

deep

Pair with equal or property to fully check the contents of a map.

$map: (
  cats: ( dogs: true ),
  kittens: false,
);

@include expect($map to have deep property 'cats.dogs');

@include expect($map to deep equal $map);

Comparison

equal($value)

Check if a value equals $value.

@include expect(5 to equal 5);
@include expect('string' to equal 'string');

Add the deep flag to check if the contents of an entire map are identical.

$map: (
  cats: ( dogs: true ),
  kittens: false,
);

@include expect($map to deep equal $map);

eql($map)

Check if two maps are identical in structure. This is the same as deep equal.

$map: (
  cats: ( dogs: true ),
  kittens: false,
);

@include expect($map to eql $map);

above($floor)

Check if a value is greater than $floor.

@include expect(5 to be above 3);

least($floor)

Check if a value is greater than or equal to $floor.

@include expect(5 to be at least 5);
@include expect(10 to be at least 5);

below($floor)

Check if a value is less than $floor.

@include expect(5 to be below 3);

most($floor)

Check if a value is less than or equal to $floor.

@include expect(5 to be at most 5);
@include expect(10 to be at most 5);

within($floor, $ceiling)

Check if a value is within the range of $floor and $ceiling (including those values).

@include expect(5 to be within (0, 10));

closeTo($base, $range)

Check if a value is equal to $base, plus or minus $range.

// Can be between 2 and 8
@include expect(7 to be closeTo (5, 3));

oneOf($list)

Check if a value is one of the items in $list.

@include expect(1 to be oneOf (1, 2, 3));
@include expect(5 to be oneOf (1, 2, 3));

Type Comparison

a($type)

Check if a value has the type of $type.

@include expect(5 to be a number);
@include expect('string' to be a string);
@include expect(#fff to be a color);
@include expect((0, 1, 2) to be a list);

ok

Check if a value is truthy:

true
A list or map that isn't empty
A number greater than 0

@include expect(true to be ok);

true

Check if a value is true. Note that this function has to be used with quotes around it, because it's a special keyword in Sass.

@include expect(true to be 'true');

false

Check if a value is false. Note that this function has to be used with quotes around it, because it's a special keyword in Sass.

@include expect(false to be 'false');

null

Check if a value is null. Note that this function has to be used with quotes around it, because it's a special keyword in Sass.

@include expect(null to be 'null');

Inspection

lengthOf($length)

Check if a list has a length equal to $length.

$list: (0, 1, 2);
@include expect($list to have lengthOf 3);

length

Check if a list has a length that satisfies a certain criteria. Pair it with above, least, below, most, or within.

$list: (0, 1, 2);
@include expect($list to have length above 1);
@include expect($list to have length below 4);
@include expect($list to have length within (0, 5));

empty

Check if a list has a length of 0.

$list: ();
@include expect($list to be empty);

string($substring)

Check if a string contains $substring.

@include expect('string' to have string 'str');

contain($needle)

Check if a string contains $needle, or check if a list contains $needle.

@include expect('string' to contain 'str');
@include expect((one, two) to contain 'one');

include($needle)

Check if a string contains $needle, or check if a list contains $needle.

@include expect('string' to include 'str');
@include expect((one, two) to include 'one');

property($property, $value)

Check if a map contains property $property, or if a list has an item at the index of $property. Optionally, you can check if that property also contains $value.

$map: (
  'kittens': 10,
  'puppies': 6,
  'otters': 4,
);

@include expect($map to have property 'kittens');
@include expect($map to have property ('puppies', 6));

Add the deep flag to check for a deep property within a map or list. Each map key or list index is separated by a dot.

$map: (
  'kittens': 10,
  'puppies': 6,
  'otters': 4,
  'other': (
    'bunnies': 1,
    'ocelots': 2,
    'evenMore': ('birds', 'penguins', 'turkeys'),
  ),
);

@include expect($map to have property 'other.bunnies');
@include expect($map to have property ('other.bunnies', 2));
@include expect($map to have property ('other.evenMore.2', 'penguins'));

keys($keys)

If you call keys by itself, check if a map contains every key within $keys and no other keys.

$map: (
  one: 'one',
  two: 'two',
);

@include expect($map to have keys (one, two));

If you call contain keys, check if a map contains every key within $keys. If the map has other keys, that's fine.

$map: (
  one: 'one',
  two: 'two',
);

@include expect($map to have keys (one));

If you call any keys, check if a map contains any key within $keys.

$map: (
  one: 'one',
  two: 'two',
);

@include expect($map to have keys (one, two, three, four));

members($list)

Check if the input list is a superset of $list, or that the input list is identical to $list;

$list: (0, 1, 2,);

@include expect($list to have members (0, 1,)); // =&gt; true
@include expect($list to have members (0, 1, 2,)); // =&gt; true
@include expect($list to have members (0, 3, 5,)); // =&gt; false