neotest-phpunit

This plugin provides a PHPUnit adapter for the Neotest framework.

:package: Installation

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
})

:wrench: Configuration

Default configuration

[!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" },
    filterdirs = { ".git", "nodemodules" },
    env = {}, -- for example {XDEBUG_CONFIG = 'idekey=neotest'}
    dap = nil, -- to configure dap strategy put single element from dap.configurations.php
  }),
}

The test command

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
})

Setting the root directory

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 rootignorefiles 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")({
    rootignorefiles = { "tests/Pest.php" }
})

Filtering directories

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
})

Debugging

The plugin can also be used for debugging via a dap strategy.

Firstly, install and configure nvim-dap with vscode-php-debug. Then set the following dap configuration:

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,
      },
    },
  }
}

Then in the plugin's config, add:

require("neotest-phpunit")({
  env = {
      XDEBUG_CONFIG = "idekey=neotest",
  },
  dap = dap.configurations.php[1],
})

[!NOTE]

If you run a test with the dap strategy from the summary window (by default by d) and see that the window content has been replaced by debugger content then consider setting dap.defaults.fallback.switchbuf = "useopen" or Neovim level switchbuf

:rocket: Usage

Test single method

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

Test file

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

Test directory

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

Test suite

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

:gift: Contributing

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