@rbxts/expect > ExpectMessageBuilder > reason

ExpectMessageBuilder.reason() method

Sets a value to use for the reason.

Signature:

reason(reason?: string): this;

Parameters

Parameter	Type	Description
reason	string	(Optional) A displayable value to use as a replacement for reason, or undefined to reset it to nothing.

Returns:

this

This instance, for chaining.

Remarks

If the message does not have a ${place.reason} in it, but was thrown with a reason attached via this method- then the reason will be displayed before the metadata, in the same format of Reason: message.

Example 1

Lets say we were checking if two values are equal:

const baseMessage = new ExpectMessageBuilder(
  `Expected ${place.name} to ${place.not} equal ${place.expected.value}, but ${place.reason}`
);

const equal: CustomMethodImpl<defined> = (
  _,
  actual: defined,
  expected: defined
) => {
  const message = baseMessage.use().expectedValue(expected);

  if(typeOf(actual) !== typeOf(expected)) {
    return message.reason("it was a different type").fail();
  }

  if(actual !== value) {
    return message.reason("it had a different value").fail();
  }

  // apply a default reason for negations
  return message.reason("it did").pass();
};

Example output:

Expected "4" to equal '4', but it was a different type

Example 2

If our message didn't have a reason placeholder in it, like so:

new ExpectMessageBuilder(
  `Expected ${place.name} to ${place.not} equal ${place.expected.value}`
);

But we still called reason in our logic, then it would get attached as metadata, but before any existing metadata:

Expected "4" to equal '4'
Reason: it was a different type