mlua-lspec

BDD test framework for Lua on mlua.

Embeds a forked copy of lust and provides Rust APIs for executing Lua tests with structured result collection. Includes Rust-backed spy/stub/mock test doubles.

Quick start

let summary = mlua_lspec::run_tests(r#"
    local describe, it, expect = lust.describe, lust.it, lust.expect

    describe('math', function()
        it('adds numbers', function()
            expect(1 + 1).to.equal(2)
        end)
    end)
"#, "@test.lua").unwrap();

assert_eq!(summary.passed, 1);
assert_eq!(summary.failed, 0);

Assertions

-- Equality
expect(value).to.equal(expected)
expect(value).to.equal(expected, epsilon)  -- float tolerance
expect(value).to_not.equal(other)

-- Identity
expect(value).to.be(same_ref)

-- Truthiness / existence
expect(value).to.be.truthy()
expect(value).to.exist()
expect(nil).to_not.exist()

-- Type checking
expect(value).to.be.a('string')
expect(value).to.be.an('number')

-- Comparison
expect(10).to.be.gt(5)     -- greater than
expect(10).to.be.gte(10)   -- greater than or equal
expect(3).to.be.lt(5)      -- less than
expect(3).to.be.lte(3)     -- less than or equal

-- Tables
expect(tbl).to.have(value)            -- contains value
expect(tbl).to.have_key('name')       -- has key
expect(tbl).to.have_length(3)         -- #tbl == 3

-- Strings
expect(str).to.have_length(5)         -- #str == 5
expect(str).to.match('pattern')       -- Lua pattern match

-- Errors
expect(fn).to.fail()
expect(fn).to.fail.with('pattern')

-- Negation (all assertions support to_not)
expect(value).to_not.equal(other)
expect(3).to_not.be.gt(5)
expect(tbl).to_not.have_key('missing')

Test doubles

-- Spy: records calls, delegates to original
local s = test_doubles.spy(function(x) return x * 2 end)
s(5)
s:call_count()            -- 1
s:call_args(1)            -- {5}
s:was_called_with(5)      -- true
s:reset()                 -- clear call history

-- Stub: returns fixed values
local st = test_doubles.stub()
st:returns(42)
st()                      -- 42

-- Spy on table method (with revert)
local spy = test_doubles.spy_on(obj, "method_name")
obj.method_name("arg")
spy:call_count()          -- 1
spy:revert()              -- restore original

Granular control

For pre-existing Lua VMs (e.g. testing Rust APIs exposed to Lua):

use mlua::prelude::*;

let lua = Lua::new();

// Register your application globals
lua.globals().set("my_api", /* ... */).unwrap();

// Register lspec
mlua_lspec::register(&lua).unwrap();
mlua_lspec::register_doubles(&lua).unwrap();

// Run tests
lua.load(r#"
    local describe, it, expect = lust.describe, lust.it, lust.expect
    describe('my_api', function()
        it('works', function()
            expect(my_api.ping()).to.equal("pong")
        end)
    end)
"#).exec().unwrap();

let summary = mlua_lspec::collect_results(&lua).unwrap();
assert_eq!(summary.failed, 0);

License