DOCSEARCHbyAlgolia
Submit Docs

plenary.nvim Documentation

repository·master·Indexed 25 days ago

https://github.com/nvim-lua/plenary.nvim

A collection of Lua utility modules for Neovim plugin developers, featuring a Busted-style testing framework, asynchronous execution helpers, and mocking and stubbing capabilities via luassert.

Tokens
1.1K
Snippets
5
Records
5
Agent score
36%

What's inside plenary.nvim

  1. Run tests via Neovim commands

    master

    You can execute tests directly from Neovim using the following commands:

    • :PlenaryBustedFile <file>: Runs the test file in the current buffer.
    • :PlenaryBustedDirectory <dir>: Runs all tests within the specified directory.
    " Run the test in the current buffer
:PlenaryBustedFile %

" Run all tests in the directory "tests/plenary/"
:PlenaryBustedDirectory tests/plenary/

  2. Write basic tests using describe and it

    master

    Plenary.nvim provides a Busted-style testing syntax. You can group tests using describe blocks, define individual tests with it blocks, and use before_each to run setup code before every test within a block. Use assert.equals(expected, actual) for assertions.

    describe("some basics", function()
  local bounter

  before_each(function()
    bounter = 0
  end)

  it("some test", function()
    bounter = 100
    assert.equals("bello Brian", bello("Brian"))
  end)

  it("some other test", function()
    assert.equals(0, bounter)
  end)
end)

  3. Perform asynchronous testing

    master

    Tests in Plenary run inside a coroutine. To test asynchronous code (like vim.defer_fn), you can capture the current coroutine using coroutine.running(), yield the test execution with coroutine.yield(), and resume the coroutine from within your asynchronous callback.

    local co = coroutine.running()
vim.defer_fn(function()
  coroutine.resume(co)
end, 1000)

-- The test will reach here immediately.
coroutine.yield()
-- The test will only reach here after one second, when the deferred function runs.

  4. Mock and stub functions with luassert

    master

    Plenary.nvim includes luassert, which provides tools for mocking and stubbing.

    • Mocking: Use require('luassert.mock') to create a full mock of a module. You can set return values using .returns() and verify calls using assert.stub(mocked_func).was_called_with(...). Always call mock.revert(api) to restore the original module.
    • Stubbing: Use require('luassert.stub') to replace a single function within a module without mocking the entire object.
    local mock = require('luassert.mock')
local stub = require('luassert.stub')

-- Mocking example
describe("example", function()
  it("Should make expected calls to api, fully mocked", function()
    local api = mock(vim.api, true)
    api.nvim_create_buf.returns(5)

    -- call code that uses api...

    assert.stub(api.nvim_create_buf).was_called_with(false, true)
    assert.stub(api.nvim_command).was_called_with("sbuffer 5")

    mock.revert(api)
  end)

  -- Stubbing example
  it("Should mock single api call", function()
    stub(vim.api, "nvim_command")
    -- call code that uses vim.api.nvim_command...
  end)
end)