lust
A lightweight, single-file Lua test framework with expect-style assertions, spies, and nested describe/it blocks.
What is lust?
Lust is a lightweight, single-file test framework for Lua that enables developers to write structured tests using describe/it blocks and expect-style assertions. It solves the problem of adding testing to Lua projects without heavy dependencies or complex configuration.
Lua developers looking for a simple, non-opinionated testing solution for small to medium-sized projects, especially those who value minimal setup and easy integration.
Developers choose Lust for its simplicity and ease of use—it's a single file with no external dependencies, supports modern testing features like spies and nested groups, and allows customization without being overly prescriptive.
Overview
Lightweight Lua test framework
Use Cases
Best For
- Adding quick testing to existing Lua scripts or libraries
- Projects that need a minimal, dependency-free test framework
- Writing behavior-driven tests with nested describe/it blocks
- Mocking and tracking function calls with spies
- Extending test assertions with custom matchers
- Embedded Lua environments where console color support may be limited
Not Ideal For
- Projects requiring advanced mocking features like return value stubbing or complex call verification
- Teams that need built-in code coverage reports or parallel test execution for large suites
- Environments requiring extensive CI/CD integration with standardized output formats like JUnit XML
Pros & Cons
Pros
Lust is just one Lua file with no dependencies, making it trivial to integrate by copying the file into a project, as shown in the usage section.
Offers chainable expect-style assertions like `expect(x).to.equal(y)` with support for tables and custom matchers, improving test clarity based on the documentation.
Includes spying to track function calls and arguments, useful for lightweight mocking without external libraries, as demonstrated in the spies section.
Supports nested describe blocks and before/after handlers for logical grouping and setup, allowing structured test suites per the examples.
Cons
Spies only track invocation data and don't support stubbing return values or advanced mocking, which may require manual workarounds for complex tests.
Users must write custom scripts to execute tests, as Lust lacks automatic test discovery or CLI tools, adding setup overhead for larger projects.
The `equal` assertion for tables ignores metatables, which can lead to inaccurate comparisons in Lua code using object-oriented patterns or metamethods.
Frequently Asked Questions
Related Projects
bustedElegant Lua unit testing.
LuassertAssertion library for Lua
luassertAssertion library for Lua
telescopeA highly customizable test library for Lua that allows declarative tests with nested contexts.
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.