tui-sandbox is a framework for using the cypress browser testing tool to run tests against terminal applications. Currently only Neovim is supported.
☝🏻 example of tui-sandbox running Neovim with yazi.nvim. The yazi.nvim Neovim plugin shows the terminal file manager yazi in a floating window inside Neovim, and tests their full integration exactly as a user interacts with them.
Modern terminal applications are complex. They often depend on external programs as well as the network and filesystem. The development ecosystem is also diverse, spanning many different toolchains.
As a developer, it is difficult to
- Ensure that all contributors have the same development environment
- Write tests that are reliable, easy to maintain, and easily understood
tui-sandbox can solve these issues:
The preview is fully interactive. You can use Neovim exactly as you would normally, including mouse clicks.
You can run Neovim inside tui-sandbox and see the changes in your plugin code reflected in the running Neovim instance. When you update your test, the tests automatically rerun with the latest changes.
You can also isolate the development and testing from your own config
- your own Neovim setup is kept separate from the test environment
- each test has its own Neovim instance
- each test has its own mini directory structure that is type safe. This makes the tests more maintainable and discoverable.
☝🏻 Neovim using the type-safe test environment provided by tui-sandbox. The language server offers completions for the available file paths along with some metadata.
Using cypress gives us great features for free, such as:
- automatically waiting for asynchronous things to happen
- make assertions on many things
- test the terminal colors that are visible
- images might work too, but I haven't tried them yet 😄
- emoji are supported 👍🏻
- time travel debugging
- access to screenshots and videos of the test run in case it fails
- type safety with TypeScript
The main limitation is that tui-sandbox is much slower for running tests than a unit testing tool. It trades performance for the ability to run tests in a live environment (giving very strong guarantees that the tests are valid).
For example, it takes 70 seconds to run 40 test cases in yazi.nvim (1.75s per test). In contrast, it takes 0.21 seconds to run 110 unit tests in the same project (0.002s per test).
Note that this is true for any unit/integration test comparison in general, so I recommend using both.
Even though it's being used in a nontrivial project, this framework is not very mature yet. If you are interested in using it, please reach out to me via github issues. I would love to help.
Example projects that use tui-sandbox:
- yazi.nvim: Neovim plugin for file manager integration
- blink-ripgrep.nvim: Neovim plugin for ripgrep search results