Laura · unit-testing framework for Lua

Laura 👧🏻 is a lightweight unit-testing framework for Lua with simplicity in mind. The framework has no dependencies and is compatible with Lua versions 5.1—5.4, luau, LuaJIT and LuaJIT-OpenResty.

Features

• Lightweight and minimalist
• Easy to install and use
• No Dependencies
• Understandable, human-readable reports
• Includes: stubs, spies and hooks
• Compatible with any Lua 5.1+ version and LuaJIT

📚 Complete documentation

Getting started

Install

There are several ways to install: LuaRocks, Make utility, and manual installation.

LuaRocks

luarocks install laura

...or use the tree in the user's home directory.

luarocks --local install laura

Makefile

Using the make utility to install.

Clone the source code.

git clone https://github.com/dknight/laura.git

Run make

make install

There are variables that can be set with make.

• PREFIX: basic installation prefix for the module (default /usr/local);
• BINDIR: use the binary path in the file system tree (default ${PREFIX}/bin);
• LIBDIR: where to put the shared libraries (default ${PREFIX}/share/lua/${LUA_VERSION})

Consider:

PREFIX=/opt/lua/libs BINDIR=/opt/bin LIBDIR=/opt/share make install

Manual installation

Just clone the repository and include the location to LUA_PATH environment variable.

Writing tests

Writing tests is pretty simple and straightforward.

local laura = require("laura")

local it = laura.it
local describe = laura.describe
local expect = laura.expect

describe("my test case", function()
	it("should be equal to three", function()
		expect(1 + 2).toEqual(3)
	end)
end)

Skipping tests

There is a possibility to skip the test case or suite using the skip method. Skipped tests won't run and will be reported as [SKIPPED]. Please note that there is a : colon. If you mark a suite as skipped, all its children will also be skipped.

local laura = require("laura")

local it = laura.it
local describe = laura.describe
local expect = laura.expect

describe:skip("skip", function()
	it("should be skipped", function()
		expect(1 + 2).toEqual(3)
	end)
end)

Only tests

Like skipped tests, mark tests with only; only marked tests will run; others will be ignored, useful for debugging.

local laura = require("laura")

local it = laura.it
local describe = laura.describe
local expect = laura.expect

describe:only("only suite", function()
	it("should be three", function()
		expect(1 + 2).toEqual(3)
	end)
end)

Running tests

Using Command Line Client

By default, Laura looks for files with pattern *_test.lua in the given directory. Current directory is the default value.

laura [test_dir]

Using API

Consider example:

local laura = require("laura")
local TextReporter = require("laura.reporters.text")

local it = laura.it
local describe = laura.describe
local expect = laura.expect
local Runner = laura.Runner

describe("my test case", function()
	it("should be equal to three", function()
		expect(1 + 2).toEqual(3)
	end)
end)

local runner = Runner:new()
local results = runner:runTests()
local reporter = TextReporter:new(results)
reporter:report()
runner:done()

Running in Docker container

Building an image:

docker build -t <your-image-name> .

Run the container; notice that by default /app is the working directory; change it Dockerfile if you want to place your code in another directory.

docker run -v $(pwd):/app --rm -it <your-image-name>

Configuration

There are the options that can be customized. Check more options on the documentation page.

Options can be set in any *.lua file that returns a module and specified with a flag.

laura -c <path_to_config.lua> [test_dir]

Another way to create .laurarc file in your project directory and setup preferences in the same format as in the configuration file.

Also, there are "private" configuration fields, which are not recommended to change, unless you know that you know what you are doing.

Code coverage

Code coverage can be enabled in .laurarc configuration file. Or if you are using CLI flag --coverage. There are extra coverage reporters can be used, like: terminal, html, csv, etc. Check configuration file source.

Documentation

Read the complete documentation on the external website.

Known issues

Code coverage is yet to be finalized. It might have the inaccuracies.

Credits

Original picture by lumeish, used under Creative Commons Attribution v4.0 International license.

Coverage line scanner is modified algorithm based on lunarmodules/luacov, published under MIT license.

Contribution

Any help is appreciated. Found a bug, typo, inaccuracy, etc.? Please do not hesitate to create a pull request or submit an issue.

License

MIT 2024