ExpectMessageBuilder class

Builder for creating messages in an expect() method.

Signature:

declare class ExpectMessageBuilder 

Remarks

You can look at this class as a wrapper around the error messages a method can throw; while providing various utility features to make populating the message easier.

Depending on your method, you may end up not using most of what this class offers.

Details

There are three (primary) components to an expect message:

The core contents of the message
The VariableData for "actual" and "expect"
Various (optional) metadata

Core Message

The "core" of a message is the content that's not populated by placeholders.

Generally, this is static- but it doesn't have to be.

For example, given the message:

Expected '[1,2,3]' to be empty

The "core" part would be the Expected to be empty.

You can generally break this down into two components: the prefix and the suffix.

The prefix is usually static, and populated when you create your message:

new ExpectMessageBuilder(`Expected ${place.actual.value} to ${place.not} be empty`);

The "suffix" comes into play usually at runtime; where you have additional context.

Expected '[1,2,3]' to be empty, but it had 3 elements

In this case, , but it had 3 elements is the suffix.

Variable Data

The VariableData in a message corresponds to the data associated with a variable in the expression.

There are typically two variables: the "expected" variable, and the "actual" variable.

The "actual" variable is the one provided to expect() when the statement starts.

The "expected" variable is the one provided to the method that's performing the check.

expect(5).to.not.equal("5");

In this case, 5 is the "actual" variable and "5" is the "expected" variable.

Although, some checks may not have an expected variable.

expect([]).to.be.empty();

In this case, [] is the "actual" variable, but there's nothing we're comparing it to so there's not really an "expected" variable.

Metadata

The metadata in a message is additional data that follows after the message in the format of key: value with a newline for each.

Expected '[1,"2",3]' to be an array of type 'number', but there was an element of type 'number'.
Index: 1
Value: "2"

In this case, the metadata is the

Index: 1
Value: "2"

Constructors

Constructor	Modifiers	Description
(constructor)(prefix, negationPrefix, options)		Create a new instance of ExpectMessageBuilder.

Properties

Property	Modifiers	Type	Description
options	`readonly`	ExpectMessageBuilderOptions	The options configured to this instance.

Methods

Method	Modifiers	Description
actual(data)		Overwrites all the values for the actual variable.
actualType(typeStr)		Sets a value to use for the .
actualValue(value)		Sets a value to use for the actual value.
appendPrefix(str)		Adds a string to the end of the existing prefix.
build(pass, negated)		Creates an error message to display, based on the data attached to this instance.
copy()		Creates a deep copy of this instance.
encode(value, valueType, overrideOptions, array, collapsable, collapseLength)		Encodes a `value` to a string, in the same way this instance would.
expected(data)		Overwrites all the values for the expected variable.
expectedType(typeStr)		Sets a value to use for the .
expectedValue(value)		Sets a value to use for the expected value.
fail()		Returns a `Result.err` of this instance.
failureMetadata(data)		Attach data to follow after the main message, in the format of `key: value`. Only attached when the message is a failure.
failWithReason(reason)		Returns a failure with the reason attached.
index(index)		Sets a value for the index placeholder.
metadata(data)		Attach data to follow after the main message, in the format of `key: value`.
name(value)		Sets a name to use for the "actual" variable, when dealing with messages without paths.
negationSuffix(str)		Adds a string to show at the end of the message, before the metadata. Only applies if the message is negated.
nestedMetadata(data)		Attach data to follow after the main message, in the format of `key: value`. Only attached when the message has a path.
pass()		Returns a `Result.ok` of this instance.
path(str)		Sets a path to use for the "actual" variable, when dealing with nested tests.
reason(reason)		Sets a value to use for the reason.
suffix(str)		Adds a string to show at the end of the message, before the metadata.
surfaceMetadata(data)		Attach data to follow after the main message, in the format of `key: value`. Only attached when the message does NOT have a path.
toString()		Returns a built copy of this message, assuming it passed and was NOT negated.
trailingFailurePrefix(str)		Adds a string to the end of the existing prefix, but only if it's a failure.
trailingFailureSuffix(str)		Adds a string to show at the end of the message, before the metadata. Only applies if the message is a failure.
use(trailingPrefix, trailingFailurePrefix)		Create a copy of this instance, to be populated with data.