neotest.txt

================================================================================
                                                                       *neotest*

A framework to interact with tests within NeoVim.

There are three main components to this plugin's architecture.
- Adapters: Generally language specific objects to parse tests, build commands
  and parse results
- Client: Runs tests and stores state of tests and results, emitting events
  during operation
- Consumers: Use the client to provide some utility to interact with tests and
  results

In order to use neotest, you must use an adapter for your language of choice.
You can supply them in the setup function.

Once you have setup an adapter, you can use neotest consumers to run and
interact with tests. For most users, the bulk of relevant features will be in
the consumers. There are multiple consumers:
- run: Allows running, debugging and stopping tests.

- summary: Shows all known tests in a tree structure, along with their current
  state.

- output: Displays the output of tests.

- diagnostics: Uses vim.diagnostic to show error messages where they occur (if
  supported by the adapter).

- status: Displays signs beside tests and namespaces to show current result
  state.

Each consumer can be accessed as a property of the neotest module

>
 require("neotest").summary.toggle()
<



neotest.setup({user_config})                                 *neotest.setup()*
    Configure Neotest strategies and consumers
       See: ~
           |neotest.Config|

    Default values:
      {
        adapters = {},
        diagnostic = {
          enabled = true
        },
        floating = {
          border = "rounded",
          max_height = 0.6,
          max_width = 0.6
        },
        highlights = {
          adapter_name = "NeotestAdapterName",
          border = "NeotestBorder",
          dir = "NeotestDir",
          expand_marker = "NeotestExpandMarker",
          failed = "NeotestFailed",
          file = "NeotestFile",
          focused = "NeotestFocused",
          indent = "NeotestIndent",
          namespace = "NeotestNamespace",
          passed = "NeotestPassed",
          running = "NeotestRunning",
          skipped = "NeotestSkipped",
          test = "NeotestTest"
        },
        icons = {
          child_indent = "│",
          child_prefix = "├",
          collapsed = "─",
          expanded = "╮",
          failed = "✖",
          final_child_indent = " ",
          final_child_prefix = "╰",
          non_collapsible = "─",
          passed = "✔",
          running = "🗘",
          skipped = "ﰸ",
          unknown = "?"
        },
        output = {
          enabled = true,
          open_on_run = "short"
        },
        run = {
          enabled = true
        },
        status = {
          enabled = true
        },
        strategies = {
          integrated = {
            height = 40,
            width = 120
          }
        },
        summary = {
          enabled = true,
          expand_errors = true,
          follow = true,
          mappings = {
            attach = "a",
            expand = { "<CR>", "<2-LeftMouse>" },
            expand_all = "e",
            jumpto = "i",
            output = "o",
            run = "r",
            short = "O",
            stop = "u"
          }
        }
      }

    Parameters: ~
        {user_config} (neotest.Config)



================================================================================
                                                                *neotest.config*

neotest.Config                                                *neotest.Config*


    Fields: ~
        {adapters}   (neotest.Adapter[])
        {icons}      (table<string, string>)
        {highlights} (table<string, string>)
        {floating}   (neotest.Config.floating)
        {strategies} (neotest.Config.strategies)
        {summary}    (neotest.Config.summary)
        {output}     (neotest.Config.output)


neotest.Config.floating                              *neotest.Config.floating*


    Fields: ~
        {border}     (string)  Border style
        {max_height} (number)  Max height of window as proportion of NeoVim
                               window
        {max_width}  (number)  Max width of window as proportion of NeoVim
                               window


neotest.Config.strategies.integrated    *neotest.Config.strategies.integrated*


    Fields: ~
        {width} (integer)  Width to pass to the pty runnning commands


neotest.Config.strategies                          *neotest.Config.strategies*


    Fields: ~
        {integrated} (neotest.Config.strategies.integrated)


neotest.Config.summary                                *neotest.Config.summary*


    Fields: ~
        {enabled}       (boolean)
        {follow}        (boolean)                          Expand user's
                                                           current file
        {expand_errors} (boolean)                          Expand all failed
                                                           positions
        {mappings}      (neotest.Config.summary.mappings)  Buffer mappings for
                                                           summary window


neotest.Config.summary.mappings              *neotest.Config.summary.mappings*


    Fields: ~
        {expand}     (string|string[])  Expand currently selected position
        {expand_all} (string|string[])  Expand all positions under currently
                                        selected
        {output}     (string|string[])  Show output for position
        {short}      (string|string[])  Show short output for position (if
                                        exists)
        {attach}     (string|string[])  Attach to process for position
        {jumpto}     (string|string[])  Jump to the selected position
        {stop}       (string|string[])  Stop selected position
        {run}        (string|string[])  Run selected position


neotest.Config.output                                  *neotest.Config.output*


    Fields: ~
        {enabled}     (boolean)
        {open_on_run} (boolean)  Open nearest test result after running


neotest.Config.diagnostic                          *neotest.Config.diagnostic*


    Fields: ~
        {enabled} (boolean)


neotest.Config.status                                  *neotest.Config.status*


    Fields: ~
        {enabled} (boolean)



================================================================================
                                                                *neotest.output*

A consumer that displays the output of test results.

neotest.output.open({opts})                            *neotest.output.open()*
    Open the output of a test result
    >
    lua require("neotest").open({ enter = true })
<


    Parameters: ~
        {opts} (table)

    Fields: ~
        {short}       (boolean)  Show shortened output
        {enter}       (boolean)  Enter output window
        {position_id} (string)   Open output for position with this ID, opens
                                 nearest position if not given
        {adapter}     (string)   Adapter ID, defaults to first found with
                                 matching position



================================================================================
                                                                   *neotest.run*

A consumer providing a simple interface to run tests.

neotest.run.run({args})                                    *neotest.run.run()*
    Run the given position or the nearest position if not given. All arguments
    are optional

    Run the current file
    >
    lua require("neotest").run(vim.fn.expand("%"))
<

    Run the nearest test
    >
    lua require("neotest").run()
<

    Debug the current file with nvim-dap
    >
    lua require("neotest").run({vim.fn.expand("%"), strategy = "dap"})
<


    Parameters: ~
        {args} (string|table)  Position ID to run 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.
        {strategy}   (string|neotest.Strategy)  Strategy to run commands with
        {extra_args} (string[])                 Extra arguments for test
                                                command


neotest.run.stop({args})                                  *neotest.run.stop()*
    Stop a running process


    Parameters: ~
        {args} (string|table)  Position ID to stop 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.


neotest.run.attach({args})                              *neotest.run.attach()*
    Attach to a running process for the given position.


    Parameters: ~
        {args} (string|table)  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.



================================================================================
                                                                *neotest.status*

A consumer that displays the results of tests as signs beside their
declaration. This consumer is completely passive and so has no interface.


================================================================================
                                                            *neotest.diagnostic*

A consumer that displays error messages using the vim.diagnostic API. This
consumer is completely passive and so has no interface.

You can configure the diagnostic API for neotest using the "neotest" namespace
   See: ~
       |vim.diagnostic.config()|


================================================================================
                                                               *neotest.summary*

A consumer that displays the structure of the test suite, along with results
and allows running tests.
   See: ~
       |neotest.Config.summary.mappings| for all mappings in the summary window

neotest.summary.open()                                *neotest.summary.open()*
    Open the summary window
    >
    lua require("neotest").summary.open()
<



neotest.summary.close()                              *neotest.summary.close()*
    Close the summary window
    >
    lua require("neotest").summary.close()
<



neotest.summary.toggle()                            *neotest.summary.toggle()*
    Toggle the summary window
    >
    lua require("neotest").summary.toggle()
<




 vim:tw=78:ts=8:ft=help:norl: