feat: add dap strategy (#17)

Author: przepompownia

README.md

@@ -66,10 +66,12 @@ use({
 adapters = {
   require("neotest-phpunit")({
     phpunit_cmd = function()
-      return "vendor/bin/phpunit"
+      return "vendor/bin/phpunit" -- for `dap` strategy then it must return string (table values will cause validation error)
     end,
     root_files = { "composer.json", "phpunit.xml", ".gitignore" },
-    filter_dirs = { ".git", "node_modules" }
+    filter_dirs = { ".git", "node_modules" },
+    env = {}, -- for example {XDEBUG_CONFIG = 'idekey=neotest'}
+    dap = nil, -- to configure `dap` strategy put single element from `dap.configurations.php`
   }),
 }
 ```
@@ -124,6 +126,50 @@ require("neotest-phpunit")({
 })
 ```
 
+### Debugging with `dap` strategy
+
+You need to install and configure [nvim-dap](https://github.com/mfussenegger/nvim-dap) with [vscode-php-debug](https://github.com/xdebug/vscode-php-debug) first. For example if you have
+```lua
+dap.configurations.php = {
+  {
+    log = true,
+    type = "php",
+    request = "launch",
+    name = "Listen for XDebug",
+    port = 9003,
+    stopOnEntry = false,
+    xdebugSettings = {
+      max_children = 512,
+      max_data = 1024,
+      max_depth = 4,
+    },
+    breakpoints = {
+      exception = {
+        Notice = false,
+        Warning = false,
+        Error = false,
+        Exception = false,
+        ["*"] = false,
+      },
+    },
+  }
+}
+```
+you can set
+```lua
+require("neotest-phpunit")({
+  env = {
+      XDEBUG_CONFIG = "idekey=neotest",
+  },
+  dap = dap.configurations.php[1],
+})
+```
+
+If you run a test with `dap` strategy from the summary window (by default by `d`) and see that window content replaced by debugged buffer content then consider setting `dap.defaults.fallback.switchbuf` or Neovim level [`switchbuf`](https://neovim.io/doc/user/options.html#'switchbuf'), f.e.
+```lua
+dap.defaults.fallback.switchbuf = "useopen"
+```
+
 ## :rocket: Usage
 
 #### Test single method

lua/neotest-phpunit/config.lua

@@ -4,6 +4,10 @@ M.get_phpunit_cmd = function()
   return "vendor/bin/phpunit"
 end
 
+M.get_env = function()
+  return {}
+end
+
 M.get_root_files = function()
   return { "composer.json", "phpunit.xml", ".gitignore" }
 end

lua/neotest-phpunit/init.lua

@@ -8,6 +8,45 @@ local logger = require("neotest.logging")
 local utils = require("neotest-phpunit.utils")
 local config = require("neotest-phpunit.config")
 
+local dap_configuration
+
+local function get_strategy_config(strategy, program, args)
+  local cfg = {
+    dap = function()
+      vim.validate({ dap = {
+        dap_configuration,
+        function (val)
+          local valid = type(val) == "table" and not vim.tbl_isempty(val)
+
+          return valid, "Configure `dap` field (like in dap.configurations.php) before using this strategy"
+        end,
+        "not empty table"
+      }})
+      vim.validate({
+        phpunit_cmd = {
+          program,
+          function (val)
+            return type(val) == "string", "For `dap` strategy `phpunit_cmd` must be (or return) string."
+          end,
+          "string",
+        }
+      })
+
+      return vim.tbl_extend("keep", {
+        type = "php",
+        name = "Neotest Debugger",
+        cwd = async.fn.getcwd(),
+        program = program,
+        args = args,
+        runtimeArgs = { "-dzend_extension=xdebug.so" },
+      }, dap_configuration or {})
+    end,
+  }
+  if cfg[strategy] then
+    return cfg[strategy]()
+  end
+end
+
 ---@class neotest.Adapter
 ---@field name string
 local NeotestAdapter = { name = "neotest-phpunit" }
@@ -79,33 +118,41 @@ end
 function NeotestAdapter.build_spec(args)
   local position = args.tree:data()
   local results_path = async.fn.tempname()
+  local program = config.get_phpunit_cmd()
 
-  local command = vim.tbl_flatten({
-    config.get_phpunit_cmd(),
+  local script_args = {
     position.name ~= "tests" and position.path,
     "--log-junit=" .. results_path,
-  })
+  }
 
   if position.type == "test" then
-    local script_args = vim.tbl_flatten({
+    local filter_args = vim.tbl_flatten({
       "--filter",
       '::' .. position.name .. '( with data set .*)?$',
     })
 
     logger.info("position.path:", { position.path })
     logger.info("--filter position.name:", { position.name })
 
-    command = vim.tbl_flatten({
-      command,
+    script_args = vim.tbl_flatten({
       script_args,
+      filter_args,
     })
   end
 
+  local command = vim.tbl_flatten({
+    program,
+    script_args,
+  })
+
+  ---@type neotest.RunSpec
   return {
     command = command,
     context = {
       results_path = results_path,
     },
+    strategy = get_strategy_config(args.strategy, program, script_args),
+    env = args.env or config.get_env(),
   }
 end
 
@@ -165,6 +212,16 @@ setmetatable(NeotestAdapter, {
         return opts.filter_dirs
       end
     end
+    if is_callable(opts.env) then
+      config.get_env = opts.env
+    elseif type(opts.env) == "table" then
+      config.get_env = function ()
+        return opts.env
+      end
+    end
+    if type(opts.dap) == "table" then
+      dap_configuration = opts.dap
+    end
     return NeotestAdapter
   end,
 })