InvalidCallSpecification

Rasuvaeff\Understudy\Exception\InvalidCallSpecification

Class — Package: rasuvaeff/understudy — Source — Version: v1.1.0-1-g6ed023f

Extends: LogicException

Implements: Throwable, Stringable, Exception\UnderstudyError

A specification of the wrong SHAPE: the closure handed to when()/verify()/ calls() made no direct call on an understudy, made it on a static method or threw first; a tail matcher was not the last argument; the specification stopped before the required parameters ran out without saying so with Arg::rest(); a combinator was given nothing to combine; verify() was handed arguments that contradict each other; a facade was handed an object that is not a double; a protocol was armed over one still running.

The line between this class and Exception\InvalidSpecificationArgument: this one is about how a specification is written — what is called, where, how many times — and that one about a VALUE inside it that no run could act on (an inverted range, a count below zero, a pattern PCRE cannot compile, a type that is not loadable). A LogicException, because the test is malformed rather than given a bad number.

Methods

noCallRecorded()

static noCallRecorded(): self

The closure ran to its end without any generated method signalling: it called nothing on a double, or only something that is not one.

moreThanOneCall()

static moreThanOneCall(
    non-empty-string $firstLabel,
    non-empty-string $firstMethod,
    non-empty-string $lastLabel,
    non-empty-string $lastMethod,
): self

The closure called more than one double method. Nested in the arguments of another (find($r->count())) or one after the other (a() + b()), the recording cannot tell which one the test meant, and neither reading is safe to guess.

• $firstLabel — the double the first call was made on
• $firstMethod — the first call dispatched — for a nested pair, the inner one
• $lastLabel — the double the last call was made on
• $lastMethod — the last call dispatched — for a nested pair, the outer one

returnsOnVoid()

static returnsOnVoid(non-empty-string $label, non-empty-string $method): self

returns() on a method declared : void: the value would never be observed, and a test that relies on it is checking nothing.

• $label — the double, as a refusal names it
• $method — the method declared : void

returnsOnNever()

static returnsOnNever(non-empty-string $label, non-empty-string $method): self

returns() on a method declared : never, which cannot return at all.

• $label — the double, as a refusal names it
• $method — the method declared : never

notADouble()

static notADouble(non-empty-string $facade): self

Handed the object directly, so there is no closure to blame — naming one sends the reader looking for a mistake they have not made.

• $facade — the method that was given the object

neverBesideACount()

static neverBesideACount(non-empty-string $bound): self

The wording is the analysers' word for word, and deliberately so: a user who saw the report before running the suite must not have to recognise a second phrasing of the same mistake afterwards.

• $bound — the count argument written beside never

exactCountBesideABound()

static exactCountBesideABound(): self

verify($call, times: 2, minimum: 1): an exact count leaves a bound nothing to constrain, so one of the two is a mistake.

misplacedTailMatcher()

static misplacedTailMatcher(
    non-empty-string $method,
    int $position,
    non-empty-string $matcher,
): self

Builds the error for a tail matcher in the wrong position.

emptyCombinator()

static emptyCombinator(non-empty-string $matcher): self

Builds the error for an empty matcher combinator.

guardAlreadyNarrowed()

static guardAlreadyNarrowed(
    non-empty-string $method,
    non-empty-string|null $description,
): self

Builds the error for a second where() on one expectation. Replacing the first guard silently would narrow the call by the last sentence anyone wrote, which is not what a fluent chain reads like.

• $description — how the first guard reads

tailMatcherInCombinator()

static tailMatcherInCombinator(
    non-empty-string $matcher,
    non-empty-string $operand,
): self

Builds the error for putting a tail matcher inside a combinator.

matcherInsideArray()

static matcherInsideArray(
    non-empty-string $method,
    int $position,
    non-empty-string $matcher,
): self

Builds the error for a matcher nested inside an array argument.

• $method — the method the specification named
• $position — zero-based position of the array argument
• $matcher — how the buried matcher describes itself

captorInCombinator()

static captorInCombinator(non-empty-string $matcher): self

Builds the error for a captor inside a combinator.

• $matcher — the combinator the captor was passed to, without Arg::

emptySequence()

static emptySequence(): self

expectSequence() with no steps: arming an empty protocol would put every later call on trial with nothing to try it against.

protocolAlreadyArmed()

static protocolAlreadyArmed(positive-int $position, positive-int $length): self

Builds the error for arming a protocol while another is active.

incompleteSpecification()

static incompleteSpecification(
    non-empty-string $method,
    int<0, max> $given,
    int<0, max> $declared,
): self

Builds the error for an incomplete call specification.

omittedBeforeSpecified()

static omittedBeforeSpecified(
    non-empty-string $method,
    int<0, max> $omitted,
    int<0, max> $specified,
): self

Builds the error for an omitted argument before a specified one.

omittedTailNeedsRest()

static omittedTailNeedsRest(non-empty-string $method, non-empty-string $matcher): self

Builds the error for an omitted required tail without Arg::rest().

closureFailed()

static closureFailed(Throwable $previous): self

The specification closure threw before any generated method signalled; the original is kept as previous, because it is the actual mistake.

staticMethodCalled()

static staticMethodCalled(non-empty-string $method): self

Builds the error for a static method used in a specification.