README

php-lsp-test is a lightweight test harness for Language Server Protocol (LSP) servers in PHP projects, built for reliable use with PHPUnit.

It is inspired by pytest-lsp, but intentionally adapted to PHP and synchronous PHPUnit workflows instead of async pytest fixtures.

Goals

Start and control real LSP server processes from tests
Send and receive JSON-RPC messages over stdio
Assert protocol behavior in unit, integration, and end-to-end scenarios
Reproduce editor-like flows in a deterministic PHPUnit environment
Surface actionable diagnostics when tests fail (stderr/stdout/log messages)

Installation

Add as a dev dependency:

composer require --dev t3ide/php-lsp-test

Quickstart (PHPUnit)

Use LanguageServerTestCase to spin up and initialize a client quickly:

<?php

declare(strict_types=1);

use T3IDE\LanguageServerProtocol\Structure\InitializeParams;
use T3IDE\PhpLspTest\Capability\CapabilityRepository;
use T3IDE\PhpLspTest\PHPUnit\LanguageServerTestCase;

final class MyLspTest extends LanguageServerTestCase
{
    public function testServerInitialize(): void
    {
        $capabilities = CapabilityRepository::withDefaultSnapshots()->get('generic');

        $client = $this->initializeLanguageClient(
            ['php', '/path/to/server.php'],
            new InitializeParams(1, 'file:///workspace', $capabilities),
        );

        // ... send requests / assert responses ...

        $client->shutdownSession();
    }
}

Capabilities

Capability snapshots are managed by CapabilityRepository.

Built-in usage includes:

generic
version selectors like:
- name@latest
- name@v1
- name@1.2.0

This enables reproducible client simulation while still supporting latest-style test targets.

Diagnostics on Failures

LanguageServerTestCase appends client diagnostics to test failures:

process running state, pid, and exit code
collected stderr/stdout
recent window/logMessage entries

For protocol-level failures, termination details are also surfaced (exit code plus stderr), which helps with server crash and broken-pipe debugging.

Protocol and Process Robustness

php-lsp-test includes coverage for edge cases such as:

server exits while waiting for notifications
invalid JSON payloads from server
server termination mid request sequence
explicit result: null JSON-RPC response handling

Extensibility

LanguageClient supports overriding default handlers for server requests and notifications, enabling test-specific behavior without forking core client logic.

Relationship to pytest-lsp

This project borrows core ideas from pytest-lsp:

realistic client/server test orchestration
capability-driven checks
strong diagnostics around process and protocol failures

Implementation choices are intentionally PHP-first:

synchronous API design suitable for PHPUnit
typed PHP structures and exception model
process lifecycle and teardown behavior aligned with common PHP CI setups

License

MIT. See LICENSE.md.

t3ide / php-lsp-test

Maintainers

Package info

Statistics

Security