Jest Lua

https://jsdotlua.github.io/jest-lua
Admin
Jest Lua is a testing framework for Roblox, providing an API similar to JavaScript Jest. It enables...
Tokens:92,158
Snippets:772
Trust Score:8.3
Update:1 week ago
Show doc for...
Tokens:
Raw
### setupFilesAfterEnv example with setupJest.lua and jest.config.lua

Source: https://jsdotlua.github.io/jest-lua/configuration

Shows how to use setupFilesAfterEnv to run code after the test framework is installed. The setupJest.lua file extends expect and sets up afterEach hooks, and jest.config.lua references it.

```lua
local JestGlobals = require("@DevPackages/JestGlobals")  
local jest = JestGlobals.jest  
local expect = JestGlobals.expect  
local afterEach = JestGlobals.afterEach  
  
expect.extend({  
	newMatcher = function(self, received, expected)  
		-- ...  
	end)  
})  
  
afterEach(function()  
	jest.useRealTimers()  
end)  
```

```lua
return {  
	setupFilesAfterEnv = { Workspace.setupJest },  
}  
```

--------------------------------

### Repeating setup with beforeEach and afterEach

Source: https://jsdotlua.github.io/jest-lua/setup-teardown

Use beforeEach and afterEach to run setup and teardown before and after each test. The example shows synchronous hooks that call initializeCityDatabase() and clearCityDatabase(), followed by two tests that verify the city database.

```lua
beforeEach(function()  
	initializeCityDatabase()  
end)  
  
afterEach(function()  
	clearCityDatabase()  
end)  
  
test('city database has Vienna', function()  
	expect(isCity('Vienna')).toBeTruthy()  
end)  
  
test('city database has San Juan', function()  
	expect(isCity('San Juan')).toBeTruthy()  
end)  

```

--------------------------------

### One-time setup with beforeAll and afterAll

Source: https://jsdotlua.github.io/jest-lua/setup-teardown

Use beforeAll and afterAll for one-time setup and teardown at the beginning and end of a file. This example shows both hooks returning promises from initializeCityDatabase() and clearCityDatabase(), followed by two tests that verify the city database.

```lua
beforeAll(function()  
	return initializeCityDatabase()  
end)  
  
afterAll(function()  
	return clearCityDatabase()  
end)  
  
test('city database has Vienna', function()  
	expect(isCity('Vienna')).toBeTruthy()  
end)  
  
test('city database has San Juan', function()  
	expect(isCity('San Juan')).toBeTruthy()  
end)  

```

--------------------------------

### Setup and teardown hook order example

Source: https://jsdotlua.github.io/jest-lua/setup-teardown

Shows that beforeEach and afterEach hooks run in declaration order, with outer afterEach hooks called after inner ones. Output demonstrates the sequence for two tests.

```lua
beforeEach(function() print('connection setup') end)  
beforeEach(function() print('database setup') end)  
  
afterEach(function() print('database teardown') end)  
afterEach(function() print('connection teardown') end)  
  
test('test 1', function()  
	print('test 1')  
end)  
  
describe('extra', function()  
	beforeEach(function() print('extra database setup') end)  
  
	afterEach(function() print('extra database teardown') end)  
  
	test('test 2', function()  
		print('test 2')  
	end)  
end)  
  
-- connection setup  
-- database setup  
-- test 1  
-- database teardown  
-- connection teardown  
  
-- connection setup  
-- database setup  
-- extra database setup  
-- test 2  
-- extra database teardown  
-- database teardown  
-- connection teardown  
```

--------------------------------

### toHaveBeenNthCalledWith example

Source: https://jsdotlua.github.io/jest-lua/expect

Tests the arguments of the nth call to a mock function. The example checks that the first call is 'lemon' and the second is 'octopus'. The nth argument must be a positive integer starting from 1.

```lua
it('drinkEach drinks each drink', function()  
	local drink = jest.fn()  
	drinkEach(drink, {'lemon', 'octopus'})  
	expect(drink).toHaveBeenNthCalledWith(1, 'lemon')  
	expect(drink).toHaveBeenNthCalledWith(2, 'octopus')  
end)  
```

--------------------------------

### toBeTruthy example with application code

Source: https://jsdotlua.github.io/jest-lua/expect

Shows application code that uses a truthy check in an if statement. The example is used to illustrate when to use toBeTruthy.

```lua
drinkSomeLaCroix()  
if thirstInfo() then  
	drinkMoreLaCroix()  
end  

```

--------------------------------

### Profiler.start(sectionName)

Source: https://jsdotlua.github.io/jest-lua/jest-benchmark

Starts a section in the profiler.

```APIDOC
## Profiler.start(sectionName)

### Description
Starts a named section in the profiler.

### Parameters
- **sectionName** (string) - Required - The name of the section.

### Example
```lua
Profiler.start("section")
```
```

--------------------------------

### Profiler.start and Profiler.stop

Source: https://jsdotlua.github.io/jest-lua/jest-benchmark

Starts a profiling section and stops it. Each start must be concluded with a stop call.

```lua
Profiler.start("section1")  
  
Profiler.stop()  

```

--------------------------------

### toBeFalsy example with application code

Source: https://jsdotlua.github.io/jest-lua/expect

Shows application code that uses a falsy check in an if statement. The example is used to illustrate when to use toBeFalsy.

```lua
drinkSomeLaCroix()  
if not getErrors() then  
	drinkMoreLaCroix()  
end  

```

--------------------------------

### toHaveBeenCalledWith example

Source: https://jsdotlua.github.io/jest-lua/expect

Ensures a mock function was called with specific arguments. The example registers a beverage and checks that applyToAll called the mock with that beverage.

```lua
it('registration applies correctly to orange La Croix', function()  
	local beverage = LaCroix.new('orange')  
	register(beverage)  
	local f = jest.fn()  
	applyToAll(f)  
	expect(f).toHaveBeenCalledWith(beverage)  
end)  
```

--------------------------------

### Basic configuration: export a table

Source: https://jsdotlua.github.io/jest-lua/configuration

The configuration file should export a table with options. This example sets verbose to true.

```lua
return {  
	verbose = true,  
}  
```

--------------------------------

### Mocked module example (mockedModule.lua)

Source: https://jsdotlua.github.io/jest-lua/jest-object

A simple module that returns an empty table, used as the target for mocking in the test example.

```lua
return {}  
```

--------------------------------

### describe.skip example: skipping a describe block

Source: https://jsdotlua.github.io/jest-lua/api

Use describe.skip (alias xdescribe) to skip all tests in a describe block. The block still runs, so any setup should be placed in beforeAll or beforeEach if it also needs to be skipped.

```lua
describe('my beverage', function()  
	test('is delicious', function()  
		expect(myBeverage.delicious).toBeTruthy()  
	end)  
  
	test('is not sour', function()  
		expect(myBeverage.sour).toBeFalsy()  
	end)  
end)  
  
describe.skip('my other beverage', function()  
	-- ... will be skipped  
end)  

```

--------------------------------

### toBeLessThan example

Source: https://jsdotlua.github.io/jest-lua/expect

Test that ouncesPerCan() returns a value less than 20.

```lua
it('ounces per can is less than 20', function()  
	expect(ouncesPerCan()).toBeLessThan(20)  
end)  

```

--------------------------------

### mockFn.mock.instances array example

Source: https://jsdotlua.github.io/jest-lua/mock-function-api

Shows how to access instances created from a mock function using mock.instances.

```lua
local mockFn = jest.fn()  
  
local a = mockFn.new()  
local b = mockFn.new()  
  
mockFn.mock.instances[1] == a  
mockFn.mock.instances[2] == b  
```

--------------------------------

### toHaveBeenLastCalledWith example

Source: https://jsdotlua.github.io/jest-lua/expect

Tests the arguments of the most recent call to a mock function. The example checks that the last flavor operated on is 'mango'.

```lua
it('applying to all flavors does mango last', function()  
	local drink = jest.fn()  
	applyToAllFlavors(drink)  
	expect(drink).toHaveBeenLastCalledWith('mango')  
end)  
```

--------------------------------

### Reporter.start(sectionName)

Source: https://jsdotlua.github.io/jest-lua/jest-benchmark

Starts a section in the reporter for timing or tracking.

```APIDOC
## Reporter.start(sectionName)

### Description
Starts a named section in the reporter.

### Parameters
- **sectionName** (string) - Required - The name of the section.

### Example
```lua
reporter.start("render")
```
```

--------------------------------

### toBeNil example

Source: https://jsdotlua.github.io/jest-lua/expect

Test that bloop() returns nil using toBeNil.

```lua
local function bloop()  
	return nil  
end  
  
it('bloop returns nil', function()  
	expect(bloop()).toBeNil()  
end)  

```

--------------------------------

### Async configuration: export a Promise

Source: https://jsdotlua.github.io/jest-lua/configuration

The configuration file can also export an async function that returns a table. This example uses Promise.resolve():andThen() to return the configuration.

```lua
return Promise.resolve():andThen(function()  
	return {  
		verbose = true,  
	}  
end)  
```

--------------------------------

### expect.stringMatching in arrayContaining example

Source: https://jsdotlua.github.io/jest-lua/expect

Shows how to nest expect.stringMatching inside expect.arrayContaining. The example demonstrates matching an array that contains elements matching the given patterns, and also shows a negative case using .never.toEqual.

```lua
describe('stringMatching in arrayContaining', function()  
	local expected = {  
		expect.stringMatching(RegExp('^Alic')),  
		expect.stringMatching(RegExp('^[BR]ob'),  
	}  
	it('matches even if received contains additional elements', function()  
		expect({'Alicia', 'Roberto', 'Evelina'}).toEqual(  
			expect.arrayContaining(expected)  
		)  
	end)  
	it('does not match if received does not contain expected elements', function()  
		expect({'Roberto', 'Evelina'}).never.toEqual(  
			expect.arrayContaining(expected)  
		)  
	end)  
end)  

```

--------------------------------

### toContain example

Source: https://jsdotlua.github.io/jest-lua/expect

Test that getAllFlavors() contains 'lime' using toContain.

```lua
it('the flavor list contains lime', function()  
	expect(getAllFlavors()).toContain('lime')  
end)  

```

--------------------------------

### Profiler.start(sectionName)

Source: https://jsdotlua.github.io/jest-lua/jest-benchmark

Starts a profiling section. Calls reporter.start for each reporter in the reporters list. Each section must be concluded with Profiler.stop().

```APIDOC
## Profiler.start(sectionName)

### Description
Starts a profiling section. Calls reporter.start for each reporter in the reporters list. Each section must be concluded with Profiler.stop().

### Parameters
- **sectionName** (string) - Required - Name of the profiling section.

### Example
```lua
Profiler.start("section1")  
  
Profiler.stop()  
```
```

--------------------------------

### toEqual and toBe example

Source: https://jsdotlua.github.io/jest-lua/expect

Use .toEqual to compare recursively all properties of tables (deep equality). It calls Luau Polyfill's Object.is for primitive values. This example shows .toEqual and .toBe behaving differently.

```lua
local can1 = {  
	flavor = 'grapefruit',  
	ounces = 12,  
}  
local can2 = {  
	flavor = 'grapefruit',  
	ounces = 12,  
}  
  
describe('the La Croix cans on my desk', function()  
	it('have all the same properties', function()  
		expect(can1).toEqual(can2)  
	end)  
	it('are not the exact same can', function()  
		expect(can1).never.toBe(can2)  
	end)  
end)  

```

--------------------------------

### mockFn.mock.results array example

Source: https://jsdotlua.github.io/jest-lua/mock-function-api

Shows the structure of the mock.results array for a mock function that returned 'result1' and then 'result2'.

```lua
{  
	{  
		type = 'return',  
		value = 'result1',  
	},  
	{  
		type = 'return',  
		value = 'result2',  
	},  
}  
```

--------------------------------

### toMatch with regular expression example

Source: https://jsdotlua.github.io/jest-lua/expect

This matcher also accepts a regular expression. Use .toMatch with RegExp to check for alternative substrings.

```lua
describe('an essay on the best flavor', function()  
	it('mentions grapefruit or orange', function()  
		expect(essayOnTheBestFlavor()).toMatch(RegExp('grapefruit|orange'))  
	end)  
end)  

```

--------------------------------

### describe.only to run a single block

Source: https://jsdotlua.github.io/jest-lua/api

Example showing how describe.only runs only the specified describe block, skipping other describe blocks. Also available as fdescribe.

```lua
describe.only('my beverage', function()  
	test('is delicious', function()  
		expect(myBeverage.delicious).toBeTruthy()  
	end)  
  
	test('is not sour', function()  
		expect(myBeverage.sour).toBeFalsy()  
	end)  
end)  
  
describe('my other beverage', function()  
	-- ... will be skipped  
end)  

```

--------------------------------

### toBeGreaterThan example

Source: https://jsdotlua.github.io/jest-lua/expect

Test that ouncesPerCan() returns a value greater than 10.

```lua
it('ounces per can is more than 10', function()  
	expect(ouncesPerCan()).toBeGreaterThan(10)  
end)  

```

--------------------------------

### toBeCloseTo failing example

Source: https://jsdotlua.github.io/jest-lua/expect

Shows a test that fails because 0.2 + 0.1 is not exactly 0.3 due to floating-point rounding errors.

```lua
it('adding works sanely with decimals', function()  
	expect(0.2 + 0.1).toBe(0.3) -- Fails!  
end)  

```

--------------------------------

### test.only(name, fn, timeout) example

Source: https://jsdotlua.github.io/jest-lua/api

Use test.only to run only a specific test in a file. The example shows a test.only and a regular test; only the 'it is raining' test will run. The default timeout is 5 seconds.

```lua
test.only('it is raining', function()  
	expect(inchesOfRain()).toBeGreaterThan(0)  
end)  
  
test('it is not snowing', function()  
  expect(inchesOfSnow()).toBe(0)  
end)  

```

--------------------------------

### toBeLessThanOrEqual example

Source: https://jsdotlua.github.io/jest-lua/expect

Test that ouncesPerCan() returns a value at most 12.

```lua
it('ounces per can is at most 12', function()  
	expect(ouncesPerCan()).toBeLessThanOrEqual(12)  
end)  

```

--------------------------------

### Reporter

Source: https://jsdotlua.github.io/jest-lua/jest-benchmark

The Reporter interface provides methods to initialize, start, stop, report, and finish a benchmark reporter.

```APIDOC
## Reporter

### Description
The Reporter interface provides methods to initialize, start, stop, report, and finish a benchmark reporter.

### Methods
- `initializeReporter(metricName, fn)` - Initializes a reporter with a metric name and a function.
- `Reporter.start(sectionName)` - Starts the reporter for a given section.
- `Reporter.stop()` - Stops the reporter.
- `Reporter.report(number)` - Reports a numeric value.
- `Reporter.finish()` - Finalizes the reporter.
```

--------------------------------

### Asynchronous beforeEach with returned promise

Source: https://jsdotlua.github.io/jest-lua/setup-teardown

beforeEach and afterEach can handle asynchronous code by returning a promise. This example shows beforeEach returning the promise from initializeCityDatabase().

```lua
beforeEach(function()  
	return initializeCityDatabase()  
end)  

```

--------------------------------

### Example of incorrect snapshot output

Source: https://jsdotlua.github.io/jest-lua/snapshot-testing

Shows a snapshot where the expected values are swapped, demonstrating how descriptive names make it clear when a snapshot is wrong.

```lua
exports[ [=[should be nil 1]=] ] = [=[  
"Alan Turing"]=]  
  
exports[ [=[should be Alan Turing 1]=] ] = [=[  
nil]=]  

```

--------------------------------

### toBeNan example

Source: https://jsdotlua.github.io/jest-lua/expect

Test that 0/0 is NaN and 1 is not NaN using toBeNan.

```lua
it('passes when value is nan', function()  
	expect(0/0).toBeNan()  
	expect(1).never.toBeNan()  
end)  

```

--------------------------------

### toBeTruthy test example

Source: https://jsdotlua.github.io/jest-lua/expect

Test that thirstInfo() is truthy after drinking La Croix.

```lua
it('drinking La Croix leads to having thirst info', function()  
	drinkSomeLaCroix()  
	expect(thirstInfo()).toBeTruthy()  
end)  

```

--------------------------------

### projects configuration

Source: https://jsdotlua.github.io/jest-lua/configuration

Runs tests in multiple projects simultaneously. This example runs Jest Lua in ProjectA and ProjectB.

```lua
return {  
	projects = { Workspace.ProjectB, Workspace.ProjectB },  
}  
```

--------------------------------

### Example of descriptive snapshot names

Source: https://jsdotlua.github.io/jest-lua/snapshot-testing

Shows snapshot names that describe the expected content, making it easier to review and identify incorrect snapshots.

```lua
exports[ [=[should be nil 1]=] ] = [=[  
nil]=]  
  
exports[ [=[should be Alan Turing 1]=] ] = [=[  
"Alan Turing"]=]  

```

--------------------------------

### Set up project structure with default.project.json

Source: https://jsdotlua.github.io/jest-lua

Creates a default.project.json to define the project tree, including the Packages directory and the src folder as the Project.

```json
{  
	"name": "YourProject",  
	"tree": {  
		"$className": "Folder",  
		"Packages": {  
			"$path": "Packages",  
			"Project": {  
				"$path": "src"  
			}  
		}  
	}  
}  

```

--------------------------------

### test.todo(name) example

Source: https://jsdotlua.github.io/jest-lua/api

Plans a test that is not yet implemented. The test will be highlighted in the summary output. Supplying a callback function causes test.todo to throw an error.

```lua
local function add(a, b)  
	return a + b  
end  
  
test.todo('add should be associative')  

```

--------------------------------

### toHaveNthReturnedWith example

Source: https://jsdotlua.github.io/jest-lua/expect

Tests the value returned by a mock function on the nth call. The nth argument must be a positive integer starting from 1. If the nth call threw an error, the matcher fails.

```lua
it('drink returns expected nth calls', () => {  
	local beverage1 = {name = 'La Croix (Lemon)'}  
	local beverage2 = {name = 'La Croix (Orange)'}  
	local drink = jest.fn(function(beverage) return beverage.name end)  
  
	drink(beverage1)  
	drink(beverage2)  
  
	expect(drink).toHaveNthReturnedWith(1, 'La Croix (Lemon)')  
	expect(drink).toHaveNthReturnedWith(2, 'La Croix (Orange)')  
end  

```

--------------------------------

### toBeCloseTo passing example

Source: https://jsdotlua.github.io/jest-lua/expect

Shows a test that passes with a precision of 5 digits, using toBeCloseTo to compare floating-point numbers approximately.

```lua
it('adding works sanely with decimals', function()  
	expect(0.2 + 0.1).toBeCloseTo(0.3, 5)  
end)  

```

--------------------------------

### mockFn.mock.calls array example

Source: https://jsdotlua.github.io/jest-lua/mock-function-api

Shows the structure of the mock.calls array for a mock function called twice with arguments ('arg1', 'arg2') and ('arg3', 'arg4').

```lua
{  
	{'arg1', 'arg2'},  
	{'arg3', 'arg4'},  
}  
```

--------------------------------

### Example benchmark using benchmark function

Source: https://jsdotlua.github.io/jest-lua/jest-benchmark

Shows how to use the benchmark function to profile the first render of a HomePage component. The function receives a Profiler and reporters, and uses expect to assert the GameCarousel element is defined.

```lua
describe("Home Page Benchmarks", function()  
	benchmark("First Render Performance", function(Profiler, reporters)  
		render(React.createElement(HomePage))  

		local GameCarousel = screen.getByText("Continue"):expect()  

		expect(GameCarousel).toBeDefined()  
	end)  
end)  
```

--------------------------------

### projects

Source: https://jsdotlua.github.io/jest-lua/deviations

Configuration option that takes an array of Instances. Each entry should be a path to a datamodel Instance with a configuration file.

```APIDOC
## projects

### Description
Configuration option that takes an array of Instances. Each entry should be a path to a datamodel Instance with a configuration file.

### Parameters
- **projects** (array of Instances) - Required - Array of paths to datamodel Instances with configuration files.
```

--------------------------------

### afterAll cleanup example

Source: https://jsdotlua.github.io/jest-lua/api

Runs a function after all tests in the file complete. If the function returns a promise or is a generator, Jest Lua waits for it to resolve. Optional timeout in milliseconds, default 5 seconds. Useful for cleaning up global setup state.

```lua
local globalDatabase = makeGlobalDatabase()

local function cleanUpDatabase(db)
	db:cleanUp()
end

afterAll(function()
	cleanUpDatabase(globalDatabase)
end)

test('can find things', function()
	return globalDatabase:find('thing', {}, function(results)
		expect(#results).toBeGreaterThan(0)
	end)
end)

test('can insert a thing', function()
	return globalDatabase:insert('thing', makeThing(), function(response)
		expect(response.success).toBeTruthy()
	end)
end)
```

--------------------------------

### Use original implementation of a mocked global

Source: https://jsdotlua.github.io/jest-lua/global-mocks

Access the original (non-mocked) implementation of a global function by indexing into jest.globalEnv with the function name. The example shows mocking math.random to always return 5, then calling the original to get a random number.

```lua
local mockRandom = jest.spyOn(jest.globalEnv.math, "random")  
mockRandom.mockImplementation(function(_min: number?, _max: number?)  
	return 5  
end)  
  
-- will always be 5  
local mocked = math.random()  
-- will be some random number between 0 and 1  
local unmocked = jest.globalEnv.math.random()  
```

--------------------------------

### mockFn.mockImplementation(fn) example

Source: https://jsdotlua.github.io/jest-lua/mock-function-api

Sets the implementation of the mock function. The mock still records calls and instances. jest.fn(implementation) is shorthand for jest.fn().mockImplementation(implementation). Prefer mockReturnValue over mockImplementation when possible.

```lua
local mockFn = jest.fn().mockImplementation(function(scalar) return 42 + scalar end)  
-- or: jest.fn(function(scalar) return 42 + scalar end)  
  
local a = mockFn(0)  
local b = mockFn(1)  
  
a == 42 == true  
b == 43 == true  
  
mockFn.mock.calls[1][1] == 0 -- true  
mockFn.mock.calls[2][1] == 1 -- true  

```

--------------------------------

### jest.spyOn example: video module

Source: https://jsdotlua.github.io/jest-lua/jest-object

Example module with a play method that returns true. This is used in the test example to spy on the play method.

```lua
local video = {  
	play = function()  
		return true  
	end  
}  
  
return video  

```

--------------------------------

### Describe block execution order example

Source: https://jsdotlua.github.io/jest-lua/setup-teardown

Shows that all describe handlers run before tests, printing describe outer-a, inner 1, outer-b, inner 2, outer-c, then tests 1, 2, 3.

```lua
describe('describe outer', function()  
	print('describe outer-a')  
  
	describe('describe inner 1', function()  
		print('describe inner 1')  
  
		test('test 1', function()  
			print('test 1')  
		end)  
	end)  
  
	print('describe outer-b')  
  
	test('test 2', function()  
		print('test 2')  
	end)  
  
	describe('describe inner 2', function()  
		print('describe inner 2')  
  
		test('test 3', function()  
			print('test 3')  
		end)  
	end)  
  
	print('describe outer-c')  
end)  
  
-- describe outer-a  
-- describe inner 1  
-- describe outer-b  
-- describe inner 2  
-- describe outer-c  
-- test 1  
-- test 2  
-- test 3  
```

--------------------------------

### Example test file: peanutButter.spec.lua

Source: https://jsdotlua.github.io/jest-lua/upgrading-to-jest3

A simple test that checks if data is peanut butter. Used to illustrate how to run only this test file using testMatch or testNamePattern.

```lua
test('the data is peanut butter', function()  
    -- ...  
end)  
```

--------------------------------

### Using expect.any matchers in snapshot test

Source: https://jsdotlua.github.io/jest-lua/snapshot-testing

This example shows how to use expect.any matchers for generated fields so the snapshot passes. The matchers are checked before writing and saved as Any<...> in the snapshot.

```lua
it("will check the matchers and pass", function()  
	local user = {  
		createdAt = DateTime.now(),  
		id = math.floor(math.random() * 20),  
		name = "LeBron James"  
	}  
  
	expect(user).toMatchSnapshot({  
		createdAt = expect.any("DateTime"),  
		id = expect.any("number"),  
		name = expect.any("string")  
	})  
end)  
  
-- Snapshot  
exports[ [=[will check the matchers and pass 1]=] ] = [=[  
  
Table {  
  "createdAt": Any<DateTime>,  
  "id": Any<number>,  
  "name": Any<string>,  
}  
]=]  

```

--------------------------------

### toHaveReturned example

Source: https://jsdotlua.github.io/jest-lua/expect

Tests that a mock function successfully returned at least once (did not throw). The example uses a mock that returns true.

```lua
it('drinks returns', function()  
	local drink = jest.fn(function() return true end)  
  
	drink()  
  
	expect(drink).toHaveReturned()  
end  
```

--------------------------------

### describe.each(...args) with headings

Source: https://jsdotlua.github.io/jest-lua/api

Example of describe.each using the ...args API with a heading string and separate argument arrays. The test function receives a reference object with properties from the heading.

```lua
describe.each('a | b | expected',  
	{1, 1, 2},  
	{1, 2, 3},  
	{2, 1, 3}  
)('.add($a, $b)', function(ref)  
	local a, b, expected = ref.a, ref.b, ref.expected  
  
	test('returns $expected', function()  
		expect(a + b).toBe(expected)  
	end)  
  
	test('returned value not be greater than $expected', function()  
		expect(a + b).never.toBeGreaterThan(expected)  
	end)  
  
	test('returned value not be less than $expected', function()  
		expect(a + b).never.toBeLessThan(expected)  
	end)  
end)  

```

--------------------------------

### Configure snapshotFormat with printInstanceDefaults

Source: https://jsdotlua.github.io/jest-lua/configuration

Configuration for snapshotFormat to disable printing unmodified Instance properties. The example sets printInstanceDefaults to false, so the snapshot only includes changed properties.

```lua
return {  
	testMatch = { "**/*.spec" },  
	snapshotFormat = { printInstanceDefaults = false }  
}  

```

--------------------------------

### describe.only.each(table) to run specific data-driven suites

Source: https://jsdotlua.github.io/jest-lua/api

Example of describe.only.each using the table API. Only the specified data-driven test suite runs; other tests are skipped.

```lua
describe.only.each({  
	{1, 1, 2},  
	{1, 2, 3},  
	{2, 1, 3},  
})('.add($a, $b)', function(a, b, expected)  
	test('will be ran', function()  
		expect(a + b).toBe(expected)  
	end)  
end)  
  
test('will not be ran', function()  
	expect(1 / 0).toBe(math.huge)  
end)  

```

--------------------------------

### mockFn.mockReturnValue(value) example

Source: https://jsdotlua.github.io/jest-lua/mock-function-api

Sets the return value for the mock function. The example shows changing the return value with subsequent calls.

```lua
local mock = jest.fn()  
mock.mockReturnValue(42)  
mock() -- 42  
mock.mockReturnValue(43)  
mock() -- 43  

```

--------------------------------

### Using Reporter.start, report, stop, and finish

Source: https://jsdotlua.github.io/jest-lua/jest-benchmark

Shows how to create nested reporting segments, report values, and finish the reporter. The finish method returns section names and values in order of completion.

```lua
averageReporter.start("total")  

averageReporter.start("section1")  
averageReporter.report(1)  
averageReporter.report(3)  
averageReporter.stop() -- closes section1  

averageReporter.start("section2")  
averageReporter.report(5)  
averageReporter.report(7)  
averageReporter.stop() -- closes section2  

averageReporter.stop() -- closes total  

local sectionNames, sectionValues = averageReporter.finish()  
-- sectionNames: {"section1", "section2", "total"}  
-- sectionValues: {2, 6, 4}  

```

--------------------------------

### displayName as a string

Source: https://jsdotlua.github.io/jest-lua/configuration

Sets a label for the test project. Defaults to white when a string is used.

```lua
return {  
	displayName = 'CLIENT',  
}  
```

--------------------------------

### toHaveReturnedWith example

Source: https://jsdotlua.github.io/jest-lua/expect

Tests that a mock function returned a specific value. The example checks that the mock returns the beverage name 'La Croix'.

```lua
it('drink returns La Croix', function()  
	local beverage = {name = 'La Croix'}  
	local drink = jest.fn(function(beverage) return beverage.name end)  
  
	drink(beverage)  
  
	expect(drink).toHaveReturnedWith('La Croix')  
end)  
```

--------------------------------

### initializeProfiler with reporters and outputFn

Source: https://jsdotlua.github.io/jest-lua/jest-benchmark

Creates a Profiler object with a list of reporters and an output function. An optional prefix can be appended to section names.

```lua
local reporters = {  
	initializeReporter("average", average),  
	initializeReporter("sectionTime", sectionTime),  
}  
  
local outputFn = function(metricName: string, value: any)  
	print(`{metricName}, {value}`)  
end  
  
local profiler = initializeProfiler(reporters, outputFn)  

```

--------------------------------

### toHaveReturnedTimes example

Source: https://jsdotlua.github.io/jest-lua/expect

Tests that a mock function returned successfully an exact number of times. Calls that throw are not counted. The example expects two successful returns.

```lua
it('drink returns twice', function()  
	local drink = jest.fn(function() return true end)  
  
	drink()  
	drink()  
  
	expect(drink).toHaveReturnedTimes(2)  
end  
```

--------------------------------

### mockFn.mockName(value) example and error output

Source: https://jsdotlua.github.io/jest-lua/mock-function-api

Sets a name for the mock function used in test output. The example shows the resulting error message when the mock is not called.

```lua
local mockFn = jest.fn().mockName('mockedFunction')  
-- mockFn()  
expect(mockFn).toHaveBeenCalled()  

```

```text
expect(mockedFunction).toHaveBeenCalled()  
  
Expected number of calls: >= 1  
Received number of calls:    0  

```

--------------------------------

### Order of execution for all hooks

Source: https://jsdotlua.github.io/jest-lua/setup-teardown

Illustrates the execution order of beforeAll, afterAll, beforeEach, and afterEach hooks at the top level and inside a describe block. The output comments show the exact sequence.

```lua
beforeAll(function() print('1 - beforeAll') end)  
afterAll(function() print('1 - afterAll') end)  
beforeEach(function() print('1 - beforeEach') end)  
afterEach(function() print('1 - afterEach') end)  
  
test('', function()  
	print('1 - test')  
end)  
  
describe('Scoped / Nested block', function()  
	beforeAll(function() print('2 - beforeAll') end)  
	afterAll(function() print('2 - afterAll') end)  
	beforeEach(function() print('2 - beforeEach') end)  
	afterEach(function() print('2 - afterEach') end)  
  
	test('', function()  
		print('2 - test')  
	end)  
end)  
  
-- 1 - beforeAll  
-- 1 - beforeEach  
-- 1 - test  
-- 1 - afterEach  
-- 2 - beforeAll  
-- 1 - beforeEach  
-- 2 - beforeEach  
-- 2 - test  
-- 2 - afterEach  
-- 1 - afterEach  
-- 2 - afterAll  
-- 1 - afterAll  

```

--------------------------------

### toMatch with string pattern example

Source: https://jsdotlua.github.io/jest-lua/expect

Use .toMatch to check that a string matches a Lua string pattern. This example checks that the returned string contains the substring 'grapefruit'.

```lua
describe('an essay on the best flavor', function()  
	it('mentions grapefruit', function()  
		expect(essayOnTheBestFlavor()).toMatch('grapefruit')  
	end)  
end)  

```

--------------------------------

### test with promise example

Source: https://jsdotlua.github.io/jest-lua/api

If a promise is returned from test, Jest Lua waits for the promise to resolve before completing the test. This example tests a promise that resolves to a list containing 'lemon'.

```lua
test('has lemon in it', function()  
	return fetchBeverageList():then(function(list)  
		expect(list).toContain('lemon')  
	end)  
end)  

```

--------------------------------

### toHaveLastReturnedWith example

Source: https://jsdotlua.github.io/jest-lua/expect

Tests the value of the last successful return from a mock function. If the last call threw, the matcher fails. The example expects the last return to be 'La Croix (Orange)'.

```lua
it('drink returns La Croix (Orange) last', function()  
	local beverage1 = {name = 'La Croix (Lemon)'}  
	local beverage2 = {name = 'La Croix (Orange)'}  
	local drink = jest.fn(function(beverage) return beverage.name end)  
  
	drink(beverage1)  
	drink(beverage2)  
  
	expect(drink).toHaveLastReturnedWith('La Croix (Orange)')  
end)  
```

--------------------------------

### describe.only.each(...args) with headings

Source: https://jsdotlua.github.io/jest-lua/api

Example of describe.only.each using the ...args API with a heading table. Only the specified data-driven test suite runs; other tests are skipped.

```lua
describe.only.each({'a | b | expected'},  
	{1, 1, 2},  
	{1, 2, 3},  
	{2, 1, 3}  
)('returns $expected when $a is added $b', function(ref)  
	local a, b, expected = ref.a, ref.b, ref.expected  
  
	test('will be ran', function()  
		expect(a + b).toBe(expected)  
	end)  
end)  
  
test('will not be ran', function()  
	expect(1 / 0).toBe(math.huge)  
end)  

```

--------------------------------

### Use mockImplementationOnce for different results per call

Source: https://jsdotlua.github.io/jest-lua/mock-functions

Shows how to use mockImplementationOnce to define different implementations for successive calls. The first call returns true, the second returns false.

```lua
local myMockFn = jest.fn()  
	.mockImplementationOnce(function(cb) return cb(nil, true) end)  
	.mockImplementationOnce(function(cb) return cb(nil, false) end)  
  
myMockFn(function(err, val) print(val) end) -- > true  
myMockFn(function(err, val) print(val) end) -- > false  

```

--------------------------------

### beforeAll with asynchronous database setup

Source: https://jsdotlua.github.io/jest-lua/api

Runs once before all tests in a file. Jest Lua waits for the returned promise to resolve. Default timeout is 5 seconds. Useful for setting up global state.

```lua
local globalDatabase = makeGlobalDatabase()  

beforeAll(function()  
	-- Clears the database and adds some testing data.  
	-- Jest Lua will wait for this promise to resolve before running tests.  
	return globalDatabase:clear()  
		:then(function()  
			return globalDatabase:insert({testData = 'foo'})  
		end)  
end)  

-- Since we only set up the database once in this example, it's important  
-- that our tests don't modify it.  
test('can find things', function()  
	return globalDatabase:find('thing', {}, function(results)  
		expect(#results).toBeGreaterThan(0)  
	end)  
end)  

```

--------------------------------

### test.failing(name, fn, timeout) example

Source: https://jsdotlua.github.io/jest-lua/api

Use test.failing when you expect a test to fail. The example shows two tests: one that throws (passes) and one that does not (fails). The default timeout is 5 seconds.

```lua
test.failing('it is not equal', function()  
  expect(5).toBe(6) -- this test will pass  
end)  
  
test.failing('it is equal', function()  
  expect(10).toBe(10) -- this test will fail  
end)  

```

--------------------------------

### describe.each(...args)(name, fn, timeout)

Source: https://jsdotlua.github.io/jest-lua/api

Runs the same test suite with data provided via a template string and multiple arrays. The test function receives a table with the data fields.

```APIDOC
## describe.each(...args)(name, fn, timeout)

### Description
Runs the same test suite with data provided via a template string and multiple arrays. The test function receives a table with the data fields.

### Parameters
- **...args** - Required - First argument is a string with headings separated by `|`, or a table with a single element containing that. One or more arguments of arrays with the arguments passed into `fn`.
- **name** (string) - Required - The title of the test suite.
- **fn** (function) - Required - The suite of tests to run; receives the test data object.
- **timeout** (number, optional) - Optional - Time in milliseconds to wait for each row before aborting. Default is 5 seconds.

### Example
```lua
describe.each('a | b | expected',  
	{1, 1, 2},  
	{1, 2, 3},  
	{2, 1, 3}  
)('.add($a, $b)', function(ref)  
	local a, b, expected = ref.a, ref.b, ref.expected  

	test('returns $expected', function()  
		expect(a + b).toBe(expected)  
	end)  

	test('returned value not be greater than $expected', function()  
		expect(a + b).never.toBeGreaterThan(expected)  
	end)  

	test('returned value not be less than $expected', function()  
		expect(a + b).never.toBeLessThan(expected)  
	end)  
end)  
```
```

--------------------------------

### jest.getEngineFrameTime()

Source: https://jsdotlua.github.io/jest-lua/jest-object

Gets the frame time by which timers are processed.

```APIDOC
## jest.getEngineFrameTime()

### Description
`jest.getEngineFrameTime` gets the frame time by which timers are processed.

### Method
N/A (function call)

### Endpoint
N/A

### Parameters
None

### Request Example
N/A

### Response
Returns the frame time in milliseconds.

### Response Example
N/A
```

--------------------------------

### Create basic jest.config.lua

Source: https://jsdotlua.github.io/jest-lua

Basic Jest Lua configuration file that sets testMatch to match all files ending with .spec.

```lua
return {  
	testMatch = { "**/*.spec" }  
}  

```

--------------------------------

### beforeAll(fn, timeout)

Source: https://jsdotlua.github.io/jest-lua/api

Runs a function before any tests in the file. Waits for returned promises or generators. Optional timeout in milliseconds (default 5 seconds). Useful for global setup.

```APIDOC
## beforeAll(fn, timeout)

### Description
Runs a function before any of the tests in this file run. If the function returns a promise or is a generator, Jest Lua waits for that promise to resolve before running tests. Optionally, you can provide a timeout (in milliseconds) for specifying how long to wait before aborting. The default timeout is 5 seconds.

### Method
Function Call

### Endpoint
beforeAll(fn, timeout)

### Parameters
- **fn** (function) - Required - The function to run before tests.
- **timeout** (number) - Optional - Time in milliseconds to wait before aborting. Default is 5000.

### Request Example
```lua
local globalDatabase = makeGlobalDatabase()

beforeAll(function()
	-- Clears the database and adds some testing data.
	-- Jest Lua will wait for this promise to resolve before running tests.
	return globalDatabase:clear()
		:then(function()
			return globalDatabase:insert({testData = 'foo'})
		end)
end)
```

### Response
No return value documented.

```

```APIDOC
## beforeEach(fn, timeout)

### Description
Runs a function before each of the tests in this file runs. If the function returns a promise or is a generator, Jest Lua waits for that promise to resolve before running the test. Optionally, you can provide a timeout (in milliseconds) for specifying how long to wait before aborting. The default timeout is 5 seconds.

### Method
Function Call

### Endpoint
beforeEach(fn, timeout)

### Parameters
- **fn** (function) - Required - The function to run before each test.
- **timeout** (number) - Optional - Time in milliseconds to wait before aborting. Default is 5000.

### Request Example
```lua
local globalDatabase = makeGlobalDatabase()

beforeEach(function()
	-- Clears the database and adds some testing data.
	-- Jest Lua will wait for this promise to resolve before running tests.
	return globalDatabase:clear()
		:then(function()
			return globalDatabase:insert({testData = 'foo'})
		end)
end)
```

### Response
No return value documented.

```

```APIDOC
## describe(name, fn)

### Description
Creates a block that groups together several related tests. Can be nested to create a hierarchy of tests. Not required, but handy for organizing tests.

### Method
Function Call

### Endpoint
describe(name, fn)

### Parameters
- **name** (string) - Required - The name of the describe block.
- **fn** (function) - Required - The function containing the tests and nested describes.

### Request Example
```lua
local myBeverage = {
	delicious = true,
	sour = false
}

describe('my beverage', function()
	test('is delicious', function()
		expect(myBeverage.delicious).toBeTruthy()
	end)

	test('is not sour', function()
		expect(myBeverage.sour).toBeFalsy()
	end)
end)
```

### Response
No return value documented.

```

--------------------------------

### describe.skip.each(...args)(name, fn) example

Source: https://jsdotlua.github.io/jest-lua/api

Use describe.skip.each with arguments to skip a data-driven test suite. The tests inside the skipped block will not run, but a test outside will.

```lua
describe.skip.each({'a | b | expected'},  
	{1, 1, 2},  
	{1, 2, 3},  
	{2, 1, 3}  
)('returns $expected when $a is added $b', function(ref)  
	local a, b, expected = ref.a, ref.b, ref.expected  
  
	test('will not be ran', function()  
		expect(a + b).toBe(expected)  
	end)  
end)  
  
test('will be ran', function()  
	expect(1 / 0).toBe(math.huge)  
end)  

```

--------------------------------

### toBeGreaterThanOrEqual example

Source: https://jsdotlua.github.io/jest-lua/expect

Test that ouncesPerCan() returns a value at least 12.

```lua
it('ounces per can is at least 12', function()  
	expect(ouncesPerCan()).toBeGreaterThanOrEqual(12)  
end)  

```

--------------------------------

### describe.each(table) with object rows

Source: https://jsdotlua.github.io/jest-lua/api

Example of describe.each using a table of objects. Each row is passed as a single reference argument, and properties are accessed via dot notation.

```lua
describe.each({  
	{a = 1, b = 1, expected = 2},  
	{a = 1, b = 2, expected = 3},  
	{a = 2, b = 1, expected = 3},  
})('.add($a, $b)', function(ref)  
	local a, b, expected = ref.a, ref.b, ref.expected  
  
	test('returns $expected', function()  
		expect(a + b).toBe(expected)  
	end)  
  
	test('returned value not be greater than $expected', function()  
		expect(a + b).never.toBeGreaterThan(expected)  
	end)  
  
	test('returned value not be less than $expected', function()  
		expect(a + b).never.toBeLessThan(expected)  
	end)  
end)  

```

--------------------------------

### describe.each(table)(name, fn, timeout)

Source: https://jsdotlua.github.io/jest-lua/api

Runs the same test suite with different data provided as a table of arrays. Each row's values are passed as arguments to the test function.

```APIDOC
## describe.each(table)(name, fn, timeout)

### Description
Runs the same test suite with different data provided as a table of arrays. Each row's values are passed as arguments to the test function.

### Parameters
- **table** (array of arrays) - Required - The arguments passed into `fn` for each row. A 1D array of primitives is mapped to a table (e.g., `{1, 2, 3} -> {{1}, {2}, {3}}`).
- **name** (string) - Required - The title of the test suite.
- **fn** (function) - Required - The suite of tests to run; receives the parameters from each row as function arguments.
- **timeout** (number, optional) - Optional - Time in milliseconds to wait for each row before aborting. Default is 5 seconds.

### Example
```lua
describe.each({  
	{1, 1, 2},  
	{1, 2, 3},  
	{2, 1, 3},  
})('.add($a, $b)', function(a, b, expected)  
	test('returns $expected', function()  
		expect(a + b).toBe(expected)  
	end)  

	test('returned value not be greater than $expected', function()  
		expect(a + b).never.toBeGreaterThan(expected)  
	end)  

	test('returned value not be less than $expected', function()  
		expect(a + b).never.toBeLessThan(expected)  
	end)  
end)  
```

### Example with object rows
```lua
describe.each({  
	{a = 1, b = 1, expected = 2},  
	{a = 1, b = 2, expected = 3},  
	{a = 2, b = 1, expected = 3},  
})('.add($a, $b)', function(ref)  
	local a, b, expected = ref.a, ref.b, ref.expected  

	test('returns $expected', function()  
		expect(a + b).toBe(expected)  
	end)  

	test('returned value not be greater than $expected', function()  
		expect(a + b).never.toBeGreaterThan(expected)  
	end)  

	test('returned value not be less than $expected', function()  
		expect(a + b).never.toBeLessThan(expected)  
	end)  
end)  
```
```
Tokens:
Raw