API Reference¶
LanguageClient¶
- class pytest_lsp.LanguageClient(*args, configuration=None, **kwargs)¶
Bases:
BaseLanguageClient
Used to drive language servers under test.
- get_configuration(*, section=None, scope_uri=None)¶
Get a configuration value.
- Parameters:
- 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:
error (Exception)
source (PyglsError | JsonRpcException)
- set_configuration(item, *, section=None, scope_uri=None)¶
Set a configuration value.
- async shutdown_session()¶
Shutdown the server under test.
Helper method that handles sending
shutdown
andexit
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: ClientCapabilities | None¶
The client’s capabilities.
- diagnostics: Dict[str, List[Diagnostic]]¶
Holds any recieved diagnostics.
- log_messages: List[LogMessageParams]¶
Holds any received
window/logMessage
requests.
- messages: List[ShowMessageParams]¶
Holds any received
window/showMessage
requests.
- shown_documents: List[ShowDocumentParams]¶
Holds any received show document requests.
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
orclient-name@latest
Return the capabilities of the latest version of
client-name
client-name@v2
Return the latest release of the
v2
ofclient-name
client-name@v2.3.1
Return exactly
v2.3.1
ofclient-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:
- get_server_command(devtools=None)¶
Get the command to start the server with.
- 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 anlsp-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.
- 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:
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:
item (CompletionItem)
commit_characters_support (bool)
snippet_support (bool)
- 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:
capabilities (ClientCapabilities)
item (CompletionItem)
- 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:
capabilities (ClientCapabilities)
result (CompletionList | List[CompletionItem] | None)
- pytest_lsp.checks.document_links(capabilities, result)¶
Ensure that the document links returned from the server are compliant with the Spec and the client’s declared capabilities.
- Parameters:
capabilities (ClientCapabilities)
result (List[DocumentLink] | None)
- pytest_lsp.checks.work_done_progress_create(capabilities, params)¶
Assert that the client has support for
window/workDoneProgress/create
requests.- Parameters:
capabilities (ClientCapabilities)
params (WorkDoneProgressCreateParams)
- pytest_lsp.checks.workspace_configuration(capabilities, params)¶
Ensure that the client has support for
workspace/configuration
requests.- Parameters:
capabilities (ClientCapabilities)
params (ConfigurationParams)