neotest-busted

🚧 Highly experimental 🚧

Neotest adapter for running tests using busted with neovim as the lua interpreter.

Requirements
Configuration
Defining tests
Luarocks and Busted
Running from the command line
Debugging tests
FAQ

Requirements

Neovim 0.9.0+ for the -l option.
Neotest 4.0.0+ (which requires neovim 0.9.0+).
busted installed (in a project-local, user, or global location, see here).

Configuration

Setup with neotest. Leave values as nil to leave them unspecified.

require("neotest").setup({
    adapters = {
        require("neotest-busted")({
            -- Leave as nil to let neotest-busted automatically find busted
            busted_command = "<path to a busted executable>",
            -- Extra arguments to busted
            busted_args = { "--shuffle-files" },
            -- List of paths to add to package.path in neovim before running busted
            busted_paths = { "my/custom/path/?.lua" },
            -- List of paths to add to package.cpath in neovim before running busted
            busted_cpaths = { "my/custom/path/?.so" },
            -- Custom config to load via -u to set up testing.
            -- If nil, will look for a 'minimal_init.lua' file
            minimal_init = "custom_init.lua",
        }),
    },
})

Defining tests

Please refer to the official busted documentation.

Async tests

Running an asynchronous test is done by wrapping the test function in a call to async. This also works for before_each and after_each.

local async = require("neotest-busted.async")
local control = require("neotest.async").control

describe("async", function()
    before_each(async(function()
        vim.print("async before_each")
    end))

    it("async test", async(function()
        local timer = vim.loop.new_timer()
        local event = control.event()

        -- Print a message after 2 seconds
        timer:start(2000, 0, function()
            timer:stop()
            timer:close()
            vim.print("Hello from async test")
            event.set()
        end)

        -- Wait for the timer to complete
        event.wait()
    end))
end)

The async function takes an optional second timeout argument in milliseconds. If omitted, uses the numerical value of either the NEOTEST_BUSTED_ASYNC_TEST_TIMEOUT or PLENARY_TEST_TIMEOUT environment variables or a default timeout of 2000 milliseconds.

Luarocks and Busted

Install luarocks from the website. neotest-busted will try to find a busted executable automatically at the different locations listed below and in that priority (i.e. a directory-local install takes precedence over a global install). You can check the installation by running luarocks list busted.

Directory-local install

You can install busted in your project's directory by running the following commands.

> cd <your_project>
> luarocks init
> luarocks config --scope project lua_version 5.1
> luarocks install busted

User home directory install

The following command will install busted in your home directory.

> luarocks install --local busted

Global install

> luarocks install busted

Running from the command line

A test-runner.lua script is provided in the scripts/ folder for running tests via the command line. This is useful for running all tests during CI for example.

If you do not provide a minimal_init.lua to set up your test environment, the script will look for one and source it. If you don't specify any tests to run, the command will automatically try to find your tests in a spec/, test/, or tests/ directory.

$ nvim -l ./scripts/test-runner.lua tests/my_spec.lua

Test via rockspec

If you use a rockspec, you can provide a test command so you can run tests using luarocks test.

-- Your rockspec...

test = {
    type = "command",
    command = "nvim -u NONE -l ./scripts/test-runner.lua",
}

Debugging tests

neotest-busted has support for debugging tests via local-lua-debugger-vscode which can be set up via nvim-dap. Once set up, you can set a breakpoint and run the test with the dap strategy. Please refer to the neotest documentation for more information.

FAQ

Q: Can I run async tests with neotest-busted?

Yes. Please see the instructions here.

Busted removed support for async testing in version 2 (even though the docs still mention it) so you could install busted v1 but I haven't tested that.

MisanthropicBit / neotest-busted