test: draft nvim functional testing

.github/workflows/ci.yml

@@ -98,3 +98,42 @@ jobs:
 
       - run: make help-check
         if: ${{ matrix.nvim_version == 'stable' }}
+
+  functionaltest:
+    runs-on: ubuntu-latest
+
+    concurrency:
+      group: ${{ github.workflow }}-${{ matrix.nvim_version }}-${{ matrix.luals_version }}-${{ github.head_ref || github.ref_name }}
+      cancel-in-progress: true
+
+    strategy:
+      matrix:
+        nvim_version: [ stable, nightly ]
+        luals_version: [ 3.15.0 ]
+
+    env:
+      VIMRUNTIME: /home/runner/nvim-${{ matrix.nvim_version }}/share/nvim/runtime
+      DIR_NVIM_SRC: /home/runner/src/neovim-${{ matrix.nvim_version }}
+
+    steps:
+      - name: checkout
+        uses: actions/checkout@v7
+
+      - name: install lua-language-server ${{ matrix.luals_version }}
+        run: |
+          mkdir -p luals
+          curl -L "https://github.com/LuaLS/lua-language-server/releases/download/${{ matrix.luals_version }}/lua-language-server-${{ matrix.luals_version }}-linux-x64.tar.gz" | tar zx --directory luals
+          echo "luals/bin" >> "$GITHUB_PATH"
+
+      - name: build Nvim from source
+        run: |
+          mkdir -p "${DIR_NVIM_SRC}"
+          curl -L "https://github.com/neovim/neovim/archive/refs/tags/${{ matrix.nvim_version }}.tar.gz" | tar zx --directory "${DIR_NVIM_SRC}/.."
+          cd "${DIR_NVIM_SRC}"
+          make
+
+      - run: scripts/functionaltest.sh -a
+
+      - run: scripts/luals-check.sh test
+
+      - run: scripts/luals-check.sh codestyle-check test

.luacheckrc

@@ -4,12 +4,25 @@ local M = {}
 M.self = false
 
 M.ignore = {
-  "631",  -- max_line_length
+  "631", -- max_line_length
 }
 
--- Global objects defined by the C code
 M.globals = {
+  -- Global objects defined by the C code
   "vim",
+  -- Global neovim test functions
+  "it",
+  "describe",
+  "pending",
+  "setup",
+  "before_each",
+  "after_each",
+  "teardown",
+  "finally",
+  -- Global nvt functiontest fixtures
+  "NVT_FUNCTEST_CONTEXT",
+  "NVT_FUNCTEST_EVENTS",
+  "NVT_FUNCTEST_CLIPBOARD_LINES",
 }
 
 return M

.luarc.json

@@ -4,7 +4,9 @@
   "workspace": {
     "library": [
       "$VIMRUNTIME/lua/vim",
-      "${3rd}/luv/library"
+      "${3rd}/luv/library",
+      "$DIR_NVIM_SRC/test",
+      "/tmp/src/neovim-stable/test"
     ]
   },
   "format": {
@@ -21,7 +23,11 @@
   },
   "diagnostics": {
     "libraryFiles": "Disable",
-    "globals": [],
+    "globals": [
+      "NVT_FUNCTEST_CONTEXT",
+      "NVT_FUNCTEST_EVENTS",
+      "NVT_FUNCTEST_CLIPBOARD_LINES"
+    ],
     "neededFileStatus": {
       "ambiguity-1": "Any",
       "assign-type-mismatch": "Any",

Makefile

@@ -1,3 +1,5 @@
+# TODO functest move any checks from ci.yml into here, adding any missing e.g. codeformat
+
 all: lint style check
 
 #
@@ -14,15 +16,18 @@ check: luals
 #
 luacheck:
 	luacheck --codes --quiet lua --exclude-files "**/_meta/**"
+	luacheck --codes --quiet test
 
 style-check:
-	scripts/luals-check.sh codestyle-check
+	scripts/luals-check.sh codestyle-check lua
+	scripts/luals-check.sh codestyle-check scripts
 
 style-doc:
 	scripts/doc-comments.sh
 
 luals:
-	scripts/luals-check.sh
+	scripts/luals-check.sh lua
+	scripts/luals-check.sh scripts
 
 #
 # format
@@ -47,6 +52,5 @@ help-update:
 help-check: help-update
 	git diff --exit-code doc/nvim-tree-lua.txt
 
-
 .PHONY: all lint style check luacheck style-check style-doc luals format-fix format-check help-update help-check
 

doc/nvim-tree-lua.txt

@@ -1708,7 +1708,7 @@ Config: actions                                     *nvim-tree-config-actions*
       • {use_system_clipboard}?  (`boolean`, default: `true`) Use the system
                                  clipboard for copy/paste. Copied text will be
                                  stored in registers `+` (system), otherwise,
-                                 it will be stored in `1` and `"`
+                                 it will be stored in `1`
 
 *nvim_tree.config.actions.change_dir*
     vim |current-directory| behaviour

lua/nvim-tree/_meta/config/actions.lua

@@ -5,7 +5,7 @@ error("Cannot require a meta file")
 
 ---@class nvim_tree.config.actions
 ---
----Use the system clipboard for copy/paste. Copied text will be stored in registers `+` (system), otherwise, it will be stored in `1` and `"`
+---Use the system clipboard for copy/paste. Copied text will be stored in registers `+` (system), otherwise, it will be stored in `1`
 ---(default: `true`)
 ---@field use_system_clipboard? boolean
 ---

lua/nvim-tree/appearance/init.lua

@@ -182,8 +182,7 @@ M.LEGACY_LINKS = {
   NvimTreeDiagnosticHintFolderHL = "NvimTreeLspDiagnosticsHintFolderText",
 }
 
----Create all highlight groups and links. Idempotent.
-function M.highlight()
+local function highlight_main()
   -- non-linked
   for _, g in ipairs(M.HIGHLIGHT_GROUPS) do
     if g.def then
@@ -208,4 +207,57 @@ function M.highlight()
   end
 end
 
+---Create all NvimTree* highlight groups with just a unique foreground colour
+---NvimTreeCursorLine has just a background colour
+---Add a CL variant for each group with the same background colour as NvimTreeCursorLine
+---This is done here, as redefining groups in the test context is a performance issue, due to the number of :help ui-event-hl_attr_define events
+local function highlight_functest()
+  -- arbitrary cursor line "unique" value: math.random(tonumber('0x707070'),tonumber('0x909090'))
+  local hex_bg = "#85a450"
+
+  -- unique colour for each group, descending from #fefefe
+  local i, r, g, b = 1, 254, 254, 254
+  local rgb_fg, hex_fg
+
+  -- build the cursor line first, background only
+  local hgs = vim.tbl_filter(function(hg)
+    if hg.group == "NvimTreeCursorLine" then
+      vim.api.nvim_set_hl(0, "NvimTreeCursorLine", { bg = hex_bg })
+      return false
+    else
+      return true
+    end
+  end, M.HIGHLIGHT_GROUPS)
+
+  -- define the remainder with unique foregrounds
+  for _, hg in ipairs(hgs) do
+    -- next unique fg colour
+    rgb_fg = r * 256 * 256 + g * 256 + b
+    hex_fg = string.format("#%x", rgb_fg)
+    i = i + 1
+    if (i % 256 == 0) then
+      b, g, r = 254, 254, r - 1
+    elseif (i % 16 == 0) then
+      b, g = 254, g - 1
+    else
+      b = b - 1
+    end
+
+    -- add the group's concrete definition with fg only
+    vim.api.nvim_set_hl(0, hg.group, { fg = hex_fg })
+
+    -- create an NvimTreeCursorLine variant
+    vim.api.nvim_set_hl(0, hg.group .. "CL", { fg = hex_fg, bg = hex_bg })
+  end
+end
+
+---Create all highlight groups and links. Idempotent.
+function M.highlight()
+  if NVT_FUNCTEST_CONTEXT then ---@diagnostic disable-line: undefined-global
+    highlight_functest()
+  else
+    highlight_main()
+  end
+end
+
 return M

lua/nvim-tree/core.lua

@@ -67,8 +67,7 @@ function M.get_nodes_starting_line()
 end
 
 function M.purge_all_state()
-  view.close_all_tabs()
-  view.abandon_all_windows()
+  view.purge_state()
   if TreeExplorer then
     git.purge_state()
     TreeExplorer:destroy()

lua/nvim-tree/view.lua

@@ -354,6 +354,12 @@ function M.abandon_all_windows()
   end
 end
 
+function M.purge_state()
+  M.close_all_tabs()
+  M.abandon_all_windows()
+  view_state.Active.cursors = {}
+end
+
 ---@param opts table|nil
 ---@return boolean
 function M.is_visible(opts)

scripts/check-nvim-src.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env sh
+
+# common script to check the availability of neovim source
+# - NOP if $DIR_NVIM_SRC is defined
+# - sets $DIR_NVIM_SRC to /tmp/src/neovim-stable if present
+# - otherwise prompts with instructions 
+# script must be sourced to receive the exported $DIR_NVIM_SRC
+
+DIR_NVIM_SRC_DEF="/tmp/src/neovim-stable"
+
+if [ -z "${DIR_NVIM_SRC}" ] && [ -d "${DIR_NVIM_SRC_DEF}" ]; then
+	export DIR_NVIM_SRC="${DIR_NVIM_SRC_DEF}"
+fi
+
+if [ ! -d "${DIR_NVIM_SRC}" ]; then
+	cat << EOM
+
+Nvim stable source is required to run ${0}
+
+Unavailable: ${DIR_NVIM_SRC_DEF} or \$DIR_NVIM_SRC=${DIR_NVIM_SRC}
+
+Please:
+  mkdir -p ${DIR_NVIM_SRC_DEF}
+  curl -L 'https://github.com/neovim/neovim/archive/refs/tags/stable.tar.gz' | tar zx --directory $(dirname "${DIR_NVIM_SRC_DEF}")
+	or use your own e.g.
+  export DIR_NVIM_SRC="\${HOME}/src/neovim"
+
+EOM
+exit 1
+fi