neotest-busted

🚧 Highly experimental 🚧

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

Table of contents

• 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",
            -- Only use a luarocks installation in the project's directory. If
            -- true, installations in $HOME and global installations will be
            -- ignored. Useful for isolating the test environment
            local_luarocks_only = true,
        }),
    },
})

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.

Warning

If you have set busted_command to a non-nil value in the setup function, neotest-busted will not know where to look for appropriate lua paths and will not look for installations as specified below to avoid setting up paths for a different busted installation.

In this case, you should set busted_paths and busted_cpaths to appropriate paths.

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

Important

You need to set local_luarocks_only to false for neotest-busted to find your home directory installation.

The following command will install busted in your home directory.

> luarocks install --local busted

Global install

Important

You need to set local_luarocks_only to false for neotest-busted to find your global installation.

> 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 <path-to-neotest-busted>/scripts/test-runner.lua tests/my_spec.lua

Using busted directly

You can also provide a .busted config file and run your tests using busted. Learn more about busted configuration files from the official docs or take a look at the example here.

Pass extra arguments to neotest to run a specific task. For example, to run the "integration" task in a test file:

require("neotest").run.run({ vim.fn.expand("%"), extra_args = { "--run", "integration" } })

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.

Q: Why is neotest-busted tested using plenary?

The test could be run via neotest-busted itself but I decided to use plenary instead to use another test runner so that bugs in neotest-busted won't affect its own tests.

Inspiration

• Using Neovim as Lua interpreter with Luarocks
• nlua
• Test your Neovim plugins with luarocks & busted