Neotest

A framework for interacting with tests within NeoVim.

This is early stage software.

• Introduction
• Installation
  • Supported Runners
• Configuration
• Usage
• Consumers
  • Output Window
  • Summary Window
  • Diagnostic Messages
  • Status Signs
• Strategies
• Writing Adapters
  • Parsing tests in a directory
  • Collecting results

Introduction

See :h neotest for details on neotest is designed and how to interact with it programmatically.

Installation

Neotest uses nvim-nio and plenary.nvim.

Most adapters will also require nvim-treesitter.

Neotest uses the CursorHold event. This uses the updatetime setting which is by default very high, and lowering this can lead to excessive writes to disk. It's recommended to use https://github.com/antoinemadec/FixCursorHold.nvim which allows detaching updatetime from the frequency of the CursorHold event. The repo claims it is no longer needed but it is still recommended (See this issue)

Install with your favourite package manager alongside nvim-dap

dein:

call dein#add("nvim-lua/plenary.nvim")
call dein#add("antoinemadec/FixCursorHold.nvim")
call dein#add("nvim-treesitter/nvim-treesitter")
call dein#add("nvim-neotest/nvim-nio")
call dein#add("nvim-neotest/neotest")

vim-plug

Plug 'nvim-lua/plenary.nvim'
Plug 'antoinemadec/FixCursorHold.nvim'
Plug 'nvim-treesitter/nvim-treesitter'
Plug 'nvim-neotest/nvim-nio'
Plug 'nvim-neotest/neotest'

packer.nvim

use {
  "nvim-neotest/neotest",
  requires = {
    "nvim-neotest/nvim-nio",
    "nvim-lua/plenary.nvim",
    "antoinemadec/FixCursorHold.nvim",
    "nvim-treesitter/nvim-treesitter"
  }
}

lazy.nvim

{
  "nvim-neotest/neotest",
  dependencies = {
    "nvim-neotest/nvim-nio",
    "nvim-lua/plenary.nvim",
    "antoinemadec/FixCursorHold.nvim",
    "nvim-treesitter/nvim-treesitter"
  }
}

To get started you will also need to install an adapter for your test runner. See the adapter's documentation for their specific setup instructions.

Supported Runners

| Test Runner | Adapter | | :-------------------- | :-------------------------------------------------------------------------------------------------------------------------: | | pytest | neotest-python | | python-unittest | neotest-python | | plenary | neotest-plenary | | go | neotest-go <br> neotest-golang | | jest | neotest-jest | | mocha | neotest-mocha | | vitest | neotest-vitest | | bun | neotest-bun | | stenciljs | neotest-stenciljs | | playwright | neotest-playwright | | rspec | neotest-rspec | | minitest | neotest-minitest | | ruby, minitest | neotest-ruby-minitest | | dart, flutter | neotest-dart | | testthat | neotest-testthat | | phpunit | neotest-phpunit | | pest | neotest-pest | | rust (treesitter) | neotest-rust | | rust (LSP) | rustaceanvim | | elixir | neotest-elixir | | dotnet (treesitter) | neotest-dotnet | | dotnet (vstest) | neotest-vstest | | scala | neotest-scala | | haskell | neotest-haskell | | deno | neotest-deno | | java | neotest-java | | kotlin | neotest-kotlin | | foundry | neotest-foundry | | zig | neotest-zig | | c++ (google test) | neotest-gtest | | c++ (ctest) | neotest-ctest | | gradle | neotest-gradle | | bazel | neotest-bazel | | bash | neotest-bash | | hardhat | neotest-hardhat | | swift (Swift Testing) | neotest-swift-testing | | busted | neotest-busted | | nix-unit | neotest-nix-unit |

For any runner without an adapter you can use neotest-vim-test which supports any runner that vim-test supports. The vim-test adapter does not support some of the more advanced features such as error locations or per-test output. If you're using the vim-test adapter then install vim-test too.

Configuration

Provide your adapters and other config to the setup function.

require("neotest").setup({
  adapters = {
    require("neotest-python")({
      dap = { justMyCode = false },
    }),
    require("neotest-plenary"),
    require("neotest-vim-test")({
      ignore_file_types = { "python", "vim", "lua" },
    }),
  },
})

See :h neotest.Config for configuration options and :h neotest.setup() for the default values.

It is highly recommended to use lazydev.nvim to enable type checking for neotest to get type checking, documenta