neotest-busted

🚧 Highly experimental 🚧

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

Table of contents

• Requirements
• Configuration
• Defining tests
• Parametric tests
• Debugging tests
• Luarocks and Busted
• Running from the command line
• Contributing
• 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,
            -- Find parametric tests
            parametric_test_discovery = false,
        }),
    },
})

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.

Parametric tests

Important

Supporting parametric tests requires extra computation to discover them so support is disabled by default. You need to set parametric_test_discovery to true if you want neotest-busted to find parametric tests.

neotest-busted supports parametric tests that are generated at runtime as opposed to being defined entirely at source-level as shown below. describe's can also be parametric and are also supported.

Due to technical limitations, parametric tests won't be shown in the neotest summary until they have been run.

describe("parametric tests", function()
    for i = 1, 3 do
        it(("test %d"):format(i), function()
            assert.are.same(i, i)
        end)
    end
end)

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.

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" } })

Contributing

Thanks for considering to contribute. Please see the instructions here.

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