Build comprehensive test suite with local CI script

Overview

Build a comprehensive test suite for markdown-toc.nvim along with a run-ci-locally.sh script that runs all tests locally before pushing changes.

Objectives

  1. Test Suite: Implement comprehensive tests covering all plugin functionality
  2. Local CI Script: Create run-ci-locally.sh to run tests pre-push
  3. CI Integration: Ensure tests can run in GitHub Actions workflow

Test Coverage Areas

Core Functionality Tests

  • TOC Generation (lua/mtoc/toc.lua)

    • Generate TOC from various heading structures
    • Handle duplicate headings (suffix -1, -2, etc.)
    • Test different heading patterns and formats
    • Validate GitHub Flavored Markdown link formatting

  • Fence Detection & Management (lua/mtoc/toc.lua)

    • Find and parse fence markers (<!-- mtoc-start -->, <!-- mtoc-end -->)
    • Extract max-depth parameter from fence comments
    • Handle missing or malformed fences

  • Code Block Awareness

    • Ignore headings inside triple-backtick code blocks
    • Handle nested code blocks correctly

  • Heading Parsing

    • Parse headings with various ATX formats (#, ##, etc.)
    • Respect max_depth configuration
    • Apply headings.exclude patterns and functions
    • Handle headings.before_toc option

Configuration Tests (lua/mtoc/config.lua)

  • Deep merge user options with defaults
  • Validate all configuration options
  • Test various toc_list.markers formats (string, list, cycling)
  • Test indent_size as integer and function

Command Tests (lua/mtoc/init.lua)

  • :Mtoc - Generate and insert TOC
  • :Mtoc insert - Force insert mode
  • :Mtoc update - Update existing TOC
  • :Mtoc remove - Remove TOC
  • Command with ! suffix (force fence generation)
  • Visual range selection :'<,'>Mtoc

Utility Tests (lua/mtoc/utils.lua)

  • Line insertion and deletion
  • Current line detection
  • Helper function edge cases

Auto-update Tests

  • BufWritePre autocmd triggers TOC update
  • Respects auto_update.enabled configuration

Test Framework Options

Consider using one of:

  • plenary.nvim - Popular Neovim plugin testing framework
  • busted - Lua unit testing framework
  • luaunit - Lightweight Lua testing

run-ci-locally.sh Requirements

The script should:

  1. Check for required dependencies (Neovim, test framework)
  2. Run all tests with appropriate Neovim configuration
  3. Report test results with clear pass/fail status
  4. Exit with non-zero code on test failure
  5. Be executable: chmod +x run-ci-locally.sh
  6. Support optional arguments (e.g., --verbose, specific test files)

Example structure:

#!/bin/bash
set -e

echo "Running markdown-toc.nvim test suite..."

# Check dependencies
command -v nvim >/dev/null 2>&1 || { echo "Neovim not found"; exit 1; }

# Run tests
nvim --headless -u tests/minimal_init.lua -c "PlenaryBustedDirectory tests/ {minimal_init = 'tests/minimal_init.lua'}"

echo "All tests passed!"

CI Integration

  • Update .github/workflows/ to run tests on push/PR
  • Ensure tests run in CI environment with appropriate Neovim version
  • Consider testing against multiple Neovim versions (nightly, stable)

Documentation

  • Add testing section to README.md
  • Document how to run tests locally
  • Document test structure and how to add new tests
  • Add pre-commit hook example for developers

Success Criteria

  • Comprehensive test coverage (>80% of core functionality)
  • run-ci-locally.sh script runs all tests successfully
  • CI workflow includes test execution
  • Documentation updated with testing instructions
  • All existing functionality passes tests