ExpressionAssertion

Defined in: packages/engine/src/testing/index.ts:236

Assertions about the result of one evaluated expression, returned by expectExpression. Every matcher returns this, so assertions chain, and throws an ExpectationError when it fails.

Constructors

Constructor

new ExpressionAssertion(
   expression,
   outcome,
   engine?
): ExpressionAssertion;

Defined in: packages/engine/src/testing/index.ts:243

Parameters

Parameter	Type	Description
expression	string	The text evaluated, named in every failure message.
outcome	Outcome	What evaluating it gave.
engine?	ExpressionEngine	The engine it was evaluated on, which settled re-evaluates on. Absent for a line of a document, whose outcome is final.

Returns

ExpressionAssertion

Accessors

value

Get Signature

get value(): Value;

Defined in: packages/engine/src/testing/index.ts:311

The raw resolved Value, for an assertion the matchers do not cover. Throws if the expression failed.

Returns

Value

Methods

settled()

settled(options?): Promise<ExpressionAssertion>;

Defined in: packages/engine/src/testing/index.ts:266

Wait for a Pending result to settle, then re-evaluate, so every matcher after it reads the settled answer: the value the live data resolved to, or the fetch’s coded failure.

It loops within one deadline, because a line can reveal a second fetch once its first lands: evaluate, ExpressionEngine.settle, evaluate again, until the result is not Pending. A result that was never Pending returns at once, without waiting.

Parameters

Parameter	Type
options?	SettleOptions

Returns

Promise<ExpressionAssertion>

This assertion, now holding the settled outcome.

Throws

ExpectationError EXPECTED_SETTLED (rejected) when the result is still Pending at the deadline, or the assertion was built for a document line rather than by expectExpression.

---

toBeError()

toBeError(): this;

Defined in: packages/engine/src/testing/index.ts:391

Assert the expression failed (a thrown engine error or a plugin-raised error value). Says nothing about the code.

Returns

this

---

toBePending()

toBePending(): this;

Defined in: packages/engine/src/testing/index.ts:434

Assert the expression returned a value still resolving asynchronously. A package whose result comes from an async resolver reports pending on first evaluation; this is how a test confirms the async path was taken without waiting for it. toResolveTo waits and checks the answer.

Returns

this

---

toEqual()

toEqual(expected, unit?): this;

Defined in: packages/engine/src/testing/index.ts:347

Assert the expression evaluated to expected, and, when unit is given, that the result carries exactly that unit. A number compares against the value’s numeric magnitude within a small floating-point tolerance; a string compares against the value’s own string; a boolean against its boolean reading. Omitting unit leaves the unit unchecked, so toEqual(5) passes for both 5 and 5 gp.

Parameters

Parameter	Type
expected	string | number | boolean
unit?	string

Returns

this

---

toEvaluate()

toEvaluate(): this;

Defined in: packages/engine/src/testing/index.ts:327

Assert the expression evaluated to a value (not an error, not a pending async result). Says nothing about what the value is.

Returns

this

---

toFailWith()

toFailWith(code): this;

Defined in: packages/engine/src/testing/index.ts:408

Assert the expression failed with exactly code, the error catalog code (e.g. "UNDEFINED_VARIABLE", or a package’s own code). Reports the code it actually got when they differ, so a near-miss is obvious.

Parameters

Parameter	Type
code	string

Returns

this

---

toResolveTo()

toResolveTo(
   expected,
   unit?,
   options?
): Promise<ExpressionAssertion>;

Defined in: packages/engine/src/testing/index.ts:305

Wait for the result to settle (see settled), then assert it equals expected, with unit when given, exactly as toEqual does. The matcher for a package’s async resolver: the first evaluation is Pending by contract, and this is what it resolves to.

Parameters

Parameter	Type
expected	string | number | boolean
unit?	string
options?	SettleOptions

Returns

Promise<ExpressionAssertion>

Example

await expectExpression(engine, "tide at Dover").toResolveTo(4.2, "m");