Initial draft of a v1 migration guide for pytest-lsp

README.md

@@ -33,13 +33,9 @@ This also means `pytest-lsp` can be used to test language servers written in any
 ```python
 import sys
 
+import pytest
 import pytest_lsp
-from lsprotocol.types import (
-    CompletionParams,
-    InitializeParams,
-    Position,
-    TextDocumentIdentifier,
-)
+from lsprotocol import types
 from pytest_lsp import (
     ClientServerConfig,
     LanguageClient,
@@ -48,16 +44,21 @@ from pytest_lsp import (
 
 
 @pytest_lsp.fixture(
+    scope="module",
     config=ClientServerConfig(
         server_command=[sys.executable, "-m", "esbonio"],
     ),
 )
 async def client(lsp_client: LanguageClient):
     # Setup
     response = await lsp_client.initialize_session(
-        InitializeParams(
+        types.InitializeParams(
             capabilities=client_capabilities("visual-studio-code"),
-            root_uri="file:///path/to/test/project/root/",
+            workspace_folders=[
+                types.WorkspaceFolder(
+                    uri="file:///path/to/test/project/root/", name="project"
+                ),
+            ],
         )
     )
 
@@ -67,11 +68,12 @@ async def client(lsp_client: LanguageClient):
     await lsp_client.shutdown_session()
 
 
+@pytest.mark.asyncio(loop_scope="module")
 async def test_completion(client: LanguageClient):
     result = await client.text_document_completion_async(
-        params=CompletionParams(
-            position=Position(line=5, character=23),
-            text_document=TextDocumentIdentifier(
+        params=types.CompletionParams(
+            position=types.Position(line=5, character=23),
+            text_document=types.TextDocumentIdentifier(
                 uri="file:///path/to/test/project/root/test_file.rst"
             ),
         )

docs/pytest-lsp/howto.rst

@@ -5,4 +5,5 @@ How To
    :maxdepth: 2
 
    Integrate with lsp-devtools <howto/integrate-with-lsp-devtools>
+   Migrate to v1 <howto/migrate-to-v1>
    Test Generic JSON-RPC Servers <howto/testing-json-rpc-servers>

docs/pytest-lsp/howto/migrate-to-v1.rst

@@ -0,0 +1,27 @@
+How To Migrate to v1
+====================
+
+The ``v1`` release of ``pytest-lsp`` contains some breaking changes, mostly as a result of changes in the wider ecosystem.
+This guide summarises the changes and provides references on where to get more details.
+
+Python Support
+--------------
+
+This release removes support for Python 3.8 and adds support for Python 3.13.
+
+``pytest``
+----------
+
+This release removes support for pytest ``v7``, if you have not done so already please update to pytest ``v8``.
+
+
+``pytest-asyncio``
+------------------
+
+The minimum required version for ``pytest-asyncio`` is now ``0.24``, see `this guide <https://pytest-asyncio.readthedocs.io/en/latest/how-to-guides/migrate_from_0_23.html>`__ for details on upgrading
+
+``pygls``
+---------
+
+``pygls``, the underlying language server protocol implementation used by ``pytest-lsp`` has been upgraded to ``v2``.
+See `this guide <https://pygls.readthedocs.io/en/latest/howto/migrate-to-v2.html>`__ for details on the breaking changes this brings.

lib/pytest-lsp/README.md

@@ -12,13 +12,9 @@ See the [documentation](https://lsp-devtools.readthedocs.io/en/latest/) for deta
 ```python
 import sys
 
+import pytest
 import pytest_lsp
-from lsprotocol.types import (
-    CompletionParams,
-    InitializeParams,
-    Position,
-    TextDocumentIdentifier,
-)
+from lsprotocol import types
 from pytest_lsp import (
     ClientServerConfig,
     LanguageClient,
@@ -27,16 +23,21 @@ from pytest_lsp import (
 
 
 @pytest_lsp.fixture(
+    scope="module",
     config=ClientServerConfig(
         server_command=[sys.executable, "-m", "esbonio"],
     ),
 )
 async def client(lsp_client: LanguageClient):
     # Setup
     response = await lsp_client.initialize_session(
-        InitializeParams(
+        types.InitializeParams(
             capabilities=client_capabilities("visual-studio-code"),
-            root_uri="file:///path/to/test/project/root/",
+            workspace_folders=[
+                types.WorkspaceFolder(
+                    uri="file:///path/to/test/project/root/", name="project"
+                ),
+            ],
         )
     )
 
@@ -46,11 +47,12 @@ async def client(lsp_client: LanguageClient):
     await lsp_client.shutdown_session()
 
 
+@pytest.mark.asyncio(loop_scope="module")
 async def test_completion(client: LanguageClient):
     result = await client.text_document_completion_async(
-        params=CompletionParams(
-            position=Position(line=5, character=23),
-            text_document=TextDocumentIdentifier(
+        params=types.CompletionParams(
+            position=types.Position(line=5, character=23),
+            text_document=types.TextDocumentIdentifier(
                 uri="file:///path/to/test/project/root/test_file.rst"
             ),
         )