chore: add pytest-xdist

Parallelise the tests so the test suite runs faster.

Signed-off-by: JP-Ellis <[email protected]>

examples/conftest.py

@@ -12,6 +12,9 @@
 
 from __future__ import annotations
 
+import socket
+import sys
+import warnings
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
@@ -20,7 +23,9 @@
 from yarl import URL
 
 if TYPE_CHECKING:
-    from collections.abc import Generator
+    from collections.abc import Generator, Sequence
+
+    import execnet
 
 EXAMPLE_DIR = Path(__file__).parent.resolve()
 
@@ -45,17 +50,46 @@ def broker(request: pytest.FixtureRequest) -> Generator[URL, Any, None]:
         yield URL(broker_url)
         return
 
+    # Check whether port 9292 is already in use. If it is, we assume that the
+    # broker is already running and return early.
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        if s.connect_ex(("localhost", 9292)) == 0:
+            yield URL("http://pactbroker:pactbroker@localhost:9292")
+            return
+
     with DockerCompose(
         EXAMPLE_DIR,
         compose_file_name=["docker-compose.yml"],
         pull=True,
         wait=False,
     ) as _:
         yield URL("http://pactbroker:pactbroker@localhost:9292")
-    return
 
 
 @pytest.fixture(scope="session")
 def pact_dir() -> Path:
     """Fixture for the Pact directory."""
     return EXAMPLE_DIR / "pacts"
+
+
+def pytest_xdist_setupnodes(
+    config: pytest.Config,  # noqa: ARG001
+    specs: Sequence[execnet.XSpec],
+) -> None:
+    """
+    Hook to check if the examples are run with multiple workers.
+
+    The examples are designed to run in a specific order, with the consumer
+    tests running _before_ the provider tests as the provider tests require that
+    the consumer-generated Pacts are published.
+
+    If multiple xdist workers are detected, a warning is printed to the console.
+    """
+    if len(specs) > 1:
+        sys.stderr.write("\n")
+        warnings.warn(
+            "Running the examples with multiple workers may cause issues. "
+            "Consider running the examples with a single worker by setting "
+            "`--numprocesses=1` or using `hatch run example`.",
+            stacklevel=1,
+        )

pyproject.toml

@@ -81,10 +81,11 @@ devel-test = [
   "flask[async]      ~=3.0",
   "httpx             ~=0.0",
   "mock              ~=5.0",
-  "pytest            ~=8.0",
   "pytest-asyncio    ~=0.0",
   "pytest-bdd        ~=8.0",
   "pytest-cov        ~=6.0",
+  "pytest-xdist      ~=3.0",
+  "pytest            ~=8.0",
   "testcontainers    ~=4.0",
 ]
 devel = ["pact-python[devel-types,devel-docs,devel-test]", "ruff==0.8.3"]
@@ -160,7 +161,7 @@ lint       = "ruff check --output-format=full --show-fixes {args}"
 typecheck  = "mypy {args:.}"
 format     = "ruff format {args}"
 test       = "pytest tests/ {args}"
-example    = "pytest examples/ {args}"
+example    = "pytest --numprocesses=1 examples/ {args}"
 all        = ["format", "lint", "typecheck", "test", "example"]
 docs       = "mkdocs serve {args}"
 docs-build = "mkdocs build {args}"
@@ -183,9 +184,13 @@ pythonpath = "."
 asyncio_default_fixture_loop_scope = "session"
 addopts = [
   "--import-mode=importlib",
+  # Coverage options
   "--cov-config=pyproject.toml",
   "--cov=pact",
   "--cov-report=xml",
+  # Xdist options
+  "--numprocesses=logical",
+  "--dist=worksteal",
 ]
 filterwarnings = [
   "ignore::DeprecationWarning:examples",