What?

• neorocksTest is a nix function that allows you to run luarocks test with Neovim as the Lua interpreter.
• This project's README provides tutorials for using busted to test Neovim plugins (with and without Nix).

Why?

So you can use busted to test your Neovim plugins with access to the Neovim Lua API.

How?

• See the luarocks test documentation.
• An example project can be found in the testproject subdirectory.
• Neovim plugins should have a rockspec and a .busted file in the project root.

In a Nix flake

This project provides a Nix overlay with a neorocksTest function. Here is an example of how to use it in a Nix flake:

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
    neorocks.url = "github:nvim-neorocks/neorocks";
  };
  outputs = {
    self,
    nixpkgs,
    neorocks,
    ...
  }: let
    system = "x86_64-linux";
    pkgs = import nixpkgs {
      inherit system;
      overlays = [
        neorocks.overlays.default
      ];
    };
  in {
    # ...
    checks.${system} = {
      neorocks-test = pkgs.neorocksTest {
        src = self; # Project containing the rockspec and .busted files.
        # Plugin name. If running multiple tests,
        # you can use pname for the plugin name instead
        name = "my-plugin.nvim"
        version = "scm-1"; # Optional, defaults to "scm-1";
        neovim = pkgs.neovim-nightly; # Optional, defaults to neovim-nightly.
        luaPackages = ps: # Optional
          with ps; [
            # LuaRocks dependencies must be added here.
            plenary-nvim
          ];
        extraPackages = []; # Optional. External test runtime dependencies.
      };
    };
  };
}

In a Nix shell

nix shell "github:nvim-neorocks/neorocks"
busted

Without Nix (using nlua)

See: mfussenegger/nlua

Without nlua

To run busted tests locally, without neorocks or neolua...

• Install lua 5.1 and luarocks with your distribution's package manager.
• Add luarocks, lua_modules and .luarocks to your project's .gitignore.
• Add the following shell script to your project:

#!/bin/sh
export BUSTED_VERSION="2.1.2-3"
luarocks init
luarocks install busted "$BUSTED_VERSION"
luarocks config --scope project lua_version 5.1
nvim -u NONE \
  -c "lua package.path='lua_modules/share/lua/5.1/?.lua;lua_modules/share/lua/5.1/?/init.lua;'..package.path;package.cpath='lua_modules/lib/lua/5.1/?.so;'..package.cpath;local k,l,_=pcall(require,'luarocks.loader') _=k and l.add_context('busted','$BUSTED_VERSION')" \
  -l "lua_modules/lib/luarocks/rocks-5.1/busted/$BUSTED_VERSION/bin/busted" "$@"

• If your project depends on other luarocks packages, add them to the dependencies and test_dependencies in your project's rockspec.
• See also the example project in the testproject subdirectory.

Note

If your tests are not in a spec directory, pass the name of the test directory to the script. e.g., ./run-tests.sh tests

With GitHub Actions

• We recommend using the nvim-busted-action action, which uses nlua to run tests, or to use the neorocksTest helper in a nix-based CI.
• Alternatively, you can see the tests job of this project's CI for an example on how to use neorocksTest with GitHub actions manually.