mlua_lspec/lib.rs
1//! BDD test framework for Lua on mlua.
2//!
3//! Embeds a forked copy of [lust](https://github.com/bjornbytes/lust)
4//! (MIT, single-file, zero-dependency) and provides Rust APIs for
5//! executing tests and collecting structured results.
6//!
7//! Includes spy/stub/mock test doubles implemented as Rust `UserData`.
8//!
9//! # Quick start
10//!
11//! ```rust
12//! let summary = mlua_lspec::run_tests(r#"
13//! local describe, it, expect = lust.describe, lust.it, lust.expect
14//! describe('example', function()
15//! it('works', function()
16//! expect(1 + 1).to.equal(2)
17//! end)
18//! end)
19//! "#, "@test.lua").unwrap();
20//!
21//! assert_eq!(summary.passed, 1);
22//! assert_eq!(summary.failed, 0);
23//! ```
24//!
25//! # Granular control
26//!
27//! For advanced use cases (e.g. registering lust on a pre-existing
28//! VM or running multiple test suites in sequence), use
29//! [`register`] and [`collect_results`] directly instead of
30//! [`run_tests`].
31//!
32//! ```rust
33//! use mlua::prelude::*;
34//! use mlua_lspec::{register, register_doubles, collect_results};
35//!
36//! let lua = Lua::new();
37//! register(&lua).unwrap();
38//! register_doubles(&lua).unwrap();
39//!
40//! lua.load(r#"
41//! local describe, it, expect = lust.describe, lust.it, lust.expect
42//! describe('inline', function()
43//! it('works', function()
44//! expect(42).to.equal(42)
45//! end)
46//! end)
47//! "#).exec().unwrap();
48//!
49//! let summary = collect_results(&lua).unwrap();
50//! assert_eq!(summary.passed, 1);
51//! ```
52//!
53//! # Test doubles
54//!
55//! The [`doubles`] module provides Rust-backed spy, stub, and mock
56//! objects exposed as Lua `UserData`. These are registered
57//! automatically by [`run_tests`] as the `test_doubles` global table.
58//!
59//! ```lua
60//! local s = test_doubles.spy(function(x) return x * 2 end)
61//! s(5)
62//! assert(s:call_count() == 1)
63//! assert(s:was_called_with(5))
64//!
65//! local st = test_doubles.stub()
66//! st:returns(42)
67//! assert(st() == 42)
68//! ```
69
70pub mod doubles;
71pub mod framework;
72mod types;
73
74pub use doubles::register as register_doubles;
75pub use framework::{collect_results, register, run_tests};
76pub use types::{TestResult, TestSummary};