By default, LazyVim downloads plugins from a provider such as GitHub. However, you can pass it any git url or point it at a local directory. We’ll be doing the latter.

First, let’s initialize a basic plugin structure in a new directory. You’ll need to make three nested directories:

The first neotest-bun can actually be any name. The lua is required for LazyVim to pick up any files inside it, and the last neotest-bun is a lua module that we will import in our configuration.

Inside this directory, create a file named init.lua. The contents of the file can just be some simple Lua code for now:

The next step is to hook this local plugin up to our LazyVim configuration. Create a new file in your LazyVim plugin directory (I called mine neotest-bun.lua). We’ll use the same format we used for vitest above, except we’ll point to our local plugin with the dir key:

To see if it’s working so far, open any file in Neovim and run <Space>tt to attempt to kick off the test runner. It will fail because we haven’t properly implemented the adapter interface, but it should also pop up a notification that says, “Hello, Lua!”.

Let’s flesh out the adapter interface. Open the neotest-bun/init.lua file and replace the print statement with the following content:

This is the interface we need to implement. If you’re wondering where I got this, it is defined in the Neotest source code and linked from the Neotest README. I also have the GitHub repositories for the neotest-jest and neotest-deno packages open for reference.

If you try to run tests on a Bun test file now, it will (probably) fail with a “No Tests Found” message. If it doesn’t, there may be another test runner installed that thinks this is a legit test file.

Our adapter is currently correctly reporting that it is a Neotest adapter, but then it is failing to register the current folder or file as a test file. We can fix that by implementing the first three methods in the file.

The root directory is supposed to find the project root given a current directory. When using Bun, we can use the presence or absence of a bun.lockb file as an indicator of the current project root. This file is generated when you run bun install and is used for keeping track of dependencies.

So let’s implement the BunNeoTestAdapter.root method like this:

The key here is the neotest.lib function match_root_pattern. We import that library and assign it to a local, then our root function just needs to create a callback and call it.

While we’re at it, we can also implement the filter_dir function. This method is designed to filter out directories that shouldn’t be scanned. In a Bun project, this includes the node_modules folder. We definitely don’t want to waste time scanning for tests in that folder!

Now if you restart Neovim and try to run tests with <Space>tT (that is a capital T the second time) it will not show the “No Tests found” message. It won’t do anything, but at least it won’t error. However, <Space>tt will error, because it doesn’t know that we are currently in a test file. We can address that from the is_test_file method.

In Bun, like most Javascript runtimes, tests are typically in a something.test.js or somethingElse.test.ts file. So we can use the following Lua function to check if we are in a test file:

If I open my cohere.test.ts file and run <Space>tt, I still get No Tests found. It is identifying the file as a Bun test file, but it doesn’t know how to look inside the file to find any tests.

Solving this requires implementing the discover_positions function, and that is…​ complicated. Typically, you would write Treesitter queries that identify namespaces and tests in the file. I suppose you could also write your own parser or use string.match, but Treesitter’s parser is probably better than anything we can write.

I don’t know anything about writing Treesitter queries, and I don’t particularly want to. So I’m just going to rely on the fact that Bun uses the same describe/test syntax that Jest uses, and I’ll copy the queries wholesale from the neotest-jest plugin!

It’s a pretty long bit of code that will likely be hard to read in book format, but I’ll include it here for completeness:

Now you can restart Neovim and open a bun test file to get a new error! New errors are progress, right?

You’ll now notice that Neotest is identifying the positions of describe and test calls in the gutter. Instead of the red cross or green check we would expect from a successful test run, it will be an eye with a cross through it. I suspect this means the test was skipped or not runnable. The good news is it is finding the tests. The bad news is it is not running the tests.

We can run the tests by implementing the build_spec function. This function accepts various parameters to determine how the user kicked off the tests. If they used <Space>tr it’s in “single test” mode, but if they used <Space>tt it is in “file” mode, and <Space>tT would run it in “all tests” mode.

The return value of build_spec is essentially a command to be run and some context to read the results back.

The code is actually not that long, so here it is in its entirety, followed by discussion:

We start by creating a temporary results_path using the neotest.async library. (You’ll need to import this with local async = require("neotest.async") at the top of the file). We load the position, which is a structure constructed from the return value of the discover_positions method we just wrote.

The if..elseif block is essentially checking how the user kicked off the test, and running the appropriate Bun command. If they provided a test name, then we pass the --test-name-pattern argument to the bun test command. If they kicked it off as a file, we run bun test filename. And if they wanted to run all tests, we simply run all tests with bun test.

The returned object includes some necessary context that will be used when we parse results. The bun test command is rather unusual in that it outputs the results to standard error, so we pass a 2> redirect to store the results in the temporary file we defined.

Now we just need to extract the results from that file.

This ended up being simpler than I expected, because bun test aggregates names in a way that maps to Neotest’s expected form quite easily. But it took me half a day of fussing around to get code that actually worked!

The results method mostly just has to read through the results_path file that was created by our build_spec function and convert it to a simple Lua table. The keys of the result table are the names of the tests in question, and the values are just a second table with {status = "passed"} or {status = "failed"}. At least, that’s all we’re going to put in it. Neotest does accept some other details here that it can render in the UI, but I’ll leave that as “an exercise for the reader.”

The tricky part is the “keys are the names of the tests”. I couldn’t find any documentation on this, and it took some trial and error to discover that nested “namespaces” (describe calls, in this case) in Neotest are separated by ::. The name also needs the absolute path to the test file. If we return that in the right format, Neotest will happily convert our results to the appropriate icons!

Here’s the code:

For context, this function is designed to translate output like this:

into something like this:

The method first grabs the filename from the context (the context was returned from the build_spec method). It opens the file and reads the lines from that file one by one. It then uses a matcher to determine if the line starts with (passed) or (failed) which is how Bun reports a test result. The rest of the test line will be the properly namespaced test name (minus a timing in square brackets), except the namespaces are separated by > instead of ::. So we use gsub to replace the > with ::. This is combined with the absolute path of the name of the file to get the right test name.

If a given line is not a test name, then it might be the name of the test file, which Bun kindly specifies as a relative path followed by a colon. So we do a match on that format and store the test name as an absolute path (that’s what the spec.cwd is for) to be prepended to subsequent test results.

And that’s the basics of implementing our own test runner! It’s missing some features, notably debugging tests and capturing output, but it’s a good start.