KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agents #developer-tools #codex #claude-code #mcp #rust #deepseek-harness #typescript #ai-agent #cli

lust

★ 134 Open GitHub ↗

Lightweight Lua test framework

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Lust
===

Lust is a small library that tests Lua code.  It's useful because it is a single file and isn't very
opinionated, which can make it easier to quickly add testing to a Lua project.

It supports nested describe/it blocks, before/after handlers, expect-style assertions, function
spies, and colors.

Usage
---

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

```Lua
local lust = require 'lust'
local describe, it, expect = lust.describe, lust.it, lust.expect

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

describe('module1', function() -- Can be nested
    it('feature1', function()
      expect(1).to.be.a('number') -- Pass
      expect('astring').to.equal('astring') -- Pass
    end)

it('feature2', function()
      expect(nil).to.exist() -- Fail
    end)
  end)
end)
```

Documentation
---

##### `lust.describe(name, func)`

Used to declare a group of tests.  `name` is a string used to describe the group, and `func` is a function containing all tests and `describe` blocks in the group.  Groups created using `describe` can be nested.

##### `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

Cheatsheet

```lua
expect(...).to.exist()
expect(...).to.be.truthy()
expect(...).to.be.falsy()
expect(...).to.be(...)
expect(...).to.equal(...)
expect(...).to.approximately.equal(...)
expect(...).to.approximately(eps).equal(...)
expect(t).to.have(val)
expect(f).to.fail(pattern?)
expect(x).to_not.*
```

Lust uses "expect style" assertions.  An assertion begins with `lust.expect(value)` and other modifiers can be chained after that.  Some assertions support multiple arguments, denoted by `...`.

##### `lust.expect(...).to.exist()`

Fails only if any of its arguments are `nil`.

##### `lust.expect(...).to.equal(...)`

Performs a strict equality test, failing if the two sets of arguments 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.

This test works with the `approximately` modifier, to test for approximate floating point equality.

##### `lust.expect(...).to.be(...)`

Performs a simple equality test using the `==` operator.

##### `lust.expect(...).to.be.truthy()`

Fails if any of the arguments are `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([pattern])`

Ensures that the function `f` throws an error when it is called with arguments `...`.  An optional
pattern can be used to assert that the error message matches a pattern.

##### `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

##### `lust.spy(table, key, run)` and `lust.spy(function, run)`

Spies on a function and tracks the number of times it was called and the arguments it was called with.  There are 3 ways to specify arguments to this function:

- Specify `nil`.
- Specify a function.
- Specify a table and a name of a function in that table.

The return value is a table that will contain one element for each call to the function. Each element of this table is a table containing the arguments passed to that particular invocation of the function.  The table can also be called as a function, in which case it will call the function it is spying on.  The third argument, `run`, is a function that will be called immediately upon creation of the spy.  Example:

```lua
local object = {
  method = function() end
}

-- Basic usage:
local spy = lust.spy(object, 'method')
object.method(3, 4) -- spy is now {{3, 4}}
object.method('foo') -- spy is now {{3, 4}, {'foo'}}
lust.expect(#spy).to.equal(2)
lust.expect(spy[1][2]).to.equal(4)

-- Using a run function:
local run = function()
  object.method(1, 2, 3)
  object.method(4, 5, 6)
end

lust.expect(lust.spy(object, 'method', run)).to.equal({{1, 2, 3}, {4, 5, 6}})

-- Using a function input:
local add = function(a, b)
  return a + b
end

local spy = lust.spy(add)

spy(1, 2) -- => {{1, 2}}
spy('rain', 'bows') -- => {{1, 2}, {'rain', 'bows'}}

lust.expect(#spy).to.equal(2)
lust.expect(spy[2]).to.equal({'rain', 'bows'})
```

### 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:

```lua
local lust = require 'lust'

lust.paths.empty = {
  test = function(value)
    return #value == 0, 'expected ' .. tostring(value) .. ' to 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 two values: the result of the test (true for
pass, false for fail), followed by a failure message.

We then insert our 'empty' assertion into the `be` path -- the numeric keys of a path represent the
possible expectations that can be chained.

### Non-console Environments

If Lua is embedded in an application and does not run in a console environment that understands ANSI color escapes, the library can be required as follows:

```lua
local lust = require('lust').nocolor()
```

License
---

MIT, see LICENSE for details.

lust

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README