1 - About

The prtr-test module is a simple Lua module that helps writing tests for other Lua modules. It's mainly exposing an expect global function that can be used instead of assert to get better error messages when a test fails. Since this is the only point of the library you may want to have a look at the examples below.

The name test is not original, but it reflects the purpose of the library. The prtr- prefix (a contraction for piratery.net, the website domain) is used in case some other Linux bindings emerge with the same naming problems.


All support is done through the Lua mailing list.

Feel free to ask for further developments. I can't guarantee that I'll develop everything you ask, but I want my code to be as useful as possible, so I'll do my best to help you. You can also send me request or bug reports (for code and documentation) directly at jerome.vuarand@gmail.com.


This module is written and maintained by Jérôme Vuarand.

It is available under a MIT-style license.

2 - Installation

prtr-test sources are available in its Mercurial repository:

hg clone http://hg.piratery.net/test/

Tarballs of the latest code can be downloaded directly from there: as gz, bz2 or zip.

Finally, I published a rockspec:

luarocks install prtr-test

3 - Manual

This module is very basic, it creates one global function, expect, that is similar to the Lua built-in assert function, but that will provide better default error messages.

To load the module, simply write:

require 'test'

From then on a global expect function will be available.

expect ( expectation, value )

The expect function takes two Lua values parameters. It will throw an error if the two values don't match. For immutable values (nil, booleans, numbers and strings), the values must be identical (as defined by the == operator). For functions and threads, both values must be references to the same object.

The case of tables is where this module can come handy. Both tables are compared recursively, and each key-value pair must match, with the restriction that keys can only be booleans, numbers or strings (otherwise an error is thrown).

Finally, if both values are userdata sharing the same metatable, and that metatable has a __tostring field, tostring is called on both values and the resulting strings are compared.

4 - Examples

The purpose of this module is only to get better generated error messages when tests fail. Here are some example to help you decide if this module is worth using it.

When comparing simple values, the following:

local function f() return 42 end
expect('foo', f())

would throw the error:

script.lua:2: expectation failed! foo (string) expected, got 42 (number)

When comparing tables, a path to the first mismatching field will be displayed. The following:

local function f() return {
    data = {'a', 'b2', 'c'},
} end
expect({ data = {'a', 'b', 'c'} }, f())

would throw the error:

script.lua:4: expectation failed! b (string) expected for field .data[2], got b2 (string)