neotest-playwright

A playwright adapter for neotest.

Written in typescript and transpiled to Lua using tstl.

Features

• 🎭 Discover, run, and parse the output of playwright tests
• ⌨️ Quick launch test attachments ( 🕵️ trace, 📼 video)
• 💅 Project selection + persistence
• ⚙️ On-the-fly presets

---

Demo

neotest-playwright-demo.mp4

---

Table of contents

• neotest-playwright
  • Features
  • Demo
  • Table of contents
  • Installation
  • Configuration
  • Projects
  • Presets
    • headed
    • debug
    • none
  • Dynamic Test Discovery
    • Caveats
  • Consumers
    • Attachment
    • Consumers Configuration
  • Performance
  • Troubleshooting
  • Credits

Installation

Using packer:

use({
  "nvim-neotest/neotest",
  requires = {
    -- ...
    "thenbe/neotest-playwright",
  },
  config = function()
    require("neotest").setup({
      -- ...
      adapters = {
        require("neotest-playwright").adapter({
          options = {
            persist_project_selection = true,
            enable_dynamic_test_discovery = true,
          }
        }),
      },
    })
  end,
})

Configuration

require("neotest-playwright").adapter({
  -- default values shown
  options = {
    persist_project_selection = false,

    enable_dynamic_test_discovery = false,

    preset = "none", -- "none" | "headed" | "debug"

    -- get_playwright_binary = function()
    --   return vim.loop.cwd() + "/node_modules/.bin/playwright"
    -- end,

    -- get_playwright_config = function()
    --   return vim.loop.cwd() + "/playwright.config.ts"
    -- end,

    -- Controls the location of the spawned test process.
    -- Has no affect on neither the location of the binary nor the location of the config file.
    -- get_cwd = function()
    --   return vim.loop.cwd()
    -- end,

    -- env = { },

    -- Extra args to always passed to playwright. These are merged with any extra_args passed to neotest's run command.
    -- extra_args = { },

    -- Filter directories when searching for test files. Useful in large projects (see performance notes).
    -- filter_dir = function(name, rel_path, root)
    --   return name ~= "node_modules"
    -- end,

    -- Custom criteria for a file path to be a test file. Useful in large projects or projects with peculiar tests folder structure.
    -- is_test_file = function(file_path)
    --     -- By default, neotest-playwright only returns true if a file contains one of several file extension patterns.
    --     -- See default implementation here: https://github.com/thenbe/neotest-playwright/blob/c036fe39469e06ae70b63479b5bb2ce7d654beaf/src/discover.ts#L25-L47
    --     return string.match(file_path, "my-project's-vitest-tests-folder")
    -- end,
  },
})

---

Projects

neotest-playwright allows you to conveniently toggle your playwright Projects on and off. To activate (or deactivate) a project, use the :NeotestPlaywrightProject command. neotest-playwright will only include the projects you've activated in any subsequent playwright commands (using the --project flag). Your selection will persist until you either change it with :NeotestPlaywrightProject, or restart neovim.

If you wish, you can choose to persist your project selection across neovim sessions by setting persist_project_selection to true (see example). Selection data is keyed by the project's root directory, meaning you can persist multiple distinct selections across different projects (or git worktrees).

---

Presets

Presets can help you debug your tests on the fly. A preset is just a group of command line flags that come in handy in common scenarios.

To select a preset, use the :NeotestPlaywrightPreset command. Once a preset is selected, it remains active until you either select another preset, clear it by selecting the none preset, or restart neovim.

headed

Applies the following flags: --headed --retries 0 --timeout 0 --workers 1 --max-failures 0

Runs tests in headed mode.

💡 Tip: Use with await page.pause() to open the playwright inspector and debug your locators.

debug

Applies the following flags: --debug

Playwright uses the --debug flag as a shortcut for multiple options. See here for more information.

none

Does not apply any flags. Your tests will run as defined in your playwright.config.ts file.

---

Dynamic Test Discovery

neotest-playwright can make use of the playwright cli to unlock extra features. Most importantly, the playwright cli provides information about which tests belongs to which project. neotest-playwright will parse this information to display, run, and report the results of tests on a per-project basis.

To enable this, set enable_dynamic_test_discovery to true.

Caveats

This feature works by calling playwright test --list --reporter=json. While this is a relatively fast operation, it does add some overhead. Therefore, neotest-playwright only calls this feature once (when the adapter is first initialized). From then on, neotest-playwright continues to rely on treesitter to track your tests and enhance them with the data previously resolved by the playwright cli. There are times, however, where we want to refresh this data. To remedy this: neotest-playwright exposes a command :NeotestPlaywrightRefresh. This comes in handy in the following scenarios:

• Adding a new test
• Renaming a test
• Changing the project(s) configuration in your playwright.config.ts file

Consumers

Attachment

Displays the attachments for the test under the cursor. Upon selection, the attachment is launched.

neotest-playwright-test-attachment-2.mp4

Consumers Configuration

Requires enable_dynamic_test_discovery = true.

1. Include the consumer in your neotest setup:

   require("neotest").setup({
     consumers = {
       -- add to your list of consumers
       playwright = require("neotest-playwright.consumers").consumers,
     },
   })

2. Add keybinding:

   {
     "thenbe/neotest-playwright",
     keys = {
       {
         "<leader>ta",
         function()
           require("neotest").playwright.attachment()
         end,
         desc = "Launch test attachment",
       },
     },
   }

Performance

Use filter_dir option to limit directories to be searched for tests.

---Filter directories when searching for test files
---@async
---@param name string Name of directory
---@param rel_path string Path to directory, relative to root
---@param root string Root directory of project
---@return boolean
filter_dir = function(name, rel_path, root)
  local full_path = root .. "/" .. rel_path

  if root:match("projects/my-large-monorepo") then
    if full_path:match("^packages/site/test") then
      return true
    else
      return false
    end
  else
    return name ~= "node_modules"
  end
end

Troubleshooting

testDir should be defined in playwright.config.ts.

Credits

• neotest-jest