test-samurai.nvim

A Neovim plugin to run tests across multiple languages and frameworks with a unified UX and an extensible runner architecture.

Requirements

Neovim >= 0.11.4
Lua
Test runners are provided as separate Lua modules

Installation (Lazy.nvim)

Use the GitHub repository. The example below shows how to add the Go runner as a dependency and configure it in setup():

{
  "m13r/test-samurai.nvim",
  dependencies = {
    "m13r/test-samurai-go-runner",
    -- furthur samurai runners
  },
  config = function()
    require("test-samurai").setup({
      runner_modules = {
        "test-samurai-go-runner",
        -- furthur samurai runners
      },
    })
  end,
}

Configuration

Runner modules (required)

test-samurai does not ship with any built-in runners. You must explicitly configure the runners you want to use:

require("test-samurai").setup({
  runner_modules = {
    "my-runners.go",
    "my-runners.js",
  },
})

If no runner matches the current test file, test-samurai will show:

[test-samurai] no runner installed for this kind of test

Commands and keymaps

TSamNearest -> <leader>tn
TSamFile -> <leader>tf
TSamAll -> <leader>ta
TSamLast -> <leader>tl
TSamFailedOnly -> <leader>te
TSamShowOutput -> <leader>to
Help: :help test-samurai

Additional keymaps:

<leader>qn -> close the testing floats and jump to the first quickfix entry
<leader>nf -> jump to the next [ FAIL ] entry in the Test-Listing-Float (wraps to the first)
<leader>pf -> jump to the previous [ FAIL ] entry in the Test-Listing-Float (wraps to the last)
<leader>sf -> filter the listing to [ FAIL ] - ... entries
<leader>ss -> filter the listing to [ SKIP ] - ... entries
<leader>sa -> clear the listing filter and show all entries
? -> show help with TSam commands and standard keymaps in the Detail-Float

Output UI

Output is shown in a floating container called Testing-Float.
The Test-Listing-Float is the left subwindow and shows the test result list.
The Detail-Float is the right subwindow and shows detailed output for a selected test.
After TSamNearest, TSamFile, TSamAll, TSamFailedOnly, etc., the UI opens in listing mode (only Test-Listing-Float visible).
Press <cr> on a [ FAIL ] ... line in the listing to open/update the Detail-Float as a 20/80 split (left 20% listing, right 80% detail).
ANSI color translation is only applied in the Detail-Float; the Test-Listing-Float shows raw text without ANSI translation.
<esc><esc> hides the floating window; TSamShowOutput reopens it.

Runner architecture

Runners are standalone Lua modules. All runner modules are expected to implement the full interface so every command and keymap works. All functions are required (including the previously optional ones) and listing output must be streamed. Required functions:

is_test_file
find_nearest
build_command
build_file_command
build_all_command
build_failed_command
parse_results
output_parser (must stream listing output via on_line)
parse_test_output
collect_failed_locations

No runner for your environment exists? No problem: use runners-agents.md to guide an AI-assisted runner implementation tailored to your stack.

Known runners

Development

Runner development guidelines, including required data formats for keymaps, tests (run_test.sh), Gitea CI (Neovim AppImage on ARM runners), and framework-agnostic best practices (naming conventions, TSamNearest priority, reporter payloads, failed-only behavior), are documented in runner-agents.md.

Tests are written with plenary.nvim / busted. Mocks and stubs are allowed.

Run tests:

bash run_test.sh

4.1 KiB Raw Blame History