Module lester

Lester is a minimal unit testing framework for Lua with a focus on being simple to use.

Features

  • Minimal, just one file.
  • Self contained, no external dependencies.
  • Simple and hackable when needed.
  • Use describe and it blocks to describe tests.
  • Supports before and after handlers.
  • Colored output.
  • Configurable via the script or with environment variables.
  • Quiet mode, to use in live development.
  • Optionally filter tests by name.
  • Show traceback on errors.
  • Show time to complete tests.
  • Works with Lua 5.1+.
  • Efficient.

Usage

Copy lester.lua file to a project and require it, which returns a table that includes all of the functionality:

local lester = require 'lester'
local describe, it, expect = lester.describe, lester.it, lester.expect

-- Customize lester configuration.
lester.show_traceback = false

-- Parse arguments from command line.
lester.parse_args()

describe('my project', function()
  lester.before(function()
    -- This function is run before every test.
  end)

  describe('module1', function() -- Describe blocks can be nested.
    it('feature1', function()
      expect.equal('something', 'something') -- Pass.
    end)

    it('feature2', function()
      expect.truthy(false) -- Fail.
    end)

    local feature3_test_enabled = false
    it('feature3', function() -- This test will be skipped.
      expect.truthy(false) -- Fail.
    end, feature3_test_enabled)
  end)
end)

lester.report() -- Print overall statistic of the tests run.
lester.exit() -- Exit with success if all tests passed.

Customizing output with environment variables

To customize the output of lester externally, you can set the following environment variables before running a test suite:

  • LESTER_QUIET="true", omit print of passed tests.
  • LESTER_COLOR="false", disable colored output.
  • LESTER_SHOW_TRACEBACK="false", disable traceback on test failures.
  • LESTER_SHOW_ERROR="false", omit print of error description of failed tests.
  • LESTER_STOP_ON_FAIL="true", stop on first test failure.
  • LESTER_UTF8TERM="false", disable printing of UTF-8 characters.
  • LESTER_FILTER="some text", filter the tests that should be run.

Note that these configurations can be changed via script too, check the documentation.

Customizing output with command line arguments

You can also customize output using command line arguments if lester.parse_args() is called at startup.

The following command line arguments are available:

  • --quiet, omit print of passed tests.
  • --no-quiet, show print of passed tests.
  • --no-color, disable colored output.
  • --no-show-traceback, disable traceback on test failures.
  • --no-show-error, omit print of error description of failed tests.
  • --stop-on-fail, stop on first test failure.
  • --no-utf8term, disable printing of UTF-8 characters.
  • --filter="some text", filter the tests that should be run.

Functions

describe (name, func) Describe a block of tests, which consists in a set of tests.
it (name, func, enabled) Declare a test, which consists of a set of assertions.
before (func) Set a function that is called before every test inside a describe block.
after (func) Set a function that is called after every test inside a describe block.
report () Pretty print statistics of all test runs.
exit () Exit the application with success code if all tests passed, or failure code otherwise.
expect.tohumanstring (v) Converts a value to a human-readable string.
expect.fail (func, expected) Check if a function fails with an error.
expect.not_fail (func) Check if a function does not fail with a error.
expect.exist (v) Check if a value is not nil.
expect.not_exist (v) Check if a value is nil.
expect.truthy (v) Check if an expression is evaluates to true.
expect.falsy (v) Check if an expression is evaluates to false.
expect.strict_eq (t1, t2, name) Compare if two values are equal, considering nested tables.
expect.equal (v1, v2) Check if two values are equal.
expect.not_equal (v1, v2) Check if two values are not equal.

Fields

quiet Whether lines of passed tests should not be printed.
color Whether the output should be colorized.
show_traceback Whether a traceback must be shown on test failures.
show_error Whether the error description of a test failure should be shown.
stop_on_fail Whether test suite should exit on first test failure.
utf8term Whether we can print UTF-8 characters to the terminal.
filter A string with a lua pattern to filter tests.
seconds Function to retrieve time in seconds with milliseconds precision, os.clock by default.
colors Table of terminal colors codes, can be customized.
expect Expect module, containing utility function for doing assertions inside a test.


Functions

describe (name, func)
Describe a block of tests, which consists in a set of tests. Describes can be nested.

Parameters:

  • name A string used to describe the block.
  • func A function containing all the tests or other describes.
it (name, func, enabled)
Declare a test, which consists of a set of assertions.

Parameters:

  • name A name for the test.
  • func The function containing all assertions.
  • enabled If not nil and equals to false, the test will be skipped and this will be reported.
before (func)
Set a function that is called before every test inside a describe block. A single string containing the name of the test about to be run will be passed to func.

Parameters:

  • func
after (func)
Set a function that is called after every test inside a describe block. A single string containing the name of the test that was finished will be passed to func. The function is executed independently if the test passed or failed.

Parameters:

  • func
report ()
Pretty print statistics of all test runs. With total success, total failures and run time in seconds.
exit ()
Exit the application with success code if all tests passed, or failure code otherwise.
expect.tohumanstring (v)
Converts a value to a human-readable string. If the final string not contains only ASCII characters, then it is converted to a Lua hexdecimal string.

Parameters:

  • v
expect.fail (func, expected)
Check if a function fails with an error. If expected is nil then any error is accepted. If expected is a string then we check if the error contains that string. If expected is anything else then we check if both are equal.

Parameters:

  • func
  • expected
expect.not_fail (func)
Check if a function does not fail with a error.

Parameters:

  • func
expect.exist (v)
Check if a value is not nil.

Parameters:

  • v
expect.not_exist (v)
Check if a value is nil.

Parameters:

  • v
expect.truthy (v)
Check if an expression is evaluates to true.

Parameters:

  • v
expect.falsy (v)
Check if an expression is evaluates to false.

Parameters:

  • v
expect.strict_eq (t1, t2, name)
Compare if two values are equal, considering nested tables.

Parameters:

  • t1
  • t2
  • name
expect.equal (v1, v2)
Check if two values are equal.

Parameters:

  • v1
  • v2
expect.not_equal (v1, v2)
Check if two values are not equal.

Parameters:

  • v1
  • v2

Fields

quiet
Whether lines of passed tests should not be printed. False by default.
color
Whether the output should be colorized. True by default.
show_traceback
Whether a traceback must be shown on test failures. True by default.
show_error
Whether the error description of a test failure should be shown. True by default.
stop_on_fail
Whether test suite should exit on first test failure. False by default.
utf8term
Whether we can print UTF-8 characters to the terminal. True by default when supported.
filter
A string with a lua pattern to filter tests. Nil by default.
seconds
Function to retrieve time in seconds with milliseconds precision, os.clock by default.
colors
Table of terminal colors codes, can be customized.
expect
Expect module, containing utility function for doing assertions inside a test.
generated by LDoc 1.5.0 Last updated 2023-10-18 08:06:51