This plugin provides a PHPUnit adapter for the Neotest framework.

⚠️ This plugin is still in the early stages of development. Please test against your PHPUnit tests ⚠️

Install with the package manager of your choice:

Lazy

{
  "nvim-neotest/neotest",
  lazy = true,
  dependencies = {
    ...,
    "olimorris/neotest-phpunit",
  },
  config = function()
    require("neotest").setup({
      ...,
      adapters = {
        require("neotest-phpunit")
      },
    }
  end
}

Packer

use({
  "nvim-neotest/neotest",
  requires = {
    ...,
    "olimorris/neotest-phpunit",
  },
  config = function()
    require("neotest").setup({
      ...,
      adapters = {
        require("neotest-phpunit"),
      }
    })
  end
})

Note: You only need to the call the setup function if you wish to change any of the defaults.

adapters = {
  require("neotest-phpunit")({
    phpunit_cmd = function()
      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" },
    env = {}, -- for example {XDEBUG_CONFIG = 'idekey=neotest'}
    dap = nil, -- to configure `dap` strategy put single element from `dap.configurations.php`
  }),
}

The command used to run tests can be changed via the phpunit_cmd option:

require("neotest-phpunit")({
  phpunit_cmd = function()
    return "vendor/bin/phpunit"
  end
})

For Neotest adapters to work, they need to define a project root whereby the process of discovering tests can take place. By default, the adapter looks for a composer.json, phpunit.xml or .gitignore file. These can be changed with:

require("neotest-phpunit")({
  root_files = { "README.md" }
})

You can even set root_files with a function which returns a table:

require("neotest-phpunit")({
  root_files = function() return { "README.md" } end
})

If there are projects you don't want discovered, you can instead set root_ignore_files to ignore any matching projects.

For example, if your project uses Pest and the appropriate neotest adapter, you'll need to set:

require("neotest-phpunit")({
    root_ignore_files = { "tests/Pest.php" }
})

By default, the adapter will search test files in all dirs in the root with the exception of node_modules and .git. You can change this with:

require("neotest-phpunit")({
  filter_dirs = { "vendor" }
})

You can even set filter_dirs with a function which returns a table:

require("neotest-phpunit")({
  filter_dirs = function() return { "vendor" } end
})

You need to install and configure nvim-dap with vscode-php-debug first. For example if you have

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

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, f.e.

dap.defaults.fallback.switchbuf = "useopen"

To test a single test, hover over the test and run lua require("neotest").run.run()

To test a file run lua require("neotest").run.run(vim.fn.expand("%"))

To test a directory run lua require("neotest").run.run("path/to/directory")

To test the full test suite run lua require("neotest").run.run({ suite = true })

This project is maintained by the Neovim PHP community. Please raise a PR if you are interested in adding new functionality or fixing any bugs. When submitting a bug, please include an example test that we can test against.

To trigger the tests for the adapter, run:

./scripts/test