Composable Matchers

Combine matchers with .and and .or to express compound expectations without writing a one-off custom matcher. Every type that does the Matcher role gets these two methods automatically, so they work with built-in matchers, hand-rolled does Matcher classes, and define-matcher factories alike.

`.and`#

AndMatcher requires every inner matcher to pass. It short-circuits at the first failure and reports which inner matcher rejected the value.

use BDD::Behave;
use BDD::Behave::Matcher::Core;
use BDD::Behave::Matcher::Numeric;

it 'is a small positive integer', {
  my $small-positive = BeMatcher.new(:expected(Int))
    .and(BeGreaterThanMatcher.new(:expected(0)))
    .and(BeLessThanMatcher.new(:expected(100)));

  expect(50).to.be($small-positive);       # passes
  expect(200).to.not.be($small-positive);  # passes
}

Pass multiple matchers to a single .and call to combine them in one step:

BeMatcher.new(:expected(Int)).and(
  BeGreaterThanMatcher.new(:expected(0)),
  BeLessThanMatcher.new(:expected(100)),
);

Chained .and calls flatten into a single AndMatcher, so the failure message and description stay readable regardless of how many you compose.

`.or`#

OrMatcher passes when any inner matcher passes. It short-circuits at the first match and reports matched-index for tooling.

my $endpoint-ish = StartWithMatcher.new(:expected(['/api/']))
  .or(StartWithMatcher.new(:expected(['/v2/'])));

expect('/api/users').to.be($endpoint-ish);   # passes
expect('/v2/items').to.be($endpoint-ish);    # passes
expect('/admin').to.not.be($endpoint-ish);   # passes

As with .and, multiple-arg calls and chained calls both flatten.

Composing with custom matchers#

define-matcher factories return ordinary matchers, so they compose the same way:

my &positive = define-matcher 'positive', match => -> $a { $a > 0 };
my &small    = define-matcher 'small',    match => -> $a { $a < 100 };

expect(50).to.be(positive().and(small()));     # passes
expect(200).to.not.be(positive().and(small())); # passes

Mixing `.and` and `.or`#

Composition is left-associative: each call returns a new composite, so chains build up naturally.

# (A and B) or C
$a.and($b).or($c);

# A and (B or C): group with an explicit inner composite
$a.and($b.or($c));

Reach for an explicit nested matcher when precedence matters.

Negation#

.not flips the composite result the same way it flips any other matcher:

Composite	Under `.not` passes when…
`AndMatcher`	At least one inner matcher fails
`OrMatcher`	Every inner matcher fails

Failure messages for the negated forms tell you why the composite ended up matching when it wasn't supposed to (which AndMatcher couldn't escape, or which OrMatcher branch matched).

Failure messages#

AndMatcher failure messages identify the first inner matcher that rejected the value:

expected 200 to be greater than 0 and be less than 100, but be less than 100 failed: expected 200 to be less than 100

OrMatcher failure messages list every inner matcher and note that none matched:

expected 7 to be 5 or be 10, but none matched

Negated AndMatcher and OrMatcher failure messages mirror the structure above with not to ….

Inspecting composites#

Both composites expose useful state for diagnostics and custom formatters:

Method	Returns
`.matchers`	The flattened inner matcher list.
`AndMatcher.failing-index`	Index of the first inner matcher that failed (or `Int`).
`AndMatcher.failing-matcher`	The first inner matcher that failed (or `Nil`).
`OrMatcher.matched-index`	Index of the first inner matcher that matched.
`OrMatcher.matched-matcher`	The first inner matcher that matched.
`.expected-value`	A `List` of every inner matcher's `expected-value`.
`.description`	Inner descriptions joined with `and` / `or`.

Argument validation#

.and and .or accept only objects that do the Matcher role. Passing anything else dies immediately with a clear message: composition catches typos at the call site rather than papering over them with surprising smartmatch semantics.