Skip to main content

Crate mlua_probe_core

Crate mlua_probe_core 

Source
Expand description

Core debug and testing engine for mlua.

Provides two main capabilities for Lua code running inside an mlua Lua instance:

§Architecture

The debug engine uses a VM-thread blocking model:

  • A Lua debug hook pauses the VM thread when a breakpoint or step condition is met.
  • While paused, the hook dispatches inspection commands (locals, upvalues, evaluate) on the VM thread — required because lua_getlocal and friends are not thread-safe.
  • A resume command (continue / step) unblocks the hook and lets Lua execution proceed.

The testing module is independent of the debug engine. It creates a fresh Lua VM per test run, so tests are fully isolated.

§Debugging example

use mlua::prelude::*;
use mlua_probe_core::{DebugSession, DebugEvent};

let lua = Lua::new();
let (session, controller) = DebugSession::new();
session.attach(&lua).unwrap();

controller.set_breakpoint("@main.lua", 3, None).unwrap();

// Run Lua on a separate thread so the current thread can
// interact with the controller.
let handle = std::thread::spawn(move || {
    lua.load(r#"
        local x = 1
        local y = 2
        local z = x + y
        return z
    "#)
    .set_name("@main.lua")
    .eval::<i64>()
});

// Wait for the VM to pause.
let event = controller.wait_event().unwrap();
// Inspect, step, continue …
controller.continue_execution().unwrap();

let result = handle.join().unwrap().unwrap();
assert_eq!(result, 3);

§Testing example

use mlua_probe_core::testing;

let summary = testing::framework::run_tests(r#"
    local describe, it, expect = lust.describe, lust.it, lust.expect
    describe('math', function()
        it('adds', function()
            expect(1 + 1).to.equal(2)
        end)
    end)
"#, "@test.lua").unwrap();

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

Modules§

testing
BDD test framework for Lua, re-exported from mlua_lspec.

Structs§

Breakpoint
A single breakpoint definition.
BreakpointId
Unique identifier for a breakpoint.
CompletionNotifier
A handle for notifying the session that Lua execution has completed.
DebugController
Controls a DebugSession from a frontend (MCP server, DAP adapter, Web console, …).
DebugSession
A debug session attached to a single Lua instance.
StackFrame
A single frame in the Lua call stack.
Variable
A single variable (local, upvalue, or global).
VariableRef
Opaque handle used to expand structured values (tables) on demand.

Enums§

DebugError
Errors returned by DebugController and DebugSession methods.
DebugEvent
An event emitted by the debug engine.
FrameKind
What produced this stack frame.
OutputCategory
Category for DebugEvent::Output.
PauseReason
Why the VM was paused.
SessionState
State of a debug session.
StepMode
How the stepping engine should behave after a resume.