PackageAssertion

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

Assertions about a package’s declared descriptor, returned by expectPackage. These catch the three mistakes the issue calls out, before the package is ever registered. Every matcher returns this and throws an ExpectationError when it fails.

Constructors

Constructor

new PackageAssertion(pkg): PackageAssertion;

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

Parameters

Parameter	Type
pkg	IEnginePackage

Returns

PackageAssertion

Methods

notToCollideWith()

notToCollideWith(others, strictness?): CompatibilityReport;

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

Assert the package does not collide with any of others in a way that would silently break one of them (two packages claiming the same lexer keyword, plugin-function index, async-resolver namespace, and so on).

strictness sets which severities fail the assertion: "error" (the default) fails only on the collisions that always break something, "warning" also fails on the ones that silently pick a winner, "info" fails on cosmetic overlaps too.

Parameters

Parameter	Type	Default value
others	IEnginePackage[]	undefined
strictness?	CollisionStrictness	"error"

Returns

CompatibilityReport

the full compatibility report, so a test can inspect every conflict, including ones below the strictness threshold.

---

notToShadow()

notToShadow(words?): ShadowedWord[];

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

Assert none of the package’s claimed words shadow a prose word.

A trigger word that is also an ordinary word turns a line of prose into arithmetic, the single most common package mistake and the subject of the trigger-words guide. This checks the words the package declares (lexer keywords, units, operators, and single-word phrases) against words (defaulting to COMMON_PROSE_WORDS), case-insensitively.

Parameters

Parameter	Type	Default value
words?	readonly string[]	COMMON_PROSE_WORDS

Returns

ShadowedWord[]

the shadowed words, empty when the package is clean, for a test that wants to inspect rather than assert.

---

toBeWellFormed()

toBeWellFormed(): this;

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

Assert the package is put together so every part it declares can be reached (#719). Each of these used to be accepted without a word and then fail, or never run, at the first line that used it:

• it has a name (registration keys everything by name, so a second nameless package unregistered the first);
• it registers against the built-ins;
• a token its keywords, operators, phrases or calls produce that no parselet reads is not meant for a parselet the package keys under another name (twice making DOUBLE_KW while the parselet waits for DOUBLE). A token read inside another parselet’s grammar (the and of between X and Y) is not a mistake, and is not reported;
• no parselet claims a token the parser reads itself (NUMBER, +, …), where it would never run;
• each token type of its own has a tokenCategories entry, so an editor can colour it;
• each plugin function its parselets call by name is in pluginFunctions, found by compiling the package’s own words in the shapes a line puts them in (word 1, word(1), 1 op 1). A call reached only by some other shape is not seen.

Every problem is reported at once rather than the first alone.

Returns

this

---

toDeclareCompatibleEngineVersion()

toDeclareCompatibleEngineVersion(engineVersion?): this;

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

Assert the package’s declared engineVersion range is satisfied by the running engine (or by engineVersion when given).

A package that declares a range and never checks it resolves is the third mistake the issue names: it looks fine until the one engine version it cannot run against, where the range either fails to match or turns out to be a malformed string. A package with no declared range passes (no constraint is always compatible).

Parameters

Parameter	Type	Default value
engineVersion?	string	ENGINE_VERSION

Returns

this