Upstream: https://github.com/facebook/jest/tree/v27.4.7/packages/expect
This package exports the expect
function used in Jest. You can find its documentation in the Jest documentation.
⚠️ Sincenot
is a reserved keyword in Lua, we usenever
.⚠️ Several changes to matchers are made to maintain Lua-nativity. Corresponding changes are made to tests.-
toBeInstanceOf
can be used to check that the received value is an instance (or a derived instance) of the expected value, where the expected value is a prototype class. The matcher will error if either the received or expected value isn't an object. -
toBeDefined
is omitted andtoBeUndefined
check fornil
since there is noundefined
in Lua. -
toBeFalsy
andtoBeTruthy
checks for Lua falsy and truthy values, not JS ones -
toHaveLength
checks using the Lua length operator by default, but instead checks for alength
property if the object has one⚠️ Length is only well defined for (non-sparse) array-like tables since the Lua#
operator returns 0 for tables with key-value pairs
-
toHaveLength
does not accept functions, can't get the argument count of a function in Lua -
toMatch
matches Lua string patterns or a LuauPolyfillRegExp
whereastoContain
matches exact substrings -
toStrictEqual
is omitted, there is no strict equality in Lua - The
Any
matcher is used to match any instance of a type or object given a constructor function. Lua doesn't have constructors for primitive types. Our deviation for this matcher therefore accepts either a typename string (e.g. "number", "boolean") or a table representing a prototype class, and will error otherwise.- If a typename string is passed in, the type is compared against the string.
- If a table is passed in, it checks that the object passed in is an instance (or a derived instance) of the provided prototype class.
any("number"):asymmetricMatch(1) -- true any("number"):toAsymmetricMatcher() -- "Any<number>" any(ClassA):asymmetricMatch(ClassA.new()) -- true any(ClassA):asymmetricMatch(ClassB.new()) -- false any(ClassA):asymmetricMatch(ChildOfClassA.new()) -- true
-
StringMatching
accepts Lua string patterns or a LuauPolyfillRegExp
⚠️ Although Jest has use cases wheretoHaveProperty
is used to detect the existence of a property asundefined
, we should never try to usetoHaveProperty
withnil
as the property to check for-
toStrictEqual
does not check for array sparseness orundefined
properties like in Javascript. Its only difference fromtoEqual
is that it also applies a Lua type/class check based on the Lua prototypical metatable inheritance pattern
-
⚠️ isError returnstrue
for string and table types since we don't have a designated error type in Lua and these two types are what can be used to trigger an error- The throwing matchers (e.g.
toThrow()
) will print out stack traces for ALL types (exceptnil
) that are thrown whereas in Javascript the stack trace is only printed if you error with an Error type. In other words, executing atoThrow
matcher on something likethrow ''
in Javascript will not end up printing the stack trace but doing so witherror("")
will print the stack trace for our Lua equivalent. ⚠️ When writing custom matchers withexpect.extend()
, a first argumentself
is needed to receive thematcherContext
. It can be left empty with_
if thematcherContext
is not be needed.⚠️ Custom throwing matchers should throw errors that follow one of three patterns. Jest Lua will attempt totostring
values that do not match these patterns and may result in undefined behavior.- strings
- tables with a
message
key that has a string value - objects with a
__tostring
metamethod
⚠️ Currently, the spyMatchers have undefined behavior when used with jest-mock and function calls withnil
arguments, this should be fixed by ADO-1395 (the matchers may work incidentally but there are no guarantees)