{"id":18476352,"url":"https://github.com/mikavilpas/tui-sandbox","last_synced_at":"2026-05-03T10:04:48.663Z","repository":{"id":254542379,"uuid":"844647488","full_name":"mikavilpas/tui-sandbox","owner":"mikavilpas","description":"🧪 A terminal test environment and development playground 🛝","archived":false,"fork":false,"pushed_at":"2025-05-11T13:16:52.000Z","size":4076,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-11T14:25:27.424Z","etag":null,"topics":["cypress","terminal","testing"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mikavilpas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-08-19T17:28:08.000Z","updated_at":"2025-05-11T13:16:55.000Z","dependencies_parsed_at":"2024-08-27T20:14:38.584Z","dependency_job_id":"233f535c-1b49-4406-a456-ad1754cd8455","html_url":"https://github.com/mikavilpas/tui-sandbox","commit_stats":null,"previous_names":["mikavilpas/tui-sandbox"],"tags_count":69,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikavilpas%2Ftui-sandbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikavilpas%2Ftui-sandbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikavilpas%2Ftui-sandbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikavilpas%2Ftui-sandbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mikavilpas","download_url":"https://codeload.github.com/mikavilpas/tui-sandbox/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253579865,"owners_count":21930828,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cypress","terminal","testing"],"created_at":"2024-11-06T10:39:37.192Z","updated_at":"2025-12-24T11:32:31.756Z","avatar_url":"https://github.com/mikavilpas.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🧪 A terminal test environment and development playground 🛝\n\n[![NPM Version](https://img.shields.io/npm/v/%40tui-sandbox%2Flibrary?logo=npm)](https://www.npmjs.com/package/@tui-sandbox/library)\n![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript\u0026logoColor=fff)\n![Neovim](https://img.shields.io/badge/Neovim-57A143?logo=neovim\u0026logoColor=fff)\n\ntui-sandbox is a framework for using the [cypress](https://www.cypress.io/) browser testing tool to run tests against\nterminal applications.\n\n![example of tui-sandbox being used in [yazi.nvim](https://github.com/mikavilpas/yazi.nvim) tests](documentation/images/yazi-example.webp)\n\n\u003e ☝🏻 example of tui-sandbox running Neovim with [yazi.nvim](https://github.com/mikavilpas/yazi.nvim). The yazi.nvim\n\u003e Neovim plugin shows the terminal file manager [yazi](https://github.com/sxyazi/yazi/) in a floating window inside\n\u003e Neovim, and tests their full integration exactly as a user interacts with them.\n\n## The problems tui-sandbox solves\n\nModern terminal applications are complex. They often depend on external programs as well as the network and filesystem.\nThe development ecosystem is also diverse, spanning many different toolchains.\n\nAs a developer, it is difficult to\n\n1. Ensure that all contributors have the same development environment\n2. Write tests that are reliable, easy to maintain, and easily understood\n\ntui-sandbox can solve these issues:\n\n### Develop terminal applications in a live environment\n\nThe preview is fully interactive. You can use your application exactly as you would normally, including mouse clicks.\nWhen you update your test, the tests automatically rerun with the latest changes.\n\nYou can also isolate the development and testing from your own config\n\n- your own development setup is kept separate from the test environment\n- each test has its own instance of the application\n- each test has its own mini directory structure. This makes the tests more maintainable and discoverable.\n  - The directory structure is also available as a TypeScript type, so you get completions and type errors in your\n    tests.\n\n![example of a type-safe test environment in tui-sandbox](documentation/images/type-safe-test-environment-example.webp)\n\n\u003e ☝🏻 Neovim using the type-safe test environment provided by tui-sandbox. The language server offers completions for the\n\u003e available file paths along with some metadata.\n\n### Write and run integration tests for terminal applications\n\nUsing [cypress](https://www.cypress.io/) gives us great features for free, such as:\n\n- automatically waiting for asynchronous things to happen\n- make assertions on many things\n  - test the terminal colors that are visible\n  - images might work too, but I haven't tried them yet 😄\n  - emoji are supported 👍🏻\n- time travel debugging\n- access to screenshots and videos of the test run in case it fails\n- type safety with TypeScript\n\n## Limitations\n\nThe main limitation is that tui-sandbox is much slower for running tests than a unit testing tool. It trades performance\nfor the ability to run tests in a live environment (giving very strong guarantees that the tests are valid).\n\nFor example, it takes 70 seconds to run 40 test cases in yazi.nvim (1.75s per test). In contrast, it takes 0.21 seconds\nto run 110 unit tests in the same project (0.002s per test).\n\n_Note that this is true for any unit/integration test comparison in general, so I recommend using both._\n\n## Getting started\n\nEven though it's being used in a nontrivial project, this framework is not very mature yet. If you are interested in\nusing it, please reach out to me via github issues. I would love to help.\n\nExample projects that use tui-sandbox:\n\n- [yazi.nvim](https://github.com/mikavilpas/yazi.nvim): Neovim plugin for file manager integration\n- [blink-ripgrep.nvim](https://github.com/mikavilpas/blink-ripgrep.nvim): Neovim plugin for\n  [ripgrep](https://github.com/BurntSushi/ripgrep) search results\n- [tsugit.nvim](https://github.com/mikavilpas/tsugit.nvim): Neovim plugin for superfast lazygit integration\n- [mikavilpas/dotfiles](https://github.com/mikavilpas/dotfiles): My personal dotfiles. Some custom TUI application\n  integrations are end-to-end tested because \"why not\" 🙂\n\n### Configuration\n\nTo configure the test environment, create a `tui-sandbox.config.ts` file in the root of your project with the following\ncontents:\n\n```ts\nimport { createDefaultConfig } from \"@tui-sandbox/library/dist/src/server/config.js\"\nimport type { TestServerConfig } from \"@tui-sandbox/library/dist/src/server/index.js\"\n\nexport const config: TestServerConfig = createDefaultConfig(process.cwd(), process.env)\n// add customizations here\nconfig.port = 5174\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikavilpas%2Ftui-sandbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmikavilpas%2Ftui-sandbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikavilpas%2Ftui-sandbox/lists"}