Who owns NymVPN?

Introduction to the lsp-devtools project

Ever tried debugging a language server and felt like you're yelling into a void? Since lsp usually runs over stdio with json-rpc, you can't just print() stuff to see what's happening between your editor and the server.

• Visibility: It's basically a black box where messages fly back and forth invisibly.
• Complexity: Debugging why a completion fails in vscode but works in neovim is a nightmare.
• Tooling Gap: Most devs end up writing messy loggers just to see a single packet.

According to the lsp-devtools project, this repo was built because the author got tired of that exact pain while working on the esbonio server.

It's a "grab bag" of tools like agent to intercept traffic and inspect for a nice TUI. Before we dive into the tools, let's get your environment ready.

Installation and Setup

Getting this stuff running is pretty straightforward. You'll want to use a virtual environment because nobody likes a messy global python path.

Using pip:

# Install the main devtools
pip install lsp-devtools

# If you want to do testing, grab the pytest plugin too
pip install pytest-lsp

Using conda:

conda install -c conda-forge lsp-devtools pytest-lsp

Once you got it installed, you can check if it works by typing lsp-devtools --help in your terminal. If it doesn't blow up, you're good to go. Now that the boring setup is done, let's look at the actual utilities.

Core Utilities in the lsp-devtools Package

Ever felt like you're debugging with one hand tied behind your back? The lsp-devtools package changes that by giving you actual eyes on the wire.

The agent is your man-in-the-middle. It wraps your server process and pipes every json-rpc message to a sidecar. You can then use record to save this stream.

• Wrapping: You run the agent as a proxy between the client (like vscode) and your server.
• Persistence: Save traffic to a sqlite database or just dump it to the console.
• Filtering: use flags to ignore noisy $/progress messages so you can focus on the stuff that's actually breaking.

If you've used browser devtools, lsp-devtools inspect will feel like home. This tool is powered by textual and it works by reading the database or log file you created with the record command. It connects the dots so you aren't just staring at raw json.

• Visualizing: See exactly which request triggered what response.
• Experimental Client: There is even a client tool for testing server features without opening a full IDE.

These tools make the "black box" of stdio transparent. Since we can see the messages now, we should probably talk about how to automate these checks with tests.

Testing with pytest-lsp

Ever spent hours clicking through a UI just to see if a single completion works? Man, it’s a total drag. That is where pytest-lsp comes in, letting you write actual tests that act like a real editor.

It spins up your server in a subprocess and talks to it over stdio. Since it is just json-rpc, you can test servers written in Rust, Go, or whatever—not just python stuff. To make this work, you usually need a conftest.py file that defines a client fixture, which handles the lifecycle of starting and stopping the server.

import pytest
import pytest_lsp
from lsprotocol import types
from pytest_lsp import LanguageClient

@pytest.mark.asyncio
async def test_completion(client: LanguageClient):
    # we simulate a user typing in a file
    # the 'client' fixture is provided by pytest-lsp via your conftest setup
    result = await client.text_document_completion_async(
        params=types.CompletionParams(
            position=types.Position(line=1, character=5),
            text_document=types.TextDocumentIdentifier(uri="file:///tmp/test.py")
        )
    )
    assert len(result.items) > 0

This plugin relies on pygls for the heavy lifting. The LanguageClient and types come from the lsprotocol and pytest_lsp libraries.

Honestly, it’s way better than manual testing. Let's see how this fits into a bigger picture for real projects.

Real world applications and system design

Ever wonder how big players keep their editor tools from breaking every time they push a commit? It's not magic, it’s just solid ci/cd integration.

You can easily bake these checks into github actions. Instead of manual clicking, your pipeline spins up the server and runs a suite of pytest-lsp tests. This is huge for catching regressions in complex areas like semantic tokens or deep workspace symbols.

• Headless testing: Run full client-server handshakes on every PR without a display.
• Industry use: Companies like Authzed are great examples of why this matters. They use these protocols to provide ide-like validation for their spicedb schema. While they have their own stack, using tools like pytest-lsp is exactly how you'd ensure those schemas validate correctly in a CI pipeline.
• Quality Gates: Block merges if the server response time for textDocument/completion drops below a certain threshold.

I've seen teams save days of debugging just by having a recorded log of a failed CI run to inspect later.

Future Outlook

The lsp world is moving fast. There's some cool stuff on the horizon that'll make these tools even better:

• New Specs: Support for workspace/diagnostic/refresh is being worked on to make error reporting smoother.
• Editor Profiles: Better integration for clients like Kate and specialized vscode profiles to make setup even faster.
• Advanced Filtering: More ways to slice and dice the recorded json-rpc traffic in the inspect TUI.

Conclusion

Building lsp tools is finally stop being a guessing game. Honestly, having a TUI to see messages in real-time saves so much hair-pulling. These utilities turn a messy process into a clean workflow. Stop logging to files and start inspecting.

Give it a spin and see if it makes your life easier.