nvim-test - SKILL.md Agent Skill

name: nvim-test description: > Execute tests and diagnose failures for this Neovim plugin. Use when the user says "run tests", "run the suite", or asks to execute the test suite (full, single file, or offline). Also use when the user pastes test error output, asks what a test failure means, or needs help fixing a broken test. The test stack is mini.test + luassert with _spec.lua files. Do not trigger for writing tests, learning test APIs, setting up testing from scratch, or non-Neovim tools.

Running Neovim Plugin Tests

This skill covers running tests and diagnosing failures. For how to write tests, see the nvim-plugin skill's references/TESTS.md.

Discover the project's test runner

Before running tests, check how the project invokes the test suite. Look for:

scripts/test — a shell script (e.g., nvim -l tests/minit.lua --minitest "$@")
Makefile — a test target (e.g., nvim -l tests/minit.lua --minitest $(FILE))
If neither exists, run directly: nvim -l tests/minit.lua --minitest

Running tests

Full test suite

# Via Makefile (preferred if available)
make test

# Via scripts
./scripts/test

# Direct
nvim -l tests/minit.lua --minitest

Single test file

# Via Makefile (if available)
make test-one MODULE=base

# Direct — pass the file path
nvim -l tests/minit.lua --minitest tests/base_spec.lua

Running offline (no network)

Set LAZY_OFFLINE=1 to skip plugin updates. Useful when dependencies are already installed:

LAZY_OFFLINE=1 nvim -l tests/minit.lua --minitest

With verbose output

nvim -l tests/minit.lua --minitest -v tests/base_spec.lua

Reading test output

mini.test reports in headless mode:

Green o = passed test case
Red x = failed test case (with error details below)
Summary line shows total cases and groups
Failures are listed at the end with file, line, and error message

Example output

test_base_spec.lua
  describe "setup"
    ✓ it "creates side effects"
    ✓ it "validates config"
  describe "hello"
    ✗ it "returns greeting"
      tests/base_spec.lua:42: Expected:
      "Hello World"
      Got:
      "Hello John Doe"
      stack traceback:
        tests/base_spec.lua:42: in function <tests/base_spec.lua:41>

Diagnosing failures

Read the error message — luassert shows expected vs actual values
Check the line number — it points to the assertion that failed
Check the stack trace — it shows the call chain leading to the failure
Reproduce in isolation — run just the failing file with --minitest
Check for state leaks — if a test passes alone but fails with the suite, something in a previous test didn't clean up (missing after_each)

Common failure patterns

Error	Cause	Fix
`Expected: X, Got: Y`	Wrong return value	Check the function logic
`attempt to index nil value`	Module not loaded or config not set	Call `setup()` in `before_each`
`Vim:E516: buffer is already loaded`	Buffer cleanup missing	Add `after_each` with `pcall(vim.api.nvim_buf_delete, ...)`
`test passes alone, fails in suite`	State leak between tests	Check `after_each` cleanup, restore stubs
`PENDING: ...`	Conditional test skipped	Install missing dependency or ignore
`module 'luassert' not found`	Dependencies not installed	Run without `LAZY_OFFLINE=1` once

Existing project files to reference

Before running tests, check if the project already has:

tests/minit.lua — the test harness bootstrap. Do not recreate this file.
scripts/test — the shell script that invokes the test runner. Use it.
Makefile — may have test, test-one, check targets.
Existing *_spec.lua files — read them to understand the test structure.

Test environment details

Headless Neovim — nvim -l runs in headless mode. No terminal, no real UI.
--minitest flag triggers discovery — mini.test finds tests/**/*_spec.lua files automatically.
Package path includes tests/ — lazy.minit adds tests/?.lua to package.path.
luassert is auto-loaded — via hererocks, configured by lazy.minit.