https://github.com/mikavilpas/tui-sandbox
🧪 A terminal test environment and development playground 🛝
https://github.com/mikavilpas/tui-sandbox
cypress terminal testing
Last synced: 3 months ago
JSON representation
🧪 A terminal test environment and development playground 🛝
- Host: GitHub
- URL: https://github.com/mikavilpas/tui-sandbox
- Owner: mikavilpas
- License: mit
- Created: 2024-08-19T17:28:08.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2024-10-30T05:50:50.000Z (6 months ago)
- Last Synced: 2024-10-30T08:39:40.261Z (6 months ago)
- Topics: cypress, terminal, testing
- Language: TypeScript
- Homepage:
- Size: 3.04 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 🧪 A terminal test environment and development playground 🛝
[](https://www.npmjs.com/package/@tui-sandbox/library)
tui-sandbox is a framework for using the [cypress](https://www.cypress.io/) browser testing tool to run tests against
terminal applications.
 tests](documentation/images/yazi-example.webp)
> ☝🏻 example of tui-sandbox running Neovim with [yazi.nvim](https://github.com/mikavilpas/yazi.nvim). The yazi.nvim
> Neovim plugin shows the terminal file manager [yazi](https://github.com/sxyazi/yazi/) in a floating window inside
> Neovim, and tests their full integration exactly as a user interacts with them.
## The problems tui-sandbox solves
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
1. Ensure that all contributors have the same development environment
2. Write tests that are reliable, easy to maintain, and easily understood
tui-sandbox can solve these issues:
### Develop terminal applications in a live environment
The preview is fully interactive. You can use your application exactly as you would normally, including mouse clicks.
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 development setup is kept separate from the test environment
- each test has its own instance of the application
- each test has its own mini directory structure. This makes the tests more maintainable and discoverable.
- The directory structure is also available as a TypeScript type, so you get completions and type errors in your
tests.
> ☝🏻 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.
### Write and run integration tests for terminal applications
Using [cypress](https://www.cypress.io/) 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
## Limitations
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._
## Getting started
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](https://github.com/mikavilpas/yazi.nvim): Neovim plugin for file manager integration
- [blink-ripgrep.nvim](https://github.com/mikavilpas/blink-ripgrep.nvim): Neovim plugin for
[ripgrep](https://github.com/BurntSushi/ripgrep) search results