Using Matchers
Jest Roblox uses "matchers" to let you test values in different ways. This document will introduce some commonly used matchers. For the full list, see the expect
API doc.
Common Matchers
The simplest way to test a value is with exact equality.
it('two plus two is four', function()
expect(2 + 2).toBe(4)
end)
In this code, expect(2 + 2)
returns an "expectation" object. You typically won't do much with these expectation objects except call matchers on them. In this code, .toBe(4)
is the matcher. When Jest Roblox runs, it tracks all the failing matchers so that it can print out nice error messages for you.
toBe
tests exact equality. If you want to check the value of an object, use toEqual
instead:
it('object assignment', function()
local data = { one = 1 }
data['two'] = 2
expect(data).toEqual({one = 1, two = 2})
end)
toEqual
recursively checks every field of a table.
You can also test for the opposite of a matcher:
it('adding positive numbers is not zero', function()
expect(1 + 2).never.toBe(0)
end)
Truthiness
In tests, you sometimes need to distinguish between nil
, and false
, but you sometimes do not want to treat these differently. Jest Roblox contains helpers that let you be explicit about what you want.
toBeNil
matches onlynil
toBeTruthy
matches anything that anif
statement treats astrue
(anything butfalse
andnil
)toBeFalsy
matches anything that anif
statement treats asfalse
(false
andnil
)
The following are identical to the ones above but are provided for the sake of completeness:
toBeUndefined
is identical totoBeNil
toBeNull
is an alias oftoBeNil
toBeDefined
is identical tonever.toBeNil
For example:
it('nil', function()
local n = nil
expect(n).toBeNil()
expect(n).never.toBeTruthy()
expect(n).toBeFalsy()
end)
it('false', function()
local z = false
expect(z).never.toBeNull()
expect(z).never.toBeTruthy()
expect(z).toBeFalsy()
end)
You should use the matcher that most precisely corresponds to what you want your code to be doing.
Numbers
Most ways of comparing numbers have matcher equivalents.
it('two plus two', function()
local value = 2 + 2
expect(value).toBeGreaterThan(3)
expect(value).toBeGreaterThanOrEqual(3.5)
expect(value).toBeLessThan(5)
expect(value).toBeLessThanOrEqual(4.5)
-- toBe and toEqual are equivalent for numbers
expect(value).toBe(4)
expect(value).toEqual(4)
end)
For floating point equality, use toBeCloseTo
instead of toEqual
, because you don't want a test to depend on a tiny rounding error.
it('adding floating point numbers', function()
local value = 0.1 + 0.2
expect(value).toBeCloseTo(0.3)
end)
Strings
You can check strings against Lua string patterns with toMatch
:
it('there is no I in team', function()
expect('team').never.toMatch('I')
end)
it('but there is a "stop" in Christoph', function()
expect('Christoph').toMatch('stop')
end)
You can also check strings against a regular expression using RegExp
from LuauRegExp:
it('Christoph ends in "oph"', function()
expect('Christoph').toMatch(RegExp('oph$'))
end)
You can check if a string contains an exact substring using toContain
:
it('there is a "stop" in Christoph', function()
expect('Christoph').toContain('stop')
end)
Tables
You can check if an array contains a particular item using toContain
or that a string contains a particular substring:
local shoppingList = {
'diapers',
'kleenex',
'trash bags',
'paper towels',
'beer',
}
it('the shopping list has beer on it', function()
expect(shoppingList).toContain('beer')
end)
toContain
performs a shallow equality so if you need to check that a specific table exists within the array, use .toContainEqual
.
local shoppingList = {
{'milk', 4},
{'bananas', 10},
{'beer', 1},
}
it('the shopping list contains {"beer", 1}', function()
expect(shoppingList).toContainEqual({'beer', 1})
end)
You can also check that a table is equal to another table by using toEqual
. This recursively compares all properties of the tables.
local inventory = {
lacroix = {
pamplemousse = 3,
passionfruit = 10,
},
beer = {
budweiser = 3,
}
}
it('the inventory matches', function()
expect(inventory.lacroix).toEqual({
lacroix = {
pamplemousse = 3,
passionfruit = 10,
},
beer = {
budweiser = 3,
}
})
end)
Lastly, you can check that a table has a property and value by using .toHaveProperty
.
it('the inventory has 3 budweisers', function()
expect(inventory).toHaveProperty('beer.budweiser', 3)
end)
it('the inventory does not have guinness', function()
expect(inventory).never.toHaveProperty('beer.guinness')
end)
Exceptions
If you want to test whether a particular function throws an error when it's called, use toThrow
.
function thisFunctionErrors()
error('oh no')
end
it('the function errors', function()
expect(thisFunctionErrors).toThrow()
-- You can also use the exact error message or a RegExp using the LuauRegExp library
expect(thisFunctionErrors).toThrow('oh no')
expect(thisFunctionErrors).toThrow(RegExp('no'))
end)
And More
This is just a taste. For a complete list of matchers, check out the reference docs.