Nvim Headless

Headless Neovim for codediff

The one rule

Not "headless can't do it" — "synchronous code can't observe deferred events."

Specs run synchronously inside -c "run_and_exit(spec)". The main loop never regains control, so events that fire from normal_check() — WinScrolled, WinResized — are never dispatched. This is identical with or without a UI.

What works

Everything data-level:

• buffer read/write, nvim_buf_get_lines / set_lines
• extmarks with details=true: highlights, virt_lines, signs
• nvim_get_hl (resolved colors)
• window splits, layout, nvim_tabpage_list_wins
• cursor, winsaveview (topline, topfill, leftcol)
• topfill accounting through virt_lines blocks
• folds (foldclosed, zf, zo)
• immediate autocmds: BufEnter, WinEnter, CursorMoved, TabNew, …
• vim.system + vim.wait (async child processes)
• vim.uv timers under vim.wait
• keymaps via feedkeys with "x" (execute immediately) flag
• treesitter parsers and queries
• git operations via tests/helpers (create_temp_git_repo, git_cmd)

What needs a workaround

WinScrolled and WinResized — fire them manually after scrolling:

vim.cmd("normal! 20\5") -- 20x <C-e>
vim.api.nvim_exec_autocmds("WinScrolled", {})

This is what existing specs already do.

What is not possible

• Rendered screen content (which character is at row/col, its color). Neovim's own test suite solves this by spawning a child nvim --embed and attaching a fake UI over RPC — a different architecture from ours.
• UIEnter never fires. Plugins that lazy-load on UIEnter (e.g. snacks.nvim) must be initialized manually with .enable() or equivalent.

Driving styles

For a defer_fn chain (e.g. reproducing animation conflicts):

local co = coroutine.create(function()
  -- step 1
  coroutine.yield(200) -- ms to wait before next step
  -- step 2
end)
local function resume()
  local ok, delay = coroutine.resume(co)
  if ok and coroutine.status(co) ~= "dead" then
    vim.defer_fn(resume, delay or 50)
  end
end
vim.defer_fn(resume, 100)

Traps

• helpers.wait_for_diff_ready() captures tabpage at call time. :CodeDiff file <rev> creates the tab asynchronously, so calling it immediately polls the wrong tab. Use wait_for_new_tab first, or poll get_current_tabpage() inside the condition.

• Default terminal size is 24×80 (window height 22). Set vim.o.lines explicitly when assertions depend on height.

• vim.wait does NOT pump the normal-mode loop. It processes libuv callbacks (timers, child process I/O) but not deferred display events. Do not expect WinScrolled to fire inside vim.wait.

Entry points