expect

expect builds an expectation about an actual value. The current matcher is be, which uses Raku's smartmatch operator (~~).

Basic form

expect(actual).to.be(expected);

expect returns a builder, .to is a no-op for readability, and .be(expected) performs the comparison.

it 'compares values', {
  expect(1 + 1).to.be(2);
  expect('hi'.uc).to.be('HI');
  expect(@list).to.be([1, 2, 3]);
}

Smartmatch semantics

Because be uses ~~ (via the built-in BeMatcher), you can match against types, regexes, ranges, junctions, and anything else Raku smartmatches:

expect(42).to.be(Int);              # type
expect('hello').to.be(/hell/);      # regex
expect(5).to.be(1..10);             # range
expect($x).to.be(any(1, 2, 3));     # junction

Plain values are wrapped in BeMatcher automatically. To plug in your own logic, pass any object that does the Matcher role, or use define-matcher for the lighter, callback-based form. Combine matchers with .and / .or. See Composable Matchers. For Raku-native any / all / one / none junctions, see Junctions.

Negation

.not flips the comparison:

expect(1 + 1).to.not.be(3);

Reading from let

expect recognises a single named-pair argument as a let lookup:

let(:answer, { 42 });

it 'matches the let', {
  expect(:answer).to.be(42);
}

You can also pass a Pair as the expected value to read from a let:

let(:answer, { 42 });

it 'compares two lets', {
  expect(:answer).to.be(:answer);
}

For other ways to read a let, see let.

Failure output

When an expectation fails, the runner records the file and line of the expect call and prints them in the failure summary so you can jump straight to the offending line.

For diffable shapes (strings, arrays, hashes, sets, bags, mixes), the failure block also includes a colorized Diff: section that highlights only the changed regions. See Diff Output for the full conventions.

Built-in matchers beyond be

expect(...).to.<matcher>(...) is the general form. The current built-ins:

expect([1, 2, 3]).to.eq([1, 2, 3]);
expect([1, 2, 3]).to.contain-exactly(3, 1, 2);
expect([1, 2, 3]).to.match-array([3, 1, 2]);
expect([1, 2, 3]).to.include(2);
expect({ a => 1 }).to.include(:a(1));
expect('hello').to.include('ell');
expect([1, 2, 3]).to.start-with(1, 2);
expect([1, 2, 3]).to.end-with(2, 3);
expect('hello world').to.start-with('hello');
expect('hello world').to.end-with('world');
expect([1, 2, 3]).to.all(Int);
expect(42).to.be-a(Int);
expect(42).to.be-an(Int);
expect(Dog.new).to.be-an-instance-of(Dog);
expect(Calculator.new).to.respond-to('add', 'subtract');
expect(5).to.be-between(1, 10);
expect(5).to.be-between(1, 10).exclusive;
expect(3.14e0).to.be-within(0.01e0).of(3.15e0);
expect(True).to.be-truthy;
expect(False).to.be-falsy;
expect(Nil).to.be-nil;
expect(Int).to.be-nil;          # undefined type object
expect(42).to.not.be-nil;
expect('abc123').to.match(/\d+/);
expect('HELLO').to.match(rx:i/hello/);
expect({ die "boom" }).to.raise-error;
expect({ 1 + 1 }).to.not.raise-error;
expect({ X::AdHoc.new(payload => 'oops').throw }).to.raise-error(X::AdHoc);
expect({ die "code=42" }).to.raise-error(X::AdHoc, /'code=42'/);
expect({ die "alpha" }).to.raise-error(/alpha/);
expect({ die "boom" }).to.raise-error.with-message('boom');
expect({ die "code=42" }).to.raise-error(X::AdHoc).with-message(/'code=42'/);
my $counter = 0;
expect({ $counter++ }).to.change({ $counter });
expect({ 1 + 1 }).to.not.change({ $counter });
my $balance = 0;
expect({ $balance = 100 }).to.change({ $balance }).from(0).to(100);
expect({ $balance += 50 }).to.change({ $balance }).from(100);
expect({ $balance -= 150 }).to.change({ $balance }).to(0);
expect({ $balance += 25 }).to.change({ $balance }).by(25);
expect({ $balance -= 10 }).to.change({ $balance }).by(-10);
expect({ $balance += 5 }).to.change({ $balance }).by-at-least(1).by-at-most(10);
expect(Promise.kept('done')).to.be-kept;
expect(Promise.broken('boom')).to.be-broken;
expect(start { compute() }).to.be-kept(0.5);
expect(Promise.kept('done')).to.complete-within(1);
expect(Promise.new).to.not.complete-within(0.05);
expect(Supply.from-list(1, 2, 3)).to.emit(1, 2, 3);
expect(Supply.from-list(1, 2, 3, 4)).to.emit-at-least(2);
expect(Supply.from-list(1, 2)).to.complete;
expect({ get-status() }).to.eventually.be('done');
expect({ counter() }).to.eventually(:timeout(5), :interval(0.1)).be-greater-than(100);
expect({ load() }).to.not.eventually(:timeout(0.1)).be('error');

Custom matchers

be accepts any object that does the Matcher role. The matcher's matches, failure-message, and failure-message-negated methods drive the result and the failure summary, so user-defined matchers plug in the same way as the built-in ones.

Failure behavior

When an expect(...) matcher fails, the failure is recorded on Failures.list and the example body stops executing: anything after the failing line is skipped. The example is reported once in the run summary regardless of how many expect statements its body contained.

This matches RSpec's default. Ideally each it block contains exactly one expect so the first miss is also the last. When you do need multiple expectations in a single example, wrap them in aggregate-failures { ... }. The throw is suppressed inside the block, every expectation runs, and the inner failures are rolled up into a single labeled Failures row at the aggregate-failures line. See aggregate-failures.

If you're writing meta-tests that deliberately trigger a failure and then inspect the recorded Failure records, use capture-failures { ... } instead. It suppresses the throw and returns the captured failures without polluting the surrounding example. See aggregate-failures § capture-failures for meta-tests.