feat: modernize testing infrastructure with plenary.nvim (#12)

Replace custom test runner with plenary.nvim framework for better maintainability and standard Neovim plugin testing patterns.
Add justfile for development tasks, luacheck configuration, and matrix CI testing for stable/nightly Neovim versions.

Author: alexekdahl

.github/workflows/test.yml

@@ -8,6 +8,9 @@ on:
 
 jobs:
   test:
+    strategy:
+      matrix:
+        neovim-version: ['stable', 'nightly']
     runs-on: ubuntu-latest
 
     steps:
@@ -17,7 +20,14 @@ jobs:
         uses: rhysd/action-setup-vim@v1
         with:
           neovim: true
-          version: stable
+          version: ${{ matrix.neovim-version }}
+      
+      - name: Install plenary.nvim
+        run: |
+          mkdir -p ~/.local/share/nvim/lazy/plenary.nvim
+          git clone --depth=1 https://github.com/nvim-lua/plenary.nvim.git ~/.local/share/nvim/lazy/plenary.nvim
       
       - name: Run tests
-        run: nvim --headless -c "luafile tests/integration_test.lua" -c "qa!"
+        run: |
+          nvim --headless --noplugin -u tests/minimal_init.lua \
+            -c "lua require('plenary.test_harness').test_directory('tests', {minimal_init = 'tests/minimal_init.lua'})"

.luacheckrc

@@ -0,0 +1,38 @@
+std = "luajit"
+
+globals = {
+	"vim",
+}
+
+read_globals = {
+	"vim",
+}
+
+exclude_files = {
+	".luarocks",
+	"lua_modules",
+	"tests/minimal_init.lua",
+}
+
+ignore = {
+	"212", -- Unused argument
+	"213", -- Unused loop variable
+	"431", -- Shadowing upvalue
+	"432", -- Shadowing upvalue argument
+}
+
+max_line_length = 100
+max_cyclomatic_complexity = 15
+
+files = {
+	"lua/marksman/",
+	"tests/",
+}
+
+files["tests/"] = {
+	ignore = {
+		"211", -- Unused local variable
+		"212", -- Unused argument
+		"213", -- Unused loop variable
+	},
+}

CONTRIBUTING.md

@@ -14,7 +14,27 @@ Thank you for your interest in contributing to Marksman.nvim! This document prov
 ### Prerequisites
 - Neovim >= 0.8.0
 - Git
-- Lua 5.1+ (for testing outside Neovim)
+- [just](https://github.com/casey/just) command runner (or make)
+- [plenary.nvim](https://github.com/nvim-lua/plenary.nvim) for testing
+
+### Quick Start
+```bash
+# Install dependencies
+just install-deps
+
+# Run tests
+just test
+
+# Run specific test
+just test-file tests/marksman_spec.lua
+
+# Watch tests (requires entr)
+just test-watch
+
+# Lint and format
+just lint
+just format
+```
 
 ### Code Quality Tools
 ```bash
@@ -25,10 +45,10 @@ luarocks install luacheck
 cargo install stylua
 
 # Run linting
-luacheck lua/
+just lint
 
 # Run formatting
-stylua lua/
+just format
 ```
 
 ## Code Style
@@ -64,6 +84,10 @@ lua/marksman/
 ├── storage.lua   -- Mark persistence and project management
 ├── ui.lua        -- Floating window and interface
 └── utils.lua     -- Utilities and validation
+
+tests/
+├── minimal_init.lua    -- Test environment setup
+└── marksman_spec.lua   -- Main test suite
 ```
 
 ## Contribution Types
@@ -77,7 +101,7 @@ lua/marksman/
 ### New Features
 1. **Discuss the feature** in an issue first
 2. **Ensure it aligns** with the plugin's focused scope
-3. **Write comprehensive documentation**
+3. **Write comprehensive tests**
 4. **Add configuration options** if needed
 
 ### Documentation
@@ -87,11 +111,35 @@ lua/marksman/
 
 ## Testing Guidelines
 
-### Manual Testing
-- Test with **multiple projects**
-- Verify **mark persistence** across sessions
-- Test **edge cases** (empty files, special characters)
-- Check **memory usage** with large mark sets
+### Test Framework
+We use [plenary.nvim](https://github.com/nvim-lua/plenary.nvim) for testing with a describe/it structure:
+
+```lua
+describe("feature", function()
+    before_each(function()
+        -- Setup code
+    end)
+    
+    it("does something", function()
+        assert.is_true(some_condition)
+    end)
+end)
+```
+
+### Running Tests
+```bash
+# Run all tests
+just test
+
+# Run specific test file
+just test-file tests/marksman_spec.lua
+
+# Watch tests (auto-run on file changes)
+just test-watch
+
+# Clean test artifacts
+just clean
+```
 
 ### Test Scenarios
 1. **Basic Operations**:
@@ -113,6 +161,12 @@ lua/marksman/
    - Keyboard navigation
    - Search and filtering
 
+### Writing Tests
+- Use descriptive test names
+- Test both success and failure cases
+- Clean up resources in `after_each`
+- Mock external dependencies when needed
+
 ## Performance Considerations
 
 ### Memory Efficiency
@@ -190,9 +244,10 @@ require("marksman").setup({
 
 ### Before Submitting
 1. **Test thoroughly** on your system
-2. **Run linting** and fix issues
-3. **Update documentation** if needed
-4. **Rebase on main** branch
+2. **Run linting** and fix issues: `just lint`
+3. **Format code**: `just format`
+4. **Update documentation** if needed
+5. **Rebase on main** branch
 
 ### PR Description Template
 ```markdown

justfile

@@ -0,0 +1,44 @@
+# Install plenary.nvim if not present
+install-deps:
+    #!/usr/bin/env bash
+    if [ ! -d "$HOME/.local/share/nvim/lazy/plenary.nvim" ]; then
+        echo "Installing plenary.nvim..."
+        mkdir -p "$HOME/.local/share/nvim/lazy/plenary.nvim"
+        git clone --depth=1 https://github.com/nvim-lua/plenary.nvim.git "$HOME/.local/share/nvim/lazy/plenary.nvim"
+    fi
+
+# Run all tests
+test: install-deps
+    nvim --headless --noplugin -u tests/minimal_init.lua \
+        -c "lua require('plenary.test_harness').test_directory('tests', {minimal_init = 'tests/minimal_init.lua'})"
+
+# Run specific test file
+test-file FILE: install-deps
+    nvim --headless --noplugin -u tests/minimal_init.lua \
+        -c "lua require('plenary.busted').run('{{FILE}}')"
+
+# Watch tests (requires entr: brew install entr or apt install entr)
+test-watch:
+    find lua/ tests/ -name "*.lua" | entr -c just test
+
+# Clean test artifacts
+clean:
+    rm -rf /tmp/*marksman_test*
+
+# Lint code
+lint:
+    #!/usr/bin/env bash
+    if command -v luacheck >/dev/null; then
+        luacheck lua/
+    else
+        echo "luacheck not found. Install with: luarocks install luacheck"
+    fi
+
+# Format code
+format:
+    #!/usr/bin/env bash
+    if command -v stylua >/dev/null; then
+        stylua lua/ tests/
+    else
+        echo "stylua not found. Install with: cargo install stylua"
+    fi

lua/marksman/storage.lua

@@ -29,7 +29,7 @@ end
 ---@return string project_root The project root directory
 local function get_project_root()
 	local current_dir = vim.fn.expand("%:p:h")
-	
+
 	-- Check cache first (expires after 30 seconds)
 	local cache_key = current_dir
 	local now = os.time()
@@ -103,13 +103,13 @@ local function get_marks_file()
 	if not project then
 		error("Could not determine project root")
 	end
-	
+
 	local hash = vim.fn.sha256(project):sub(1, 8)
 	local data_path = vim.fn.stdpath("data")
 	if not data_path then
 		error("Could not get Neovim data directory")
 	end
-	
+
 	return data_path .. "/marksman_" .. hash .. ".json"
 end
 
@@ -174,26 +174,26 @@ local function validate_marks_data(data)
 		if type(name) ~= "string" or name == "" then
 			return false, "Mark names must be non-empty strings"
 		end
-		
+
 		if type(mark) ~= "table" then
 			return false, "Mark data must be a table"
 		end
-		
+
 		local required_fields = { "file", "line", "col" }
 		for _, field in ipairs(required_fields) do
 			if not mark[field] then
 				return false, "Missing required field: " .. field
 			end
 		end
-		
+
 		if type(mark.line) ~= "number" or mark.line < 1 then
 			return false, "Line must be a positive number"
 		end
-		
+
 		if type(mark.col) ~= "number" or mark.col < 1 then
 			return false, "Column must be a positive number"
 		end
-		
+
 		if type(mark.file) ~= "string" or mark.file == "" then
 			return false, "File must be a non-empty string"
 		end
@@ -298,7 +298,7 @@ function M.save_marks()
 			saved_at = os.date("%Y-%m-%d %H:%M:%S"),
 			project = current_project,
 		}
-		
+
 		local json = vim.json.encode(data)
 		if not json then
 			error("Failed to encode marks data")
@@ -608,7 +608,7 @@ function M.import_marks()
 							for name, mark in pairs(data.marks) do
 								marks_data[name] = mark
 							end
-							
+
 							-- Merge order arrays, avoiding duplicates
 							if data.mark_order then
 								for _, name in ipairs(data.mark_order) do
@@ -665,7 +665,7 @@ function M.cleanup()
 	-- Clear caches
 	project_root_cache = {}
 	cache_expiry = {}
-	
+
 	-- Reset state
 	marks = {}
 	mark_order = {}