Healthchecking in Neovim

I like to use a few text editor plugins for finnicky things like “smart” code completion. These plugins often rely on some assumptions about the state of the computer outside of the editor: they might need a utility program installed (such as rls), or a configuration file to exist in a certain location, or a certain environment variable to be set.

When the computer’s state is misconfigured, editor plugins may fail. Their failure may be catastrophic or rather subtle. System upgrades and changes irregularly trigger such problems, breaking editor plugins unexpectedly, and forcing the user to troubleshoot.

Neovim’s :checkhealth command is a big help. The editor and its plugins can define certain tests, called “health checks”, which examine the user’s environment for programs, configuration files, and the like. When each test succeeds or fails, its results are logged to a window for the user to read.

A failed health check represents a failed expectation about the development environment. It might also spell out the logic used by the health check to determine that the expectation failed.

For example, suppose you decide to try out Neovim’s python2 integration. So you read the help file and type in one of the examples, but are greeted with an error message.

:py print(sys.version)
E319: No "python" provider found.  Run ":checkhealth provider"

You execute that command, which makes Neovim run health checks for its “provider” components.

Neovim’s Python 2 provider is in a degraded state. Apparently, none of the python2 interpreters that were found could import the neovim module. Like the message suggests, you read :help provider-python.

...
- For Python 2 plugins, make sure Python 2.7 is available in your $PATH, then
  install the package systemwide:
    sudo pip2 install --upgrade pynvim
  or for the current user:
    pip2 install --user --upgrade pynvim
...

You try that pip2 command in another terminal, and then run :checkhealth provider again.

All looks good, so you try the :py command again:

:py print(sys.version)
2.7.16 (default, Apr 12 2019, 15:32:40)
[GCC 4.2.1 Compatible Apple LLVM 10.0.1 (clang-1001.0.46.3)]
Press ENTER or type command to continue

It works! Now you can get your Python on in the editor.

I think what makes this experience so nice is that this health check plainly lists three key sets of facts: the preconditions for the system to work correctly; the system’s current status with respect to those preconditions; and the logic used to determine that status. The plugin is capable of diagnosing its own issues and explaining the problem in words. This is a massive improvement over, say, making sense of a stack trace in what’s likely someone else’s code.

For more on health checks, see Neovim’s documentation, or :help pi_health.