Add basic lua tests

.github/actions/test-neovim-lua/action.yml

@@ -0,0 +1,19 @@
+name: "Neovim Lua Tests"
+description: "Set up Neovim Lua environment and run Busted tests"
+runs:
+  using: "composite"
+  steps:
+    - uses: leafo/gh-actions-lua@v9
+      with:
+        luaVersion: "luajit-2.1.0-beta3"
+    - uses: leafo/gh-actions-luarocks@v4
+      with:
+        luaVersion: "5.1"
+    - shell: bash
+      run: |
+        luarocks install busted
+        luarocks install luafilesystem
+    - shell: bash
+      run: |
+        cd cursorless.nvim
+        busted --run unit

.github/workflows/test.yml

@@ -56,6 +56,8 @@ jobs:
         if: runner.os == 'Linux' && matrix.app_version == 'stable'
         env:
           NEOVIM_PATH: ${{ steps.vim.outputs.executable }}
+      - uses: ./.github/actions/test-neovim-lua/
+        if: runner.os == 'Linux' && matrix.app_version == 'stable'
       - name: Create vscode dist that can be installed locally
         run: pnpm -F @cursorless/cursorless-vscode populate-dist --local-install
         if: runner.os == 'Linux' && matrix.app_version == 'stable'

.vscode/tasks.json

@@ -287,6 +287,14 @@
       // NOTE: We don't have a way on Windows atm due to command with argument inside Run() not working
       // so we need to show logs outside of vscode (see #2454)
     },
+    {
+      "label": "Neovim: Test Lua",
+      "type": "shell",
+      "command": "busted --run unit",
+      "options": {
+        "cwd": "cursorless.nvim"
+      }
+    },
 
     // cursorless.org
     {

cursorless.nvim/.busted

@@ -0,0 +1,8 @@
+return {
+    _all = {
+        lua = './test/nvim-shim.sh'
+    },
+    unit = {
+        ROOT = {'./test/unit/'},
+    },
+}

cursorless.nvim/lua/cursorless/cursorless.lua

@@ -49,14 +49,9 @@ function M.buffer_get_selection()
 end
 
 -- https://github.com/nvim-treesitter/nvim-treesitter/blob/master/lua/nvim-treesitter/ts_utils.lua#L278
--- luacheck:ignore 631
--- https://github.com/nvim-treesitter/nvim-treesitter-textobjects/blob/master/lua/nvim-treesitter/textobjects/select.lua#L114
--- as an example if you put that in a vim buffer and do the following you can do a selection:
--- :w c:\work\tmp\test.lua
--- :so %
--- :lua select_range(5, 12, 5, 30)
--- for example it will highlight the last function name (nvim_win_set_cursor).
--- another example is :tmap <c-b> <Cmd>lua require("talon.cursorless").select_range(4, 0, 4, 38)<Cr>
+-- If you have a buffer with the line: "hello world"
+-- :lua require("cursorless.cursorless").select_range(1, 2, 1, 4)
+-- will highlight "llo"
 -- NOTE: works for any mode (n,i,v,nt) except in t mode
 function M.select_range(start_line, start_col, end_line, end_col)
   vim.cmd([[normal! :noh]])

cursorless.nvim/test/helpers.lua

@@ -0,0 +1,16 @@
+-- This file gets linked into plugin/helpers.lua of busted nvim config
+-- Functions that are exposed to all tests
+
+function _G.get_selected_text()
+  local _, ls, cs = unpack(vim.fn.getpos("v"))
+  local _, le, ce = unpack(vim.fn.getpos("."))
+  return vim.api.nvim_buf_get_text(0, ls - 1, cs - 1, le - 1, ce, {})
+end
+
+function _G.convert_table_entries(tbl, func)
+  local mapped = {}
+  for k, v in pairs(tbl) do
+    mapped[k] = func(v)
+  end
+  return mapped
+end

cursorless.nvim/test/nvim-shim.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if ! [[ "${PWD}" == *"cursorless.nvim" ]]; then
+  echo "ERROR: This script must be run from inside cursorless.nvim/ directory"
+  exit 1
+fi
+
+test_folder=$(mktemp -d "${TMPDIR-/tmp}"/cursorless-busted-test-XXXXX)
+export XDG_CONFIG_HOME="${test_folder}/xdg/config/"
+export XDG_STATE_HOME="${test_folder}/xdg/local/state/"
+export XDG_DATA_HOME="${test_folder}/xdg/local/share/"
+dependency_folder="${XDG_DATA_HOME}/nvim/site/pack/testing/start/"
+plugin_folder="${XDG_CONFIG_HOME}/nvim/plugin/"
+
+mkdir -p "${plugin_folder}" "${XDG_STATE_HOME}" "${dependency_folder}"
+ln -sf "${PWD}" "${dependency_folder}/cursorless.nvim"
+
+# Link in standalone helper functions we want all tests to be able to call
+ln -sf "${PWD}/test/helpers.lua" "${plugin_folder}/helpers.lua"
+
+# shellcheck disable=SC2068
+command nvim --cmd 'set loadplugins' -l $@
+exit_code=$?
+
+rm -rf "${test_folder}"
+
+exit $exit_code

cursorless.nvim/test/unit/cursorless_spec.lua

@@ -0,0 +1,88 @@
+describe("cursorless.nvim tests", function()
+  local cursorless = require("cursorless.cursorless")
+
+  describe("window_get_visible_lines()", function()
+    it("Can read one visible line", function()
+      local pos = vim.api.nvim_win_get_cursor(0)[2]
+      local line = vim.api.nvim_get_current_line()
+      local nline = line:sub(0, pos) .. "hello" .. line:sub(pos + 1)
+      vim.api.nvim_set_current_line(nline)
+
+      local visible = cursorless.window_get_visible_lines()
+      assert(table.concat(visible) == table.concat({ 1, 1 }))
+    end)
+
+    it("Can read all lines visible on the window", function()
+      local maxlines = vim.api.nvim_win_get_height(0)
+      local lines = {}
+      for _ = 1, (maxlines + 1) do
+        table.insert(lines, "hello ")
+      end
+      vim.api.nvim_buf_set_lines(0, 0, -1, false, lines)
+      local visible = cursorless.window_get_visible_lines()
+      assert(table.concat(visible) == table.concat({ 1, maxlines }))
+    end)
+  end)
+  describe("select_range()", function()
+    it("Selects the specified range", function()
+      local lines = "hello world"
+      vim.api.nvim_buf_set_lines(0, 0, -1, false, vim.split(lines, "\n"))
+      cursorless.select_range(1, 2, 1, 4)
+
+      assert(table.concat(_G.get_selected_text()) == "llo")
+    end)
+  end)
+  describe("buffer_get_selection()", function()
+    it(
+      "Can get the forward selection in a format expected by cursorless",
+      function()
+        local lines = "hello world"
+        vim.api.nvim_buf_set_lines(0, 0, -1, false, vim.split(lines, "\n"))
+        cursorless.select_range(1, 2, 1, 4)
+        assert(
+          table.concat(
+            _G.convert_table_entries(
+              cursorless.buffer_get_selection(),
+              tostring
+            ),
+            ", "
+          )
+            == table.concat(
+              _G.convert_table_entries({ 1, 3, 1, 5, false }, tostring),
+              ", "
+            )
+        )
+      end
+    )
+    it(
+      "Can get the backward selection in a format expected by cursorless",
+      function()
+        local lines = "hello world"
+        vim.api.nvim_buf_set_lines(0, 0, -1, false, vim.split(lines, "\n"))
+        cursorless.select_range(1, 4, 1, 2)
+        print(
+          table.concat(
+            _G.convert_table_entries(
+              cursorless.buffer_get_selection(),
+              tostring
+            ),
+            ", "
+          )
+        )
+        assert(
+          table.concat(
+            _G.convert_table_entries(
+              cursorless.buffer_get_selection(),
+              tostring
+            ),
+            ", "
+          )
+            == table.concat(
+              _G.convert_table_entries({ 1, 3, 1, 5, true }, tostring),
+              ", "
+            )
+        )
+      end
+    )
+  end)
+end)

docs/contributing/architecture/tests.md

@@ -31,7 +31,8 @@ packages/test-harness/src/config/init.lua
   -> TestHarnessRun() -> run() -> runAllTests() -> Mocha + packages/cursorless-neovim-e2e/src/suite/recorded.neovim.test.ts
 ```
 
-4. **Lua unit tests for neovim**: tests lua functions. They need to be executed in neovim. There is no such test for VSCode because we assume the functions provided by [VSCode APIs](https://code.visualstudio.com/api/references/vscode-api) have already been tested by Microsoft and work properly
+4. **Lua unit tests for neovim**: tests lua functions implemented in cursorless.nvim. These tests are
+   executed inside neovim.
 
 5. **Cursorless tests for Talon**: XXX
 
@@ -293,7 +294,26 @@ NOTE: CI uses `dist/cursorless.nvim/` (and not `cursorless.nvim/`), since the sy
 
 ## 4. Lua unit tests for neovim
 
-XXX
+Many of the cursorless.nvim lua functions are run in order to complete cursorless actions and so are already
+indirectly tested by the tests described in the [prevous section](#3.-cursorless-tests-for-neovim). Nevertheless, we run
+more specific unit tests in order to give better visibility into exactly which functions are failing.
+
+The [busted](https://github.com/lunarmodules/busted) framework is used to test lua functions defined in cursorless.nvim.
+This relies on a `./cursorless.nvim/.busted` file which directs busted to use a shell wrapper
+`.cursorless.nvim/test/nvim-shim.sh` as its lua interpreter. It also declares that test specifications files are in
+`./cursorless.nvim/test/unit/`. Any file in that folder ending with `_spec.lua` contains tests and will be executed
+by neovim's lua interpreter, which allows neovim's internal API to be exposed to the tests.
+
+The `nvim-shim.sh` script sets up an enclosed neovim environment by using [XDG Base
+Directory](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) environment variables (Linux
+only) pointing to a temp directory. This allows loading any helpers and (optional) plugins needed to run
+the tests.
+
+Afterwards, the shim will used `nvim` to execute whatever test spec file was passed by busted. Different tests rely on
+the same custom helper functions. These functions are exposed as globals in a file called `helpers.lua` placed in `nvim/plugin/` insnide the isolated XDG environment. These helpers themselves also have their own unit tests that will be run by busted.
+
+This busted setup was inspired by this [blog
+post](https://hiphish.github.io/blog/2024/01/29/testing-neovim-plugins-with-busted/), which goes into greater detail.
 
 ## 5. Cursorless tests for Talon
 

docs/contributing/cursorless-in-neovim.md

@@ -12,7 +12,7 @@ Follow the steps in [CONTRIBUTING.md](./CONTRIBUTING.md#initial-setup).
 
 Follow the installation steps in [cursorless.nvim](https://github.com/hands-free-vim/cursorless.nvim/tree/main#prerequisites).
 
-Confirm that production cursorless.nvim is working in neovim, eg say `"take first paint"` in a nonempty document.
+Confirm that production cursorless.nvim is working in neovim, eg say `"take first paint"` in a non-empty document.
 
 ### 3. Add nvim executable path to your PATH
 
@@ -40,7 +40,13 @@ debug mode. To do so you need to run the `workbench.action.debug.selectandstart`
 
 The debug logs are written in `C:\path\to\cursorless\packages\cursorless-neovim\out\nvim_node.log`.
 
-NOTE: This will spawn a standalone nvim instance that is independent of VSCode. Consequently after you're done debugging, you need to close nvim.
+NOTE: This will spawn a standalone nvim instance that is independent of VSCode. Consequently after you're done
+debugging, you need to close nvim.
+
+### Running lua tests
+
+Their are separate cursorless and lua tests. You can run the lua tests by entering the `cursorless.nvim` folder and
+running: `busted --run unit`. These tests currently only work on Linux.
 
 ## Sending pull requests
 

flake.nix

@@ -76,7 +76,10 @@
                   '';
                 }))
                 python
+
                 pkgs.neovim
+                pkgs.luajitPackages.busted # for lua testing
+                pkgs.luarocks # pre-commit doesn't auto-install luarocks
               ];
             # To prevent weird broken non-interactive bash terminal
             buildInputs = [ pkgs.bashInteractive ];

init.lua

@@ -10,7 +10,7 @@ if not (vim.uv or vim.loop).fs_stat(lazypath) then
     lazypath,
   })
 end
-vim.opt.rtp:prepend(lazypath)
+vim.opt.runtimepath:prepend(lazypath)
 require("lazy").setup({
   -- Allows title detection by neovim-talon while testing
   "hands-free-vim/talon.nvim",