🌖🧪 busted interop examples

Examples for combining Neovim/Lua test frameworks with busted

Summary

We advocate for using luarocks and busted for testing, primarily for the following reasons:

• Familiarity: It is the de facto tried and tested standard in the Lua community, with a familiar API modeled after rspec.
• Consistency: Having a consistent API makes life easier for
  • Contributors to your project.
  • Package managers, who run test suites to ensure they don't deliver a broken version of your plugin.
• Better reproducibility: By using luarocks to manage your test dependencies, you can easily pin them. Checking out git repositories is prone to flakes in CI and "it works on my machine" issues.
• Dependency management: With luarocks, you have the whole ecosystem of Lua modules at your fingertips, making it easy to manage and integrate dependencies for your project.

We do, however, acknowledge that some plugin authors may have additional requirements. For example, something that is not easy with our recommended busted setup is process isolation.

Fortunately, other test frameworks are available on luarocks and can be combined with (and run from within) busted.

Tip

If you find yourself limited due to a lack of process isolation, first consider rethinking your architecture.

A well-designed code base keeps its core logic as pure as possible, which makes it easy to reason about and easy to test. Side-effects (IO, environment, state, ...) should be "woven in" through an interface¹.

Prerequisites

We assume you are familiar with our recommended method for running tests with busted. If not, here are some resources to get you started:

• neovim-lua-plugin-template (Neovim plugin template)
• nvim-busted-action (GitHub Actions workflow)
• nlua (library)
• Testing Neovim plugins with Busted (blog post)

Frameworks that work with busted out of the box

• nvim-nio The nio.tests module provides async versions of busted's test functions.
• yo-dawg.nvim A convenience library for controlling a Neovim process embedded inside another Neovim process, written with busted tests in mind.

Examples for making other frameworks interoperable with busted

The following examples have not been designed with busted interoperability in mind, but can still be combined with busted.

• mini.test

TODO:

• nvim-test (needs triage)

Footnotes

1. This can be done easily, without having to understand monads (see for example the Universal Architecture). Nevertheless, in some cases (especially when it comes to UI), it can be challenging. ↩