lust

lust.it(name, func)

Used to declare a test, which consists of a set of assertions. name is a string used to describe the test, and func is a function containing the assertions.

Assertions

Lust uses “expect style” assertions. An assertion begins with lust.expect(value) and other modifiers can be chained after that:

lust.expect(x).to.exist()

Fails only if x is nil.

lust.expect(x).to.equal(y)

Performs a strict equality test, failing if x and y have different types or values. Tables are tested by recursively ensuring that both tables contain the same set of keys and values. Metatables are not taken into consideration.

lust.expect(x).to.be(y)

Performs an equality test using the == operator. Fails if x ~= y.

lust.expect(x).to.be.truthy()

Fails if x is nil or false.

lust.expect(x).to.be.a(y)

If y is a string, fails if type(x) is not equal to y. If y is a table, walks up x’s metatable chain and fails if y is not encountered.

lust.expect(x).to.have(y)

If x is a table, ensures that at least one of its keys contains the value y using the == operator. If x is not a table, this assertion fails.

lust.expect(f).to.fail()

Ensures that the function f causes an error when it is run.

lust.expect(x).to.match(p)

Fails if the string representation of x does not match the pattern p.

lust.expect(x).to_not.*

Negates the assertion.

Spies

Befores and Afters

You can define functions that are called before and after every call to lust.it using lust.before and lust.after. They are scoped to the describe block that contains them as well as any inner describe blocks.

lust.before(fn)

Set a function that is called before every test inside this describe block. fn will be passed a single string containing the name of the test about to be run.

lust.after(fn)

Set a function that is called after every test inside this describe block. fn will be passed a single string containing the name of the test that was finished.

Custom Assertions

Example of adding a custom empty assertion:

local lust = require 'lust'

lust.paths.empty = {
  test = function(value)
    return #value == 0,
      'expected ' .. tostring(value) .. ' to be empty',
      'expected ' .. tostring(value) .. ' to not be empty'
  end
}

table.insert(lust.paths.be, 'empty')

lust.expect({}).to.be.empty()
lust.expect('').to.be.empty()

First we define the assertion in the lust.paths table. Each path is a table containing a test function which performs the assertion. It returns three values: the result of the test (true for pass, false for fail), followed by two messages: the first for a normal expectation failure, the second for when the expectation is negated.

We then insert our ‘empty’ assertion into the be path – the numeric keys of a path represent the possible expectations that can be chained.