vim-ultest

Deprecation Warning

This repo is no longer being actively worked on. I've moved my efforts into Neotest. If you use NeoVim then I'd suggest switching to that as it will cover all features of vim-ultest. If you're a Vim user, this repo will still work and I will accept PRs but will no longer be adding features.

1. Introduction
2. Features
3. Installation
4. Usage
   1. Configuration
   2. Commands
   3. Plug mappings
5. Debugging
6. Feedback

Introduction

The ultimate testing plugin for NeoVim

Running tests should be as quick and painless as possible. vim-test is a very powerful and extensive testing plugin, but it can be cumbersome to configure and lacks some features to make it feel like an integrated piece of your editor.

Rather than replacing vim-test altogether, vim-ultest (in name and practice) builds upon vim-test to make it even better while maintaining the ability to use your existing configuration. If you're already using vim-test then switching to vim-ultest is as easy as installing and... well, that's pretty much it.

The goal behind vim-ultest is to make running tests as seamless as possible.

Features

• Run tests and view results individually
  • Test result markers using signs or virtual text
  • Failure outputs in a floating window
  • Key mappings to jump between failed tests
  • Stop long running tests

• Attach to running processes to debug
  • Currently experimental so please report issues!
  • Uses python's readline library to pass input

• Summary window
  • Highlight tests based on current status (running, succeeded, failed)
  • Show test output
  • View all tests currently found in all test files
  • Run tests with key binding

• Multithreaded (not just asynchronous) to prevent blocking

• Use existing vim-test configuration

• Customisable

More features are being worked on. If you have any ideas, feel free to open an issue!

Installation

Requirements:

All users:

• Python >= 3.7
• Pynvim library
• vim-test

Vim only:

• nvim-yarp
• vim-hug-neovim-rpc

Note: Vim support is maintained with a best effort. Due to the differences between Vim and NeoVim and their RPC libraries, it is inevitable that bugs will occur in one and not the other. I primarily use NeoVim so I will catch issues in it myself. Please file bug reports for Vim if you find them!

NeoVim >= 0.5 is currently supported.

vim-ultest can be installed as usual with your favourite plugin manager. Note: NeoVim users must run :UpdateRemotePlugins after install if they don't use a plugin manager that already does.

dein:

" Vim Only
call dein#add("roxma/nvim-yarp")
call dein#add("roxma/vim-hug-neovim-rpc")

call dein#add("vim-test/vim-test")
call dein#add("rcarriga/vim-ultest")

vim-plug

" Vim Only
Plug 'roxma/nvim-yarp'
Plug 'roxma/vim-hug-neovim-rpc'

Plug 'vim-test/vim-test'
Plug 'rcarriga/vim-ultest', { 'do': ':UpdateRemotePlugins' }

packer.nvim

use { "rcarriga/vim-ultest", requires = {"vim-test/vim-test"}, run = ":UpdateRemotePlugins" }

Usage

Configuration

:help ultest-config

Any vim-test configuration should carry over to vim-ultest. See the vim-test documentation on further details for changing test runner and options. If you have compatibility problems please raise an issue.

One change you will notice is that test output is not coloured. This is due to the way the command is run. To work around this you can simply tell your test runner to always output with colour. For example

let test#python#pytest#options = "--color=yes"

let test#javascript#jest#options = "--color=always"

Alternatively if you are using a neovim >= 0.5 you can enable PTY usage which makes the process think it is in an interactive session

let g:ultest_use_pty = 1

Because Ultest runs processes in an interactive way, test runners may wait for input or run in "watch" mode. To avoid this you have to pass a flag to your runner to disable this.

For example with react-scripts

let test#javascript#reactscripts#options = "--watchAll=false"

Note: The window to show results relies on the 'updatetime' setting which by default is 4 seconds. A longer 'updatetime' will mean the window takes longer to show automatically but a shorter time means (Neo)Vim will write to disk much more often which can degrade SSDs over time and cause slowdowns on HDDs.

Commands

:help ultest-commands

For example to run the nearest test every time a file is written:

augroup UltestRunner
    au!
    au BufWritePost * UltestNearest
augroup END

Need user contributions

The Ultest command runs all tests in a file. For some test runners the plugin can parse the output of the runner to get results so that they can all be run as a single process. For other runners the tests all have to be run as inidividual processes, which can have a significant performance impact. Please check the wiki to see if your runner is supported. If it is not please open an issue with example output and I can add support for it!

Plug mappings

:help ultest-mappings

For example to be able to jump between failures in a test file:

nmap ]t <Plug>(ultest-next-fail)
nmap [t <Plug>(ultest-prev-fail)

For configuration options and more documentation see :h ultest

Debugging

:help ultest-debugging

Debugging with nvim-dap is supported but some user configuration is required. See the debugging recipes for some working configurations. If you do not see one for your runner/language, please submit a change to the wiki so others can use it too!

Feedback

Feel free to open an issue for bug reports, feature requests or suggestions. I will try address them as soon as I can!