Expect
expect(received: any): lest.Matchers
The expect function is used to assert the result(s) of any unit of code being tested.
Pass in the value received from the code to be tested, then call one of the matchers returned by the function.
The returned matchers are bound to the received value internally, and should be called by using . instead of :.
test("returns hello world", function()
expect(someFunction()).toBe("hello world!")
end)
Modifiers
.never
If you need to invert the result of a matcher you can use the .never modifier. For example, the code below tests that the answer to life, the universe, and everything is never 42:
test("doesn't return 42", function()
expect(deepThought()).never.toBe(42)
end)
Note that as with calling matchers directly on expect(), you use . instead of : as Lest binds the received value to the function internally.
This is the same as the .not modifier in Jest. We had to use never as not is a reserved keyword in Lua.
Equality Matchers
.toBe(expected: any)
Performs a referential equality test between the received and expected values.
Two different tables with identical contents are not referentially equal, as the reference to the table stored in the variable is different.
If you want to perform a deep equality test between tables, use .toEqual() instead.
.toEqual(expected: any)
Performs a deep equality test between the received and expected values. This only affects table comparison.
If you want to check that two variables contain a reference to the same table
and not that they have the same contents, use .toBe().
.toBeDefined()
Tests whether the value is defined (not equal to nil).
.toBeUndefined()
Also under the alias toBeNil.
Tests whether the value is undefined (equal to nil).
.toBeTruthy()
Tests whether the value is truthy. In Lua, all values are truthy except nil and false.
.toBeFalsy()
Tests whether the value is falsy. In Lua, the only falsy values are nil and false.
.toBeInstanceOf(metatable: table)
Tests whether the received value is an instance of the given metatable.
Under the hood, this does getmetatable(received) == metatable.
Mock Function Matchers
.toHaveBeenCalled()
Also under the alias toBeCalled.
Tests that a mock function has been called. If you want to test that it was called with specific arguments, or a certain number of times, see the other mock function matchers.
.toHaveBeenCalledTimes(times: number)
Also under the alias toBeCalledTimes.
Tests that a mock function was called a specific number of times.
.toHaveBeenCalledWith(...: any)
Also under the alias toBeCalledWith.
Tests that a mock function was called with a specific set of arguments. Performs a deep equality test when comparing arguments.
If the mock was called multiple times, this will pass as long as it was called with the given argument(s) any of those times.
If you want to test that it was called with certain arguments on a specific call, see .toHaveBeenLastCalledWith() and .toHaveBeenNthCalledWith().
.toHaveBeenLastCalledWith(...: any)
Also under the alias lastCalledWith.
Tests that a mock function was called with specific arguments on its most recent call.
If you want to test that a mock function was called with specific arguments, but don't care when, see .toHaveBeenCalledWith().
If you want to test that a mock function was called with arguments on a specific call, see .toHaveBeenNthCalledWith().
.toHaveBeenNthCalledWith(nthCall: number, ...: any)
Also under the alias nthCalledWith.
Tests that a function was called with specific arguments on its Nth call.
If you want to test that a mock function was called with specific arguments, but don't care when, see .toHaveBeenCalledWith().
If you want to test that a mock function was called with arguments on its most recent call, see .toHaveBeenLastCalledWith().
.toHaveReturned()
Also under the alias toReturn.
Tests that a mock function returned. If you want to test that it returned specific values, or a certain number of times, see the other mock function matchers.
.toHaveReturnedTimes(times: number)
Also under the alias toReturnTimes.
Tests that a mock function returned a specific number of times.
.toHaveReturnedWith(...: any)
Also under the alias toReturnWith.
Tests that a mock function returned a specific set of values. Performs a deep equality test when comparing values.
If the mock returned multiple times, this will pass as long as it returned the given value(s) any of those times.
If you want to test that it returned certain values on a specific call, see .toHaveLastReturnedWith() and .toHaveNthReturnedWith().
.toHaveLastReturnedWith(...: any)
Also under the alias lastReturnedWith.
Tests that a mock function returned specific values on its most recent call.
If you want to test that a mock function returned specific values, but don't care when, see .toHaveReturnedWith().
If you want to test that a mock function returned values on a specific call, see .toHaveNthReturnedWith().
.toHaveNthReturnedWith(nthCall: number, ...: any)
Also under the alias nthReturnedWith.
Tests that a function returned specific values on its Nth call.
If you want to test that a mock function returned specific values, but don't care when, see .toHaveReturnedWith().
If you want to test that a mock function returned values on its most recent call, see .toHaveLastReturnedWith().
Number Matchers
.toBeCloseTo(expected: number, numDigits?: number)
Use toBeCloseTo to compare floating point numbers for approximate equality.
You can optionally specify numDigits to set the precision to compare at (default is 2).
Internally it performs the following comparison: math.abs(expected - received) < math.pow(10, -numDigits) / 2.
.toBeGreaterThan(expected: number)
Tests whether the received value is greater than the expected value.
.toBeGreaterThanOrEqual(expected: number)
Tests whether the received value is greater than or equal to the expected value.
.toBeLessThan(expected: number)
Tests whether the received value is less than the expected value.
.toBeLessThanOrEqual(expected: number)
Tests whether the received value is less than or equal to the expected value.
.toBeNaN()
Tests if the received value is NaN (not a number).
Internally this checks if the value is not equal to itself, and also if its type is number.
.toBeInfinity()
Tests if the received value is positive or negative infinity.
Internally this checks that the type of the received value is number, and that math.abs(received) equals math.huge.
String Matchers
Some table matchers also work with strings - e.g. .toHaveLength()
.toMatch(pattern: string)
Tests that the value matches the given Lua pattern.
Table Matchers
.toHaveLength(length: number)
Tests that the received value is of the given length.
This works with strings, tables and any other value that supports the Lua length operator (#).
.toContain(item: any)
Tests that the received value contains the given item.
If the received value is a string, this tests whether the substring item is contained within the string.
If the received value is a table, this enumerates all properties of the table and passes if any are referentially equal to item.
If you want to test if any of the table's properties are deeply equal to item, use .toContainEqual() instead
which performs the same equality test as .toEqual() on each property.
.toContainEqual(item: any)
Tests that the received value contains the given item.
Unlike .toContain(), this only works with tables.
This enumerates all properties of the table and passes if any are deeply equal to item.
It performs the same deep equality test on each property as .toEqual().
If you want to test if any of the table's properties are referentially equal to item, use .toContain() instead.
.toMatchObject(object: table)
Also under the alias toMatchTable.
Tests whether the received table's properties are a superset of the properties defined in object.
For example, if the received table is { a = 1, b = 2 } and object is { b = 2 },
then the test passes as { a = 1, b = 2 } is a superset of { b = 2 }.
However, if object was { b = 2, c = 3 } then the test would fail as
the received table does not contain the property c = 3.
If the length of the received table does not equal object's then this test will fail.
This is useful for matching an array of tables without allowing additional tables to be present.
Function Matchers
.toThrow(message?: string)
Also under the alias toThrowError.
Tests whether the received function throws when called.
By default, this will pass as long as the function throws an error.
You can additionally pass a value for message which will cause the test to pass only if the thrown error matches.
Internally this does string.match(tostring(error), message), so you can use Lua patterns to test more dynamic errors reliably.