mark listing entry when details are visible

README.md

@@ -63,12 +63,17 @@ If no runner matches the current test file, test-samurai will show:
 
 Additional keymaps:
 
+- Listing navigation:
+  - `<leader>fn` -> [F]ind [N]ext failed test in listing (wraps to the first, opens Detail-Float, works in Detail-Float)
+  - `<leader>fp` -> [F]ind [P]revious failed test in listing (wraps to the last, opens Detail-Float, works in Detail-Float)
+  - `<leader>ff` -> [F]ind [F]irst list entry (opens Detail-Float, works in Detail-Float)
+  - `<leader>o` -> jump to the test location
   - `<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)
+- Listing filters:
   - `<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
+- Listing actions:
   - `<leader>tt` -> run the test under the cursor in the listing
   - `<leader>cb` -> breaks test-command onto multiple lines (clears search highlight)
   - `<leader>cj` -> joins test-command onto single line
@@ -84,8 +89,9 @@ Before running any test command, test-samurai runs `:wall` to save all buffers.
 - 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.
+- `<esc><esc>` hides the floating window and restores the cursor position; `TSamShowOutput` reopens it.
 - If no output is captured for a test, the **Detail-Float** shows `No output captured`.
+- The active listing entry is highlighted while the **Detail-Float** is visible.
 - Summary lines (`TOTAL`/`DURATION`) are appended in the listing output, including `TSamLast`.
 
 ## Runner architecture

doc/test-samurai.txt

@@ -51,23 +51,29 @@ QUICK-HELP & FLOATS                                   *test-samurai-quickhelp*
 In the Testing-Float, press ? to open the quick-help in the Detail-Float.
 
 Additional keymaps:
+Listing navigation:
+  <leader>fn    [F]ind [N]ext failed test in listing (opens Detail-Float; works in Detail-Float)
+  <leader>fp    [F]ind [P]revious failed test in listing (opens Detail-Float; works in Detail-Float)
+  <leader>ff    [F]ind [F]irst list entry (opens Detail-Float; works in Detail-Float)
+  <leader>o     Jump to test location
   <leader>qn    Close floats + jump to the first quickfix entry
-  <leader>nf    Next [ FAIL ] in listing
-  <leader>pf    Previous [ FAIL ] in listing
+Listing filters:
   <leader>sf    Filter listing to [ FAIL ] only
   <leader>ss    Filter listing to [ SKIP ] only
   <leader>sa    Show all listing entries (clear filter)
+Listing actions:
   <leader>tt    Run the test under the cursor in the listing
   <leader>cb    breaks test-command onto multiple lines (clears search highlight)
   <leader>cj    joins test-command onto single line
-  <leader>o     Jump to test location
+Testing-Float:
   <leader>z     Toggle Detail-Float full width
   <C-l>         Focus Detail-Float (press l again for full)
   <C-h>         Focus Test-Listing-Float
-  <esc><esc>    Close Testing-Float
+  <esc><esc>    Close Testing-Float and restore cursor
   <C-c>         Close Detail-Float (when focused)
 
 Notes:
+  Active listing entry is highlighted while the Detail-Float is visible.
   Buffers are saved via :wall before every test run.
 
 

lua/test-samurai/core.lua

@@ -23,8 +23,12 @@ local state = {
   detail_win = nil,
   detail_opening = false,
   detail_full = false,
+  trigger_win = nil,
+  trigger_buf = nil,
+  trigger_cursor = nil,
   listing_unfiltered_lines = nil,
   listing_filtered_kind = nil,
+  detail_line = nil,
   hardtime_refcount = 0,
   hardtime_was_enabled = false,
   autocmds_set = false,
@@ -33,6 +37,8 @@ local state = {
 local summary_ns = vim.api.nvim_create_namespace("TestSamuraiSummary")
 local result_ns = vim.api.nvim_create_namespace("TestSamuraiResult")
 local detail_ns = vim.api.nvim_create_namespace("TestSamuraiDetailAnsi")
+local help_ns = vim.api.nvim_create_namespace("TestSamuraiHelp")
+local listing_sel_ns = vim.api.nvim_create_namespace("TestSamuraiListingSelection")
 local apply_border_kind
 local close_container
 local restore_listing_full
@@ -52,7 +58,7 @@ local function help_lines()
   return {
     "Test-Samurai Help",
     "",
-    "TSam Commands:",
+    "TSam commands:",
     "  TSamNearest    <leader>tn",
     "  TSamFile       <leader>tf",
     "  TSamAll        <leader>ta",
@@ -60,28 +66,33 @@ local function help_lines()
     "  TSamFailedOnly <leader>te",
     "  TSamShowOutput <leader>to",
     "",
-    "Standard Keymaps:",
+    "Listing navigation:",
+    "  <leader>fn  [F]ind [N]ext failed test in listing (opens Detail-Float; works in Detail-Float)",
+    "  <leader>fp  [F]ind [P]revious failed test in listing (opens Detail-Float; works in Detail-Float)",
+    "  <leader>ff  [F]ind [F]irst list entry (opens Detail-Float; works in Detail-Float)",
+    "  <leader>o   Jump to test location",
     "  <leader>qn  Close floats + jump to first quickfix entry",
-    "  <leader>nf  Next [ FAIL ] in listing",
-    "  <leader>pf  Previous [ FAIL ] in listing",
+    "",
+    "Listing filters:",
     "  <leader>sf  Filter listing to [ FAIL ] only",
     "  <leader>ss  Filter listing to [ SKIP ] only",
     "  <leader>sa  Show all listing entries (clear filter)",
+    "",
+    "Listing actions:",
     "  <leader>tt  Run the test under the cursor",
+    "  <leader>cb  breaks test-command onto multiple lines (clears search highlight)",
+    "  <leader>cj  joins test-command onto single line",
     "",
     "Testing-Float (Listing):",
     "  <cr>         Open Detail-Float for selected test",
-    "  <esc><esc>   Close Testing-Float",
+    "  <esc><esc>   Close Testing-Float and restore cursor",
     "  <C-l>        Focus Detail-Float (press l again for full)",
     "  <C-h>        Focus Test-Listing-Float",
     "  <leader>z    Toggle Detail-Float full width",
-    "  <leader>o    Jump to test location",
-    "  <leader>cb   breaks test-command onto multiple lines (clears search highlight)",
-    "  <leader>cj   joins test-command onto single line",
     "  ?            Show this help",
     "",
     "Testing-Float (Detail):",
-    "  <esc><esc>   Close Testing-Float",
+    "  <esc><esc>   Close Testing-Float and restore cursor",
     "  <C-h>        Focus Test-Listing-Float",
     "  <C-w>h       Focus Test-Listing-Float",
     "  <C-l>        Focus Detail-Float",
@@ -91,6 +102,7 @@ local function help_lines()
     "",
     "Notes:",
     "  No output captured -> shows placeholder text",
+    "  Active listing entry is highlighted while Detail-Float is visible",
     "  Buffers are saved via :wall before every test run",
   }
 end
@@ -140,6 +152,7 @@ local function apply_listing_lines(buf, lines)
   vim.api.nvim_buf_set_lines(buf, 0, -1, false, lines)
   vim.api.nvim_buf_clear_namespace(buf, result_ns, 0, -1)
   vim.api.nvim_buf_clear_namespace(buf, summary_ns, 0, -1)
+  vim.api.nvim_buf_clear_namespace(buf, listing_sel_ns, 0, -1)
   apply_result_highlights(buf, 0, lines)
   apply_summary_highlights(buf, 0, lines)
   rebuild_result_line_map(lines)
@@ -269,11 +282,11 @@ local function jump_listing_fail(direction)
   local win = vim.api.nvim_get_current_win()
   local buf = vim.api.nvim_get_current_buf()
   if not (buf and vim.api.nvim_buf_is_valid(buf)) then
-    return
+    return nil
   end
   local total = vim.api.nvim_buf_line_count(buf)
   if total == 0 then
-    return
+    return nil
   end
   local lines = vim.api.nvim_buf_get_lines(buf, 0, -1, false)
   local cursor = vim.api.nvim_win_get_cursor(win)
@@ -325,6 +338,76 @@ local function jump_listing_fail(direction)
   if target then
     vim.api.nvim_win_set_cursor(win, { target, 0 })
   end
+  return target
+end
+
+local function jump_to_first_listing_entry()
+  local win = vim.api.nvim_get_current_win()
+  local buf = vim.api.nvim_get_current_buf()
+  if not (buf and vim.api.nvim_buf_is_valid(buf)) then
+    return nil
+  end
+  local total = vim.api.nvim_buf_line_count(buf)
+  if total == 0 then
+    return nil
+  end
+  local lines = vim.api.nvim_buf_get_lines(buf, 0, -1, false)
+  for i = 1, total do
+    if lines[i] and lines[i]:match("^%[ %u+ %] %- ") then
+      vim.api.nvim_win_set_cursor(win, { i, 0 })
+      return i
+    end
+  end
+  return nil
+end
+
+local function jump_listing_and_open(kind)
+  local current_win = vim.api.nvim_get_current_win()
+  local listing_win = state.last_win
+  if listing_win and vim.api.nvim_win_is_valid(listing_win) then
+    vim.api.nvim_set_current_win(listing_win)
+  else
+    listing_win = current_win
+  end
+  local target = nil
+  if kind == "next" then
+    target = jump_listing_fail("next")
+  elseif kind == "prev" then
+    target = jump_listing_fail("prev")
+  elseif kind == "first" then
+    target = jump_to_first_listing_entry()
+  end
+  if target then
+    M.open_test_output_at_cursor()
+    return
+  end
+  if current_win and vim.api.nvim_win_is_valid(current_win) then
+    vim.api.nvim_set_current_win(current_win)
+  end
+end
+
+local function clear_listing_selection()
+  if state.last_buf and vim.api.nvim_buf_is_valid(state.last_buf) then
+    vim.api.nvim_buf_clear_namespace(state.last_buf, listing_sel_ns, 0, -1)
+  end
+  state.detail_line = nil
+end
+
+local function apply_listing_selection(line)
+  if not (state.last_buf and vim.api.nvim_buf_is_valid(state.last_buf)) then
+    return
+  end
+  vim.api.nvim_buf_clear_namespace(state.last_buf, listing_sel_ns, 0, -1)
+  if not line then
+    state.detail_line = nil
+    return
+  end
+  local total = vim.api.nvim_buf_line_count(state.last_buf)
+  if line < 1 or line > total then
+    return
+  end
+  vim.api.nvim_buf_add_highlight(state.last_buf, listing_sel_ns, "TestSamuraiListingActive", line - 1, 0, -1)
+  state.detail_line = line
 end
 
 local function find_normal_window()
@@ -337,6 +420,54 @@ local function find_normal_window()
   return nil
 end
 
+local function capture_trigger_location()
+  local win = vim.api.nvim_get_current_win()
+  local cfg = vim.api.nvim_win_get_config(win)
+  if cfg.relative ~= "" then
+    win = find_normal_window()
+  end
+  if not (win and vim.api.nvim_win_is_valid(win)) then
+    return
+  end
+  local buf = vim.api.nvim_win_get_buf(win)
+  if not (buf and vim.api.nvim_buf_is_valid(buf)) then
+    return
+  end
+  local cursor = vim.api.nvim_win_get_cursor(win)
+  state.trigger_win = win
+  state.trigger_buf = buf
+  state.trigger_cursor = { cursor[1], cursor[2] }
+end
+
+local function restore_trigger_location()
+  local buf = state.trigger_buf
+  local cursor = state.trigger_cursor
+  if not (buf and vim.api.nvim_buf_is_valid(buf)) then
+    return
+  end
+  local target_win = nil
+  if state.trigger_win and vim.api.nvim_win_is_valid(state.trigger_win) then
+    local cfg = vim.api.nvim_win_get_config(state.trigger_win)
+    if cfg.relative == "" then
+      target_win = state.trigger_win
+    end
+  end
+  if not target_win then
+    target_win = find_normal_window()
+  end
+  if not (target_win and vim.api.nvim_win_is_valid(target_win)) then
+    return
+  end
+  vim.api.nvim_set_current_win(target_win)
+  vim.api.nvim_win_set_buf(target_win, buf)
+  if cursor then
+    pcall(vim.api.nvim_win_set_cursor, target_win, cursor)
+  end
+  state.trigger_win = nil
+  state.trigger_buf = nil
+  state.trigger_cursor = nil
+end
+
 local function jump_to_listing_test()
   local cursor = vim.api.nvim_win_get_cursor(0)
   local line = cursor[1]
@@ -431,6 +562,7 @@ local function setup_summary_highlights()
   pcall(vim.api.nvim_set_hl, 0, "TestSamuraiResultSkip", { fg = skip_fg })
   pcall(vim.api.nvim_set_hl, 0, "TestSamuraiBorderPass", { fg = pass_fg, bold = true })
   pcall(vim.api.nvim_set_hl, 0, "TestSamuraiBorderFail", { fg = fail_fg, bold = true })
+  pcall(vim.api.nvim_set_hl, 0, "TestSamuraiListingActive", { link = "Visual" })
 end
 
 local function load_runners()
@@ -464,6 +596,7 @@ local function ensure_output_autocmds()
       if state.detail_win and closed == state.detail_win then
         state.detail_win = nil
         restore_listing_full()
+        clear_listing_selection()
         hardtime_restore()
         return
       end
@@ -474,6 +607,7 @@ local function ensure_output_autocmds()
           pcall(vim.api.nvim_win_close, state.detail_win, true)
           state.detail_win = nil
         end
+        clear_listing_selection()
         return
       end
     end,
@@ -641,6 +775,12 @@ close_container = function()
     pcall(vim.api.nvim_win_close, state.last_win, true)
     state.last_win = nil
   end
+  clear_listing_selection()
+end
+
+local function close_container_and_restore()
+  close_container()
+  restore_trigger_location()
 end
 
 jump_to_first_quickfix = function()
@@ -655,6 +795,7 @@ close_detail_float = function()
   if state.detail_win and vim.api.nvim_win_is_valid(state.detail_win) then
     pcall(vim.api.nvim_win_close, state.detail_win, true)
   end
+  clear_listing_selection()
 end
 
 restore_listing_full = function()
@@ -728,6 +869,7 @@ local function apply_split_layout(left_ratio)
 end
 
 local function create_output_win(initial_lines)
+  capture_trigger_location()
   if state.detail_win and vim.api.nvim_win_is_valid(state.detail_win) then
     pcall(vim.api.nvim_win_close, state.detail_win, true)
     state.detail_win = nil
@@ -762,7 +904,7 @@ local function create_output_win(initial_lines)
   hardtime_disable()
 
   vim.keymap.set("n", "<esc><esc>", function()
-    close_container()
+    close_container_and_restore()
   end, { buffer = buf, nowait = true, silent = true })
   vim.keymap.set("n", "<cr>", function()
     M.open_test_output_at_cursor()
@@ -776,12 +918,15 @@ local function create_output_win(initial_lines)
   vim.keymap.set("n", "<leader>z", function()
     M.toggle_detail_full()
   end, { buffer = buf, nowait = true, silent = true })
-  vim.keymap.set("n", "<leader>nf", function()
-    jump_listing_fail("next")
+  vim.keymap.set("n", "<leader>fn", function()
+    jump_listing_and_open("next")
   end, { buffer = buf, nowait = true, silent = true })
-  vim.keymap.set("n", "<leader>pf", function()
-    jump_listing_fail("prev")
+  vim.keymap.set("n", "<leader>fp", function()
+    jump_listing_and_open("prev")
   end, { buffer = buf, nowait = true, silent = true })
+  vim.keymap.set("n", "<leader>ff", function()
+    jump_listing_and_open("first")
+  end, { buffer = buf, nowait = true, silent = true, desc = "[F]ind [F]irst list entry" })
   vim.keymap.set("n", "<leader>cb", function()
     M.listing_break_on_dashes()
   end, { buffer = buf, nowait = true, silent = true })
@@ -832,6 +977,7 @@ local function reopen_output_win()
     state.detail_win = nil
   end
 
+  capture_trigger_location()
   local width, height, row, col = float_geometry()
   state.last_float = { width = width, height = height, row = row, col = col }
 
@@ -847,7 +993,7 @@ local function reopen_output_win()
   hardtime_disable()
 
   vim.keymap.set("n", "<esc><esc>", function()
-    close_container()
+    close_container_and_restore()
   end, { buffer = state.last_buf, nowait = true, silent = true })
   vim.keymap.set("n", "<cr>", function()
     M.open_test_output_at_cursor()
@@ -861,12 +1007,15 @@ local function reopen_output_win()
   vim.keymap.set("n", "<leader>z", function()
     M.toggle_detail_full()
   end, { buffer = state.last_buf, nowait = true, silent = true })
-  vim.keymap.set("n", "<leader>nf", function()
-    jump_listing_fail("next")
+  vim.keymap.set("n", "<leader>fn", function()
+    jump_listing_and_open("next")
   end, { buffer = state.last_buf, nowait = true, silent = true })
-  vim.keymap.set("n", "<leader>pf", function()
-    jump_listing_fail("prev")
+  vim.keymap.set("n", "<leader>fp", function()
+    jump_listing_and_open("prev")
   end, { buffer = state.last_buf, nowait = true, silent = true })
+  vim.keymap.set("n", "<leader>ff", function()
+    jump_listing_and_open("first")
+  end, { buffer = state.last_buf, nowait = true, silent = true, desc = "[F]ind [F]irst list entry" })
   vim.keymap.set("n", "<leader>cb", function()
     M.listing_break_on_dashes()
   end, { buffer = state.last_buf, nowait = true, silent = true })
@@ -1156,6 +1305,18 @@ local function apply_detail_highlights(buf, highlights)
   end
 end
 
+local function apply_help_highlights(buf, lines)
+  if not (buf and vim.api.nvim_buf_is_valid(buf)) then
+    return
+  end
+  vim.api.nvim_buf_clear_namespace(buf, help_ns, 0, -1)
+  for lnum, line in ipairs(lines or {}) do
+    if line:match(":%s*$") then
+      vim.api.nvim_buf_add_highlight(buf, help_ns, "TestSamuraiSummaryPass", lnum - 1, 0, -1)
+    end
+  end
+end
+
 local function parse_go_output_from_raw(output)
   local out = {}
   if not output or output == "" then
@@ -1189,7 +1350,7 @@ local function ensure_detail_buf(lines)
     vim.api.nvim_buf_set_option(buf, "filetype", "test-samurai-output")
     state.detail_buf = buf
     vim.keymap.set("n", "<esc><esc>", function()
-      close_container()
+      close_container_and_restore()
     end, { buffer = buf, nowait = true, silent = true })
     vim.keymap.set("n", "<C-w>h", function()
       M.focus_listing()
@@ -1203,6 +1364,15 @@ local function ensure_detail_buf(lines)
     vim.keymap.set("n", "<leader>z", function()
       M.toggle_detail_full()
     end, { buffer = buf, nowait = true, silent = true })
+    vim.keymap.set("n", "<leader>fn", function()
+      jump_listing_and_open("next")
+    end, { buffer = buf, nowait = true, silent = true })
+    vim.keymap.set("n", "<leader>fp", function()
+      jump_listing_and_open("prev")
+    end, { buffer = buf, nowait = true, silent = true })
+    vim.keymap.set("n", "<leader>ff", function()
+      jump_listing_and_open("first")
+    end, { buffer = buf, nowait = true, silent = true, desc = "[F]ind [F]irst list entry" })
     vim.keymap.set("n", "<C-c>", function()
       close_detail_float()
     end, { buffer = buf, nowait = true, silent = true })
@@ -1216,6 +1386,7 @@ local function ensure_detail_buf(lines)
   end
   local clean_lines, highlights = parse_ansi_lines(normalize_output_lines(lines))
   vim.api.nvim_buf_set_lines(buf, 0, -1, false, clean_lines)
+  vim.api.nvim_buf_clear_namespace(buf, help_ns, 0, -1)
   apply_detail_highlights(buf, highlights)
   return buf
 end
@@ -1334,10 +1505,12 @@ function M.open_test_output_at_cursor()
   end
   if type(output) ~= "table" or #output == 0 then
     open_detail_split({ "", "No output captured" }, "default")
+    apply_listing_selection(line)
     return
   end
   local border_kind = status and status:lower() or nil
   open_detail_split(output, border_kind)
+  apply_listing_selection(line)
 end
 
 function M.show_help()
@@ -1345,7 +1518,10 @@ function M.show_help()
     vim.notify("[test-samurai] No test output window", vim.log.levels.WARN)
     return
   end
-  open_detail_split(help_lines(), "default")
+  local lines = help_lines()
+  open_detail_split(lines, "default")
+  clear_listing_selection()
+  apply_help_highlights(state.detail_buf, lines)
 end
 
 function M.filter_listing_failures()
@@ -2393,6 +2569,10 @@ function M.run_failed_only()
   })
 end
 
+function M.close_output_and_restore()
+  close_container_and_restore()
+end
+
 function M.show_output()
   if not (state.last_buf and vim.api.nvim_buf_is_valid(state.last_buf)) then
     vim.notify("[test-samurai] No previous output", vim.log.levels.WARN)

tests/test_samurai_core_spec.lua

@@ -244,8 +244,16 @@ describe("test-samurai core (no bundled runners)", function()
     local joined = table.concat(lines, "\n")
     assert.is_true(joined:find("TSamNearest", 1, true) ~= nil)
     assert.is_true(joined:find("TSamShowOutput", 1, true) ~= nil)
+    assert.is_true(joined:find("TSam commands:", 1, true) ~= nil)
+    assert.is_true(joined:find("Listing navigation:", 1, true) ~= nil)
+    assert.is_true(joined:find("Listing filters:", 1, true) ~= nil)
+    assert.is_true(joined:find("Listing actions:", 1, true) ~= nil)
     assert.is_true(joined:find("<leader>tn", 1, true) ~= nil)
     assert.is_true(joined:find("<leader>to", 1, true) ~= nil)
+    assert.is_true(joined:find("<leader>fn", 1, true) ~= nil)
+    assert.is_true(joined:find("<leader>fp", 1, true) ~= nil)
+    assert.is_true(joined:find("[F]ind [N]ext failed test in listing (opens Detail-Float; works in Detail-Float)", 1, true) ~= nil)
+    assert.is_true(joined:find("[F]ind [P]revious failed test in listing (opens Detail-Float; works in Detail-Float)", 1, true) ~= nil)
     assert.is_true(joined:find("<leader>cb", 1, true) ~= nil)
     assert.is_true(joined:find("<leader>cj", 1, true) ~= nil)
     assert.is_true(joined:find("breaks test-command onto multiple lines", 1, true) ~= nil)
@@ -254,6 +262,188 @@ describe("test-samurai core (no bundled runners)", function()
     vim.fn.jobstart = orig_jobstart
   end)
 
+  it("keeps failed-navigation keymaps buffer-local to the output listing", function()
+    local runner = {
+      name = "test-runner-keymaps",
+    }
+
+    function runner.is_test_file(_bufnr)
+      return true
+    end
+
+    function runner.find_nearest(bufnr, _row, _col)
+      return { file = vim.api.nvim_buf_get_name(bufnr), cwd = vim.loop.cwd(), test_name = "TestA" }
+    end
+
+    function runner.build_command(spec)
+      return { cmd = { "echo", "nearest" }, cwd = spec.cwd }
+    end
+
+    function runner.parse_results(_output)
+      return { passes = {}, failures = {}, skips = {} }
+    end
+
+    function runner.output_parser()
+      return {
+        on_line = function(_line, _state)
+          return nil
+        end,
+        on_complete = function(output, _state)
+          return runner.parse_results(output)
+        end,
+      }
+    end
+
+    function runner.parse_test_output(_output)
+      return {}
+    end
+
+    package.loaded["test-samurai-keymap-runner"] = runner
+    test_samurai.setup({ runner_modules = { "test-samurai-keymap-runner" } })
+
+    local normal_buf = vim.api.nvim_create_buf(false, true)
+    vim.api.nvim_buf_set_name(normal_buf, "/tmp/test_samurai_keymaps.go")
+    vim.bo[normal_buf].filetype = "go"
+    vim.api.nvim_set_current_buf(normal_buf)
+
+    local orig_jobstart = vim.fn.jobstart
+    vim.fn.jobstart = function(_cmd, opts)
+      if opts.on_exit then
+        opts.on_exit(nil, 0, nil)
+      end
+      return 1
+    end
+
+    core.run_nearest()
+
+    local listing_buf = vim.api.nvim_get_current_buf()
+    local listing_maps = vim.api.nvim_buf_get_keymap(listing_buf, "n")
+    local has_fn = false
+    local has_fp = false
+    for _, map in ipairs(listing_maps) do
+      if map.lhs and map.lhs:sub(-2) == "fn" then
+        has_fn = true
+      elseif map.lhs and map.lhs:sub(-2) == "fp" then
+        has_fp = true
+      end
+    end
+    assert.is_true(has_fn)
+    assert.is_true(has_fp)
+
+    core.close_output_and_restore()
+
+    local normal_maps = vim.api.nvim_buf_get_keymap(normal_buf, "n")
+    local normal_fn = false
+    local normal_fp = false
+    for _, map in ipairs(normal_maps) do
+      if map.lhs and map.lhs:sub(-2) == "fn" then
+        normal_fn = true
+      elseif map.lhs and map.lhs:sub(-2) == "fp" then
+        normal_fp = true
+      end
+    end
+    assert.is_false(normal_fn)
+    assert.is_false(normal_fp)
+
+    vim.fn.jobstart = orig_jobstart
+  end)
+
+  it("restores cursor location after closing output with <esc><esc>", function()
+    local runner = {
+      name = "test-runner-restore",
+    }
+
+    function runner.is_test_file(_bufnr)
+      return true
+    end
+
+    function runner.find_nearest(bufnr, _row, _col)
+      return { file = vim.api.nvim_buf_get_name(bufnr), cwd = vim.loop.cwd(), test_name = "TestA" }
+    end
+
+    function runner.build_command(spec)
+      return { cmd = { "echo", "nearest" }, cwd = spec.cwd }
+    end
+
+    function runner.build_file_command(_bufnr)
+      return { cmd = { "echo", "file" } }
+    end
+
+    function runner.build_all_command(_bufnr)
+      return { cmd = { "echo", "all" } }
+    end
+
+    function runner.build_failed_command(last_command, _failures, _scope_kind)
+      return { cmd = { "echo", "failed" }, cwd = last_command and last_command.cwd or nil }
+    end
+
+    function runner.parse_results(_output)
+      return { passes = {}, failures = {}, skips = {} }
+    end
+
+    function runner.output_parser()
+      return {
+        on_line = function(_line, _state)
+          return nil
+        end,
+        on_complete = function(output, _state)
+          return runner.parse_results(output)
+        end,
+      }
+    end
+
+    function runner.parse_test_output(_output)
+      return {}
+    end
+
+    function runner.collect_failed_locations(_failures, _command, _scope_kind)
+      return {}
+    end
+
+    package.loaded["test-samurai-restore-runner"] = runner
+    test_samurai.setup({ runner_modules = { "test-samurai-restore-runner" } })
+
+    local normal_win = nil
+    for _, win in ipairs(vim.api.nvim_tabpage_list_wins(0)) do
+      local cfg = vim.api.nvim_win_get_config(win)
+      if cfg.relative == "" then
+        normal_win = win
+        break
+      end
+    end
+    if normal_win then
+      vim.api.nvim_set_current_win(normal_win)
+    end
+
+    local bufnr = vim.api.nvim_create_buf(false, true)
+    vim.api.nvim_buf_set_name(bufnr, "/tmp/test_samurai_restore.go")
+    vim.bo[bufnr].filetype = "go"
+    vim.api.nvim_buf_set_lines(bufnr, 0, -1, false, { "line1", "line2", "line3" })
+    vim.api.nvim_set_current_buf(bufnr)
+    vim.api.nvim_win_set_cursor(0, { 2, 1 })
+
+    local orig_jobstart = vim.fn.jobstart
+    vim.fn.jobstart = function(_cmd, opts)
+      if opts.on_exit then
+        opts.on_exit(nil, 0, nil)
+      end
+      return 1
+    end
+
+    core.run_nearest()
+
+    core.close_output_and_restore()
+
+    local cur_buf = vim.api.nvim_get_current_buf()
+    local cur_cursor = vim.api.nvim_win_get_cursor(0)
+
+    vim.fn.jobstart = orig_jobstart
+
+    assert.equals(bufnr, cur_buf)
+    assert.equals(2, cur_cursor[1])
+    assert.equals(1, cur_cursor[2])
+  end)
+
   it("applies listing break/join substitutions", function()
     local buf = vim.api.nvim_create_buf(false, true)
     vim.api.nvim_set_current_buf(buf)
@@ -816,7 +1006,356 @@ describe("test-samurai core (no bundled runners)", function()
     local detail_buf = vim.api.nvim_get_current_buf()
     local detail_lines = vim.api.nvim_buf_get_lines(detail_buf, 0, -1, false)
     assert.same({ "", "No output captured" }, detail_lines)
+    local selection_ns = vim.api.nvim_create_namespace("TestSamuraiListingSelection")
+    local marks = vim.api.nvim_buf_get_extmarks(listing_buf, selection_ns, 0, -1, { details = true })
+    assert.is_true(#marks > 0)
+    local highlighted = false
+    for _, mark in ipairs(marks) do
+      if mark[2] == target - 1 then
+        highlighted = true
+        break
+      end
+    end
+    assert.is_true(highlighted)
 
     vim.fn.jobstart = orig_jobstart
   end)
+
+  it("maps <leader>ff to jump to the first listing entry and open the detail float", function()
+    local runner = {
+      name = "test-runner",
+    }
+
+    function runner.is_test_file(_bufnr)
+      return true
+    end
+
+    function runner.find_nearest(bufnr, _row, _col)
+      return { file = vim.api.nvim_buf_get_name(bufnr), cwd = vim.loop.cwd(), test_name = "TestA" }
+    end
+
+    function runner.build_command(spec)
+      return { cmd = { "echo", "nearest" }, cwd = spec.cwd }
+    end
+
+    function runner.build_file_command(_bufnr)
+      return { cmd = { "echo", "file" } }
+    end
+
+    function runner.build_all_command(_bufnr)
+      return { cmd = { "echo", "all" } }
+    end
+
+    function runner.build_failed_command(last_command, _failures, _scope_kind)
+      return { cmd = { "echo", "failed" }, cwd = last_command and last_command.cwd or nil }
+    end
+
+    function runner.parse_results(output)
+      local passes = {}
+      if type(output) == "string" and output:find("PASS TestA", 1, true) then
+        passes = { "TestA" }
+      end
+      return { passes = passes, failures = {}, skips = {} }
+    end
+
+    function runner.output_parser()
+      return {
+        on_line = function(line, _state)
+          if line == "PASS TestA" then
+            return { passes = { "TestA" }, failures = {}, skips = {} }
+          end
+          return nil
+        end,
+        on_complete = function(output, _state)
+          return runner.parse_results(output)
+        end,
+      }
+    end
+
+    function runner.parse_test_output(_output)
+      return {}
+    end
+
+    function runner.collect_failed_locations(_failures, _command, _scope_kind)
+      return {}
+    end
+
+    package.loaded["test-samurai-test-runner"] = runner
+    test_samurai.setup({ runner_modules = { "test-samurai-test-runner" } })
+
+    local bufnr = vim.api.nvim_create_buf(false, true)
+    vim.api.nvim_buf_set_name(bufnr, "/tmp/test_runner_listing_ff.go")
+    vim.bo[bufnr].filetype = "go"
+    vim.api.nvim_set_current_buf(bufnr)
+
+    local orig_jobstart = vim.fn.jobstart
+    vim.fn.jobstart = function(_cmd, opts)
+      if opts.on_stdout then
+        opts.on_stdout(nil, { "PASS TestA" }, nil)
+      end
+      if opts.on_exit then
+        opts.on_exit(nil, 0, nil)
+      end
+      return 1
+    end
+
+    core.run_nearest()
+
+    vim.fn.jobstart = orig_jobstart
+
+    local listing_buf = vim.api.nvim_get_current_buf()
+    assert.is_true(vim.bo[listing_buf].filetype == "test-samurai-output")
+
+    local maps = vim.api.nvim_buf_get_keymap(listing_buf, "n")
+    local found = nil
+    for _, map in ipairs(maps) do
+      if type(map.lhs) == "string" and map.lhs:sub(-2) == "ff" then
+        found = map
+        break
+      end
+    end
+    assert.is_true(found ~= nil)
+    assert.equals("[F]ind [F]irst list entry", found.desc)
+
+    vim.api.nvim_set_current_buf(listing_buf)
+    local listing_win = vim.api.nvim_get_current_win()
+    local total = vim.api.nvim_buf_line_count(listing_buf)
+    vim.api.nvim_win_set_cursor(0, { total, 0 })
+    assert.is_true(type(found.callback) == "function")
+    found.callback()
+
+    local lines = vim.api.nvim_buf_get_lines(listing_buf, 0, -1, false)
+    local first_entry = nil
+    for i, line in ipairs(lines) do
+      if line:match("^%[ %u+ %] %- ") then
+        first_entry = i
+        break
+      end
+    end
+    assert.is_true(first_entry ~= nil)
+    local cursor = vim.api.nvim_win_get_cursor(listing_win)
+    assert.equals(first_entry, cursor[1])
+
+    local detail_buf = vim.api.nvim_get_current_buf()
+    local detail_lines = vim.api.nvim_buf_get_lines(detail_buf, 0, -1, false)
+    assert.same({ "", "No output captured" }, detail_lines)
+  end)
+
+  it("opens the detail float after jumping to the next failed entry", function()
+    local runner = {
+      name = "test-runner-listing-fn",
+    }
+
+    function runner.is_test_file(_bufnr)
+      return true
+    end
+
+    function runner.find_nearest(bufnr, _row, _col)
+      return { file = vim.api.nvim_buf_get_name(bufnr), cwd = vim.loop.cwd(), test_name = "TestB" }
+    end
+
+    function runner.build_command(spec)
+      return { cmd = { "echo", "nearest" }, cwd = spec.cwd }
+    end
+
+    function runner.build_file_command(_bufnr)
+      return { cmd = { "echo", "file" } }
+    end
+
+    function runner.build_all_command(_bufnr)
+      return { cmd = { "echo", "all" } }
+    end
+
+    function runner.build_failed_command(last_command, _failures, _scope_kind)
+      return { cmd = { "echo", "failed" }, cwd = last_command and last_command.cwd or nil }
+    end
+
+    function runner.parse_results(_output)
+      return { passes = {}, failures = { "TestB" }, skips = {} }
+    end
+
+    function runner.output_parser()
+      return {
+        on_complete = function(output, _state)
+          return runner.parse_results(output)
+        end,
+      }
+    end
+
+    function runner.parse_test_output(_output)
+      return {}
+    end
+
+    function runner.collect_failed_locations(_failures, _command, _scope_kind)
+      return {}
+    end
+
+    package.loaded["test-samurai-fn-runner"] = runner
+    test_samurai.setup({ runner_modules = { "test-samurai-fn-runner" } })
+
+    local bufnr = vim.api.nvim_create_buf(false, true)
+    vim.api.nvim_buf_set_name(bufnr, "/tmp/test_runner_listing_fn.go")
+    vim.bo[bufnr].filetype = "go"
+    vim.api.nvim_set_current_buf(bufnr)
+
+    local orig_jobstart = vim.fn.jobstart
+    vim.fn.jobstart = function(_cmd, opts)
+      if opts.on_exit then
+        opts.on_exit(nil, 0, nil)
+      end
+      return 1
+    end
+
+    core.run_nearest()
+
+    vim.fn.jobstart = orig_jobstart
+
+    local listing_buf = vim.api.nvim_get_current_buf()
+    assert.is_true(vim.bo[listing_buf].filetype == "test-samurai-output")
+
+    local maps = vim.api.nvim_buf_get_keymap(listing_buf, "n")
+    local found = nil
+    for _, map in ipairs(maps) do
+      if type(map.lhs) == "string" and map.lhs:sub(-2) == "fn" then
+        found = map
+        break
+      end
+    end
+    assert.is_true(found ~= nil)
+
+    vim.api.nvim_set_current_buf(listing_buf)
+    local listing_win = vim.api.nvim_get_current_win()
+    vim.api.nvim_win_set_cursor(0, { 1, 0 })
+    assert.is_true(type(found.callback) == "function")
+    found.callback()
+
+    local lines = vim.api.nvim_buf_get_lines(listing_buf, 0, -1, false)
+    local fail_entry = nil
+    for i, line in ipairs(lines) do
+      if line:match("^%[ FAIL %] %- ") then
+        fail_entry = i
+        break
+      end
+    end
+    assert.is_true(fail_entry ~= nil)
+    local cursor = vim.api.nvim_win_get_cursor(listing_win)
+    assert.equals(fail_entry, cursor[1])
+
+    local detail_buf = vim.api.nvim_get_current_buf()
+    local detail_lines = vim.api.nvim_buf_get_lines(detail_buf, 0, -1, false)
+    assert.same({ "", "No output captured" }, detail_lines)
+  end)
+
+  it("allows <leader>fn from the detail float to jump the listing and refresh detail", function()
+    local runner = {
+      name = "test-runner-detail-fn",
+    }
+
+    function runner.is_test_file(_bufnr)
+      return true
+    end
+
+    function runner.find_nearest(bufnr, _row, _col)
+      return { file = vim.api.nvim_buf_get_name(bufnr), cwd = vim.loop.cwd(), test_name = "TestC" }
+    end
+
+    function runner.build_command(spec)
+      return { cmd = { "echo", "nearest" }, cwd = spec.cwd }
+    end
+
+    function runner.build_file_command(_bufnr)
+      return { cmd = { "echo", "file" } }
+    end
+
+    function runner.build_all_command(_bufnr)
+      return { cmd = { "echo", "all" } }
+    end
+
+    function runner.build_failed_command(last_command, _failures, _scope_kind)
+      return { cmd = { "echo", "failed" }, cwd = last_command and last_command.cwd or nil }
+    end
+
+    function runner.parse_results(_output)
+      return { passes = {}, failures = { "TestC" }, skips = {} }
+    end
+
+    function runner.output_parser()
+      return {
+        on_complete = function(output, _state)
+          return runner.parse_results(output)
+        end,
+      }
+    end
+
+    function runner.parse_test_output(_output)
+      return {}
+    end
+
+    function runner.collect_failed_locations(_failures, _command, _scope_kind)
+      return {}
+    end
+
+    package.loaded["test-samurai-detail-fn-runner"] = runner
+    test_samurai.setup({ runner_modules = { "test-samurai-detail-fn-runner" } })
+
+    local bufnr = vim.api.nvim_create_buf(false, true)
+    vim.api.nvim_buf_set_name(bufnr, "/tmp/test_runner_detail_fn.go")
+    vim.bo[bufnr].filetype = "go"
+    vim.api.nvim_set_current_buf(bufnr)
+
+    local orig_jobstart = vim.fn.jobstart
+    vim.fn.jobstart = function(_cmd, opts)
+      if opts.on_exit then
+        opts.on_exit(nil, 0, nil)
+      end
+      return 1
+    end
+
+    core.run_nearest()
+
+    vim.fn.jobstart = orig_jobstart
+
+    local listing_buf = vim.api.nvim_get_current_buf()
+    assert.is_true(vim.bo[listing_buf].filetype == "test-samurai-output")
+
+    local lines = vim.api.nvim_buf_get_lines(listing_buf, 0, -1, false)
+    local fail_entry = nil
+    for i, line in ipairs(lines) do
+      if line:match("^%[ FAIL %] %- ") then
+        fail_entry = i
+        break
+      end
+    end
+    assert.is_true(fail_entry ~= nil)
+
+    local listing_win = vim.api.nvim_get_current_win()
+    vim.api.nvim_win_set_cursor(listing_win, { fail_entry, 0 })
+    core.open_test_output_at_cursor()
+
+    local detail_win = vim.api.nvim_get_current_win()
+    local detail_buf = vim.api.nvim_get_current_buf()
+    local maps = vim.api.nvim_buf_get_keymap(detail_buf, "n")
+    local found = nil
+    for _, map in ipairs(maps) do
+      if type(map.lhs) == "string" and map.lhs:sub(-2) == "fn" then
+        found = map
+        break
+      end
+    end
+    assert.is_true(found ~= nil)
+
+    vim.api.nvim_set_current_win(listing_win)
+    vim.api.nvim_win_set_cursor(listing_win, { 1, 0 })
+    vim.api.nvim_set_current_win(detail_win)
+
+    assert.is_true(type(found.callback) == "function")
+    found.callback()
+
+    local cursor = vim.api.nvim_win_get_cursor(listing_win)
+    assert.equals(fail_entry, cursor[1])
+
+    local refreshed_buf = vim.api.nvim_get_current_buf()
+    local detail_lines = vim.api.nvim_buf_get_lines(refreshed_buf, 0, -1, false)
+    assert.same({ "", "No output captured" }, detail_lines)
+  end)
 end)