feat: typed consumers

All consumer APIs now have full type annotations that work for document
generation and for the Lua LSP so that users will see type hints when
interating with neotest.

doc/neotest.txt

@@ -1,6 +1,8 @@
 *neotest.txt*	A framework to interact with tests within NeoVim
 
 ==============================================================================
+neotest                                                                *neotest*
+
   Setup......................................................|neotest.setup()|
   Configuration Options.......................................|neotest.config|
   Consumers................................................|neotest.consumers|
@@ -46,9 +48,6 @@ See the table of contents for the consumers
 <
 
 
-neotest                                                                *neotest*
-
-
                                                                *neotest.setup()*
 `setup`({user_config})
 
@@ -333,15 +332,7 @@ neotest.output                                                  *neotest.output*
 
 A consumer that displays the output of test results.
 
-                                                         *neotest.output.open()*
-`open`({opts})
-
-Open the output of a test result
->
-  lua require("neotest").output.open({ enter = true })
-<
-Parameters~
-{opts} `(table?)`
+                                             *neotest.consumers.output.OpenArgs*
 Fields~
 {open_win} `(function)` Function that takes a table with width and height keys
 and opens a window for the output. If a window ID is not returned, the current
@@ -355,6 +346,16 @@ position if not given
 {adapter} `(string)` Adapter ID, defaults to first found with matching position
 {auto_close} `(boolean)` Close output window when leaving it, or when cursor moves outside of window
 
+                                                         *neotest.output.open()*
+`open`({opts})
+
+Open the output of a test result
+>
+  lua require("neotest").output.open({ enter = true })
+<
+Parameters~
+{opts?} `(neotest.consumers.output.OpenArgs)`
+
 
 ==============================================================================
 neotest.output_panel                                      *neotest.output_panel*
@@ -420,8 +421,7 @@ Debug the current file with nvim-dap
   lua require("neotest").run.run({vim.fn.expand("%"), strategy = "dap"})
 <
 Parameters~
-{args} `(string|neotest.run.RunArgs?)` Position ID to run or args. If args then args[1] should
-be the position ID.
+{args} `(string|neotest.run.RunArgs?)` Position ID to run or args. If args then args[1] should be the position ID.
 
                                                         *neotest.run.run_last()*
 `run_last`({args})
@@ -440,28 +440,27 @@ nvim-dap
   lua require("neotest").run.run_last({ strategy = "dap" })
 <
 Parameters~
-{args} `(table)` Arguments to run with
+{args} `(neotest.run.RunArgs?)` Argument overrides
+
+                                                          *neotest.run.StopArgs*
+Inherits: `neotest.client.StopArgs`
 
 Fields~
-{adapter} `(string)` Adapter ID, if not given the same adapter as the last run
-is used.
-{strategy} `(string|neotest.Strategy)` Strategy to run commands with
-{extra_args} `(string[])` Extra arguments for test command
-{env} `(table<string, string>)` Extra environment variables to add to the
-environment of tests
-{concurrent} `(boolean)` Run tests concurrently when an adapter provides multiple commands to run
+{interactive} `(boolean)` Select a running position interactively
 
                                                             *neotest.run.stop()*
 `stop`({args})
 
 Stop a running process
 
 Parameters~
-{args} `(string|table?)` Position ID to stop or args. If args then args[1]
-should be the position ID.
+{args} `(string|neotest.run.StopArgs?)` Position ID to stop or args. If
+args then args[1] should be the position ID.
+
+                                                        *neotest.run.AttachArgs*
+Inherits: `neotest.client.AttachArgs`
+
 Fields~
-{adapter} `(string)` Adapter ID, if not given the first adapter found with
-chosen position is used.
 {interactive} `(boolean)` Select a running position interactively
 
                                                           *neotest.run.attach()*
@@ -470,25 +469,22 @@ chosen position is used.
 Attach to a running process for the given position.
 
 Parameters~
-{args} `(string|table?)` Position ID to attach to or args. If args then
+{args} `(string|neotest.run.AttachArgs?)` Position ID to attach to or args. If args then
 args[1] should be the position ID.
 
-Fields~
-{adapter} `(string)` Adapter ID, if not given the first adapter found with
-chosen position is used.
-{interactive} `(boolean)` Select a running position interactively
-
                                                         *neotest.run.adapters()*
 `adapters`()
 
 Get the list of all known adapter IDs.
+Return~
+`(string[])`
 
                                                     *neotest.run.get_last_run()*
 `get_last_run`()
 
-Get last test run tree and adapter id.
+Get last test position ID and args
 Return~
-`(string)` | nil, table | nil Position id and last args table
+`(string|nil,neotest.run.RunArgs|nil)` Position id and last args table
 
 
 ==============================================================================
@@ -545,36 +541,33 @@ the summary window
  lua require("neotest").summary.toggle()
 
 
+                                                *neotest.summmary.RunMarkedArgs*
+Inherits: `neotest.run.RunArgs`
+
+
                                                   *neotest.summary.run_marked()*
 `run_marked`({args})
 
 Run all marked positions
 Parameters~
-{args} `(table)`
-
-Fields~
-{adapter} `(string)` Adapter ID, if not given all adapters are used
-{strategy} `(string|neotest.Strategy)` Strategy to run commands with
-{extra_args} `(string[])` Extra arguments for test command
-{env} `(table<string, string>)` Extra environment variables to add to the
-environment of tests
+{args?} `(neotest.summmary.RunMarkedArgs)`
 
                                                       *neotest.summary.marked()*
 `marked`()
 
 Return a table<adapter id, position_id[]> of all marked positions
+@return table<string, string[]>
 
-@return table
+                                               *neotest.summary.ClearMarkedArgs*
+Fields~
+{adapter?} `(string)` Adapter ID, if not given all adapters are cleared
 
                                                 *neotest.summary.clear_marked()*
 `clear_marked`({args})
 
 Clear all marked positions
 Parameters~
-{args} `(table)`
-
-Fields~
-{adapter} `(string)` Adapter ID, if not given all adapters are used
+{args?} `(neotest.summary.ClearMarkedArgs)`
 
                                                       *neotest.summary.target()*
 `target`({adapter_id}, {position_id})
@@ -597,25 +590,23 @@ Example mappings to jump between test failures
   nnoremap <silent>]n <cmd>lua require("neotest").jump.next({ status = "failed" })<CR>
 <
 
+                                               *neotest.consumers.jump.JumpArgs*
+Fields~
+{status} `(string)` Only jump to positions with given status
+
                                                            *neotest.jump.next()*
 `next`({args})
 
 Jump to the position after the cursor position in the current file
 Parameters~
-{args} `(table)` Optionals arguments
-
-Fields~
-{status} `(string)` Only jump to positions with given status
+{args?} `(neotest.consumers.jump.JumpArgs)`
 
                                                            *neotest.jump.prev()*
 `prev`({args})
 
 to the position after the cursor position in the current file
 Parameters~
-{args} `(table)` Optionals arguments
-
-Fields~
-{status} `(string)` Only jump to positions with given status
+{args?} `(neotest.consumers.jump.JumpArgs)`
 
 
 ==============================================================================
@@ -898,7 +889,7 @@ Type~
                                            *neotest.lib.files.detect_filetype()*
 `detect_filetype`({path})
 
-Detect the filetype of a file by checking the name, extensions, shebang or 
+Detect the filetype of a file by checking the name, extensions, shebang or
 modeline. This is a memoized wrapper around plenary's filetype detection.
 Parameters~
 {path} `(string)`
@@ -967,7 +958,7 @@ Return~
 
 Filter elements from a list
 Parameters~
-{f} `(fun(i: integer, v: V): boolean)`
+{f} `(fun(v: V): boolean)`
 {t} `(V[])`
 Return~
 `(V[])`
@@ -1157,7 +1148,7 @@ Return~
 Read a file's contents from disk and parse test positions using the given query.
 Executed in a subprocess to avoid blocking the editor if possible.
 Since functions can't be serialised for RPC the build_position and position_id options
-can be strings that will evaluate to globally referencable functions 
+can be strings that will evaluate to globally referencable functions
 (e.g. `'require("my_adapter")._build_position'`).
 
 Parameters~

lua/neotest/client/init.lua

@@ -164,7 +164,6 @@ function neotest.Client:get_nearest(file_path, row, args)
   return nearest, adapter_id
 end
 
-
 ---Get all known active adapters
 ---@async
 ---@return string[]
@@ -265,9 +264,11 @@ function neotest.Client:_update_positions(path, args)
       -- If existing tree then we have to find the point to merge the trees and update that path rather than trying to
       -- merge an orphan. This happens when a whole new directory is found (e.g. renamed an existing one).
       local existing_root = self:get_position(nil, { adapter = adapter_id })
-      while existing_root
-          and vim.startswith(path, existing_root:data().path)
-          and not self:get_position(path, { adapter = adapter_id }) do
+      while
+        existing_root
+        and vim.startswith(path, existing_root:data().path)
+        and not self:get_position(path, { adapter = adapter_id })
+      do
         path = lib.files.parent(path)
         if not vim.startswith(path, existing_root:data().path) then
           return
@@ -281,10 +282,10 @@ function neotest.Client:_update_positions(path, args)
         lib.files.find(path, {
           filter_dir = function(...)
             return (not adapter.filter_dir or adapter.filter_dir(...))
-                and (
+              and (
                 not config.projects[root_path].discovery.filter_dir
-                    or config.projects[root_path].discovery.filter_dir(...)
-                )
+                or config.projects[root_path].discovery.filter_dir(...)
+              )
           end,
         })
       )
@@ -337,8 +338,9 @@ function neotest.Client:_get_adapter(position_id, adapter_id)
     end
 
     local root = self._state:positions(a_id)
-    if (not root or vim.startswith(position_id, root:data().path))
-        and (lib.files.is_dir(position_id) or adapter.is_test_file(position_id))
+    if
+      (not root or vim.startswith(position_id, root:data().path))
+      and (lib.files.is_dir(position_id) or adapter.is_test_file(position_id))
     then
       return a_id, adapter
     end
@@ -492,12 +494,12 @@ end
 function neotest.Client:_update_adapters(dir)
   local adapters_with_root = lib.files.is_dir(dir)
       and self._adapter_group:adapters_with_root_dir(dir)
-      or {}
+    or {}
 
   local adapters_with_bufs =
-  self._adapter_group:adapters_matching_open_bufs(lib.func_util.map(function(i, entry)
-    return i, entry.root
-  end, adapters_with_root))
+    self._adapter_group:adapters_matching_open_bufs(lib.func_util.map(function(i, entry)
+      return i, entry.root
+    end, adapters_with_root))
 
   local found = {}
   for adapter_id, _ in pairs(self._adapters) do

lua/neotest/consumers/diagnostic.lua

@@ -230,6 +230,7 @@ local neotest = {}
 ---
 --- You can configure the diagnostic API for neotest using the "neotest" namespace
 ---@seealso |vim.diagnostic.config()|
+---@class neotest.consumers.diagnostic
 neotest.diagnostic = {}
 neotest.diagnostic = setmetatable(neotest.diagnostic, {
   __call = function(_, ...)

lua/neotest/consumers/jump.lua

@@ -16,6 +16,7 @@ local neotest = {}
 ---   nnoremap <silent>[n <cmd>lua require("neotest").jump.prev({ status = "failed" })<CR>
 ---   nnoremap <silent>]n <cmd>lua require("neotest").jump.next({ status = "failed" })<CR>
 --- <
+---@class neotest.consumers.jump
 neotest.jump = {}
 
 local get_nearest = function()
@@ -84,10 +85,11 @@ local jump_to_next = function(pos, predicate)
   end
 end
 
---- Jump to the position after the cursor position in the current file
----@param args table Optionals arguments
----
+---@class neotest.consumers.jump.JumpArgs
 ---@field status string Only jump to positions with given status
+
+--- Jump to the position after the cursor position in the current file
+---@param args? neotest.consumers.jump.JumpArgs
 function neotest.jump.next(args)
   args = args or {}
 
@@ -108,9 +110,7 @@ function neotest.jump.next(args)
 end
 
 ---Jump to the position after the cursor position in the current file
----@param args table Optionals arguments
----
----@field status string Only jump to positions with given status
+---@param args? neotest.consumers.jump.JumpArgs
 function neotest.jump.prev(args)
   args = args or {}
   async.run(function()

lua/neotest/consumers/output.lua

@@ -92,6 +92,7 @@ local neotest = {}
 ---@toc_entry Output Consumer
 ---@text
 --- A consumer that displays the output of test results.
+---@class neotest.consumers.output
 neotest.output = {}
 
 ---@private
@@ -129,11 +130,7 @@ local init = function()
   end
 end
 
---- Open the output of a test result
---- >
----   lua require("neotest").output.open({ enter = true })
---- <
----@param opts table?
+---@class neotest.consumers.output.OpenArgs
 ---@field open_win function Function that takes a table with width and height keys
 --- and opens a window for the output. If a window ID is not returned, the current
 --- window will be used
@@ -145,6 +142,12 @@ end
 --- position if not given
 ---@field adapter string Adapter ID, defaults to first found with matching position
 ---@field auto_close boolean Close output window when leaving it, or when cursor moves outside of window
+
+--- Open the output of a test result
+--- >
+---   lua require("neotest").output.open({ enter = true })
+--- <
+---@param opts? neotest.consumers.output.OpenArgs
 function neotest.output.open(opts)
   opts = opts or {}
   if win then

lua/neotest/consumers/output_panel/init.lua

@@ -11,6 +11,7 @@ local neotest = {}
 ---@toc_entry Output Panel Consumer
 ---@text
 --- A consumer that streams all output of tests to a terminal window.
+---@class neotest.consumers.output_panel
 neotest.output_panel = {}
 
 ---@param client neotest.Client