API Reference

LanguageClient

class pytest_lsp.LanguageClient(*args, configuration=None, **kwargs)

Bases: LanguageClient

Used to drive language servers under test.

Parameters:

configuration (dict[str, Any] | None)

get_configuration(*, section=None, scope_uri=None)

Get a configuration value.

Parameters:

  • section (str | None) – The optional section name to retrieve. If None the top level configuration object for the requested scope will be returned

  • scope_uri (str | None) – The scope at which to set the configuration. If None, this will default to the global scope.

Returns:

The requested configuration value or None if not found.

Return type:

Optional[Any]

async initialize_session(params)

Make an initialize request to a lanaguage server.

It will also automatically send an initialized notification once the server responds.

Parameters:

params (InitializeParams) –

The parameters to send to the client.

The following fields will be automatically set if left blank.

  • process_id: Set to the PID of the current process.

Returns:

The result received from the client.

Return type:

InitializeResult

report_server_error(error, source)

Called when the server does something unexpected, e.g. sending malformed JSON.

Parameters:
async server_exit(server)

Called when the server process exits.

Parameters:

server (Process)

set_configuration(item, *, section=None, scope_uri=None)

Set a configuration value.

Parameters:

  • item (Any) – The value to set

  • section (str | None) – The optional section name to set. If None the top level configuration object will be overriden with item.

  • scope_uri (str | None) – The scope at which to set the configuration. If None, this will default to the global scope.

async shutdown_session()

Shutdown the server under test.

Helper method that handles sending shutdown and exit messages in the correct order.

Note

This method will not attempt to send these messages if a fatal error has occurred.

Return type:

None

async start_io(cmd, *args, **kwargs)

Start the given server and communicate with it over stdio.

Parameters:

cmd (str)

async wait_for_notification(method)

Block until a notification with the given method is received.

Parameters:

method (str) – The notification method to wait for, e.g. textDocument/publishDiagnostics

capabilities: types.ClientCapabilities | None

The client’s capabilities.

diagnostics: dict[str, Sequence[types.Diagnostic]]

Holds any recieved diagnostics.

error: Exception | None

Indicates if the client encountered an error.

log_messages: list[types.LogMessageParams]

Holds any received window/logMessage requests.

messages: list[types.ShowMessageParams]

Holds any received window/showMessage requests.

progress_reports: dict[types.ProgressToken, list[types.ProgressParams]]

Holds any received progress updates.

shown_documents: list[types.ShowDocumentParams]

Holds any received show document requests.

pytest_lsp.client.register_lsp_features(client, features=None)

Register the given lsp feature implementations with the given client instance.

If no features are given, then the default map will be used.

Parameters:
pytest_lsp.client.DEFAULT_CLIENT_FEATURES: dict[str, Any] = {'$/progress': <function progress>, 'textDocument/publishDiagnostics': <function publish_diagnostics>, 'window/logMessage': <function log_message>, 'window/showDocument': <function show_document>, 'window/showMessage': <function show_message>, 'window/workDoneProgress/create': <function create_work_done_progress>, 'workspace/configuration': <function configuration>}

The default implementation of LSP methods provided by the client.

Test Setup

pytest_lsp.fixture(fixture_function=None, *, config, **kwargs)

Define a fixture that returns a client connected to a server running in a background sub-process

Parameters:

config (ClientServerConfig) – Configuration for the client and server.

pytest_lsp.client_capabilities(client_spec)

Find the capabilities that correspond to the given client spec.

This function supports the following syntax

client-name or client-name@latest

Return the capabilities of the latest version of client-name

client-name@v2

Return the latest release of the v2 of client-name

client-name@v2.3.1

Return exactly v2.3.1 of client-name

Parameters:

client_spec (str) – The string describing the client to load the corresponding capabilities for.

Raises:

ValueError – If the requested client’s capabilities could not be found

Returns:

The requested client capabilities

Return type:

ClientCapabilities

class pytest_lsp.ClientServerConfig(server_command, client_factory=<function make_test_lsp_client>, server_env=None)

Configuration for a Client-Server connection.

Method generated by attrs for class ClientServerConfig.

Parameters:

  • server_command (list[str])

  • client_factory (Callable[[], JsonRPCClient])

  • server_env (dict[str, str] | None)

get_server_command(devtools=None)

Get the command to start the server with.

Parameters:

devtools (str | None)

Return type:

list[str]

async start(devtools=None)

Return the client instance to use for the test.

Parameters:

devtools (str | None) – If set, enable lsp-devtools integration, should be of the form <port> or <host>:<port>. Where <host> and <port> describe how to connect to an lsp-devtools server program.

Returns:

The client instance to use in the test.

Return type:

JsonRPCClient

client_factory: Callable[[], JsonRPCClient]

Factory function to use when constructing the test client instance.

server_command: list[str]

The command to use to start the language server.

server_env: dict[str, str] | None

Environment variables to set when starting the server.

pytest_lsp.make_test_lsp_client()

Construct a new test client instance with the handlers needed to capture additional responses from the server.

Return type:

LanguageClient

Checks

Checks to ensure that the server is compliant with the spec.

These can be used in your unit tests to ensure that objects (such as CompletionItem etc) take into account the client’s capabilities when constructed.

However, they are also called automatically during end-to-end tests that make use of the standard LanguageClient. See Specification Compliance Checks for more details.

exception pytest_lsp.checks.LspSpecificationWarning

Warning raised when encountering results that fall outside the spec.

pytest_lsp.checks.check_completion_item(item, commit_characters_support, documentation_formats, snippet_support)

Ensure that the given CompletionItem complies with the given capabilities.

Parameters:
pytest_lsp.checks.check_params_against_client_capabilities(capabilities, method, params)

Check that the given params respect the client’s declared capabilities.

This will emit an LspSpecificationWarning if any issues are detected.

Parameters:

  • capabilities (ClientCapabilities | None) – The client’s capabilities

  • method (str) – The method name to validate the result of

  • params (Any) – The params to validate

pytest_lsp.checks.check_params_of(*, method)

Define a params check.

Parameters:

method (str)

Return type:

Callable[[Callable[[ClientCapabilities, Any], None]], Callable[[ClientCapabilities, Any], None]]

pytest_lsp.checks.check_result_against_client_capabilities(capabilities, method, result)

Check that the given result respects the client’s declared capabilities.

This will emit an LspSpecificationWarning if any issues are detected.

Parameters:

  • capabilities (ClientCapabilities | None) – The client’s capabilities

  • method (str) – The method name to validate the result of

  • result (Any) – The result to validate

pytest_lsp.checks.check_result_for(*, method)

Define a result check.

Parameters:

method (str)

Return type:

Callable[[Callable[[ClientCapabilities, Any], None]], Callable[[ClientCapabilities, Any], None]]

pytest_lsp.checks.completion_item_resolve(capabilities, item)

Ensure that the completion item returned from the server is compliant with the spec and the client’s declared capbabilities.

Parameters:
pytest_lsp.checks.completion_items(capabilities, result)

Ensure that the completion items returned from the server are compliant with the spec and the client’s declared capabilities.

Parameters:

Ensure that the document links returned from the server are compliant with the Spec and the client’s declared capabilities.

Parameters:
pytest_lsp.checks.work_done_progress_create(capabilities, params)

Assert that the client has support for window/workDoneProgress/create requests.

Parameters:
pytest_lsp.checks.workspace_configuration(capabilities, params)

Ensure that the client has support for workspace/configuration requests.

Parameters: