diff --git a/caldav/config.py b/caldav/config.py index 8ff0ac1b..147ad860 100644 --- a/caldav/config.py +++ b/caldav/config.py @@ -413,10 +413,17 @@ def _get_test_server_config( for server in _collect_test_servers(name, config_file): was_already_started = server._started + # Servers from caldav.testing (pip-installed caldav) have no session lock + claim = getattr(server, "claim_server", None) + claimed = False try: + # Another process using this server: try the next one rather than wait + claimed = bool(claim and claim(server.name, 0)) server.start() except Exception as e: logging.warning("Failed to start test server %s: %s", server.name, e) + if claimed: + server.release_server(server.name) continue logging.info("Using test server: %s at %s", server.name, server.url) return _test_server_to_params(server, was_already_started) diff --git a/docs/design/TODO.md b/docs/design/TODO.md index 3a6b535b..a00cc53a 100644 --- a/docs/design/TODO.md +++ b/docs/design/TODO.md @@ -44,3 +44,7 @@ Known downsides: no Unreleased section visible on master (consider `sphinxcontri ## An error response with a non-XML body labelled as XML A response whose `Content-Type` says XML but whose body is not XML (an HTML error page sent as `application/xml`) makes `DAVResponse.__init__` raise an lxml parse error, on any status. The caller never gets the `DAVError` (with `body` and `preconditions`, https://github.com/python-caldav/caldav/issues/756) that the status calls for. Only the async client's 401/403 path was fixed (https://github.com/python-caldav/caldav/issues/738). Fix: tolerate a parse failure on a 4xx/5xx response and keep the raw body. Found in the review of the #756 fix. + +## Search-cache delay misses writes from other clients + +`tests/search_cache_delay.py` only resets its clock on writes through the one wrapped client. Writes through another `DAVClient` in the same test (e.g. the scheduling users' clients) are not counted, so a filtered search right after one may wait less than the server's cache lag, and get flaky on servers like Purelymail or Bedework. Fix: wrap `DAVClient.request` at class level for the duration of the test, or document the limitation. Found in the review of https://github.com/python-caldav/caldav/pull/776. diff --git a/pyproject.toml b/pyproject.toml index 9c228817..44577a0d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,6 +4,10 @@ build-backend = "hatchling.build" [tool.hatch.version] source = "vcs" +# Only v* tags are releases. The default describe matches any tag +# containing a digit, so a non-release tag with a number in it could +# become the version and break the build. +raw-options = { scm = { git = { describe_command = "git describe --dirty --tags --long --abbrev=40 --match v[0-9]*" } } } [tool.hatch.build.hooks.vcs] version-file = "caldav/_version.py" diff --git a/tests/README.md b/tests/README.md index dbd62457..38055597 100644 --- a/tests/README.md +++ b/tests/README.md @@ -34,6 +34,30 @@ pytest -k "test_to_utc" pytest tests/test_caldav_unit.py ``` +### Parallel Test Runs + +Test runs share the servers (fixed ports, users and calendar names), so +two runs against the same server would clobber each other. Each process +takes an exclusive per-server lock (`$TMPDIR/caldav-test-server-.session.lock`) +when it first starts using a server and holds it until it exits. A second run +against the same server waits; runs against different servers proceed in +parallel: + +```bash +pytest tests/test_caldav.py -k Baikal & +pytest tests/test_caldav.py -k Nextcloud & +``` + +The lock file lives in the temp directory, so runs only see each other's +locks when they share `TMPDIR`. + +The wait is capped at `PYTHON_CALDAV_TEST_SERVER_LOCK_TIMEOUT` seconds +(default 1800), as two runs taking servers in different orders could +otherwise deadlock. After that, the tests for that server fail at once, +naming the pid holding the lock; the run continues with the other servers. +`get_davclient()` with `PYTHON_CALDAV_USE_TEST_SERVER` does not wait at all: +it moves on to the next available server. + ## Test Configuration Test configuration uses YAML or JSON files. The configuration loader searches diff --git a/tests/test_servers/base.py b/tests/test_servers/base.py index e70b8a97..53e1637f 100644 --- a/tests/test_servers/base.py +++ b/tests/test_servers/base.py @@ -7,10 +7,13 @@ - DockerTestServer: For servers that run in Docker containers """ +import os +import threading from abc import ABC, abstractmethod from collections.abc import Iterator from contextlib import contextmanager -from typing import Any +from pathlib import Path +from typing import IO, Any try: import niquests as requests @@ -21,6 +24,22 @@ DEFAULT_HTTP_TIMEOUT = 5 MAX_STARTUP_WAIT_SECONDS = 60 STARTUP_POLL_INTERVAL = 0.05 +SESSION_LOCK_TIMEOUT_SECONDS = 1800 + +# Per-server session locks held by this process, keyed by server name. +# flock conflicts between two opens even within one process, so each +# lock file is opened only once. +_session_locks: dict[str, IO[str]] = {} +# Servers whose lock timed out; later claims fail at once instead of +# waiting again for every remaining test. +_session_lock_failures: dict[str, RuntimeError] = {} +_session_locks_mutex = threading.Lock() + + +def _lock_path(name: str, suffix: str = "") -> Path: + import tempfile + + return Path(tempfile.gettempdir()) / f"caldav-test-server-{name.lower()}{suffix}.lock" class TestServer(ABC): @@ -106,11 +125,97 @@ def features(self) -> Any: return resolve_features(self.config.get("features", [])) + @staticmethod + def claim_server(name: str, timeout: float | None = None) -> bool: + """Take an exclusive lock on server ``name`` for the rest of this process. + + Test runs sharing a server would clobber each other's calendars (and + one run's teardown may stop a container another run still uses), so + a second process waits here until the first one exits. Runs against + different servers proceed in parallel. The OS drops the lock when + the process dies, so a crashed run leaves nothing stale behind. + + Waits at most ``timeout`` seconds (default + ``$PYTHON_CALDAV_TEST_SERVER_LOCK_TIMEOUT``, or 30 minutes) - two runs + taking servers in different orders could otherwise deadlock. A + timeout is remembered, so the remaining tests for that server fail + at once - except with ``timeout=0``, a mere probe. + + Returns True if the lock was taken just now, False if this process + already held it. Anything learned about the server before a fresh + claim may be stale, since its previous user may have stopped it. + + Without ``fcntl`` (Windows) nothing is locked between processes. + """ + import time + + try: + import fcntl + except ImportError: + fcntl = None # type: ignore[assignment] + + with _session_locks_mutex: + if name in _session_locks: + return False + if name in _session_lock_failures: + raise _session_lock_failures[name] + if timeout is None: + timeout = float( + os.environ.get( + "PYTHON_CALDAV_TEST_SERVER_LOCK_TIMEOUT", SESSION_LOCK_TIMEOUT_SECONDS + ) + ) + lock_file = open(_lock_path(name, ".session"), "a+") + try: + deadline = time.monotonic() + timeout + announced = False + while fcntl: + try: + fcntl.flock(lock_file, fcntl.LOCK_EX | fcntl.LOCK_NB) + break + except BlockingIOError: + lock_file.seek(0) + holder = lock_file.read().strip() or "unknown" + if time.monotonic() > deadline: + error = RuntimeError( + f"Test server {name} is in use by pid {holder}; " + f"gave up after {timeout:.0f}s" + ) + if timeout: + _session_lock_failures[name] = error + raise error from None + if not announced: + print(f"[WAIT] {name} is in use by pid {holder} - waiting") + announced = True + time.sleep(1) + lock_file.truncate(0) + lock_file.write(str(os.getpid())) + lock_file.flush() + except BaseException: + lock_file.close() + raise + _session_locks[name] = lock_file + return True + + @staticmethod + def release_server(name: str) -> None: + """Give up a claim taken by ``claim_server()``, letting other runs have the server.""" + with _session_locks_mutex: + lock_file = _session_locks.pop(name, None) + if lock_file: + lock_file.close() + + def claim(self) -> bool: + """``claim_server()`` for this server.""" + return self.claim_server(self.name) + @abstractmethod def start(self) -> None: """ Start the server if not already running. + Implementations must call ``self.claim()`` first. + This method should be idempotent - calling it multiple times should not cause issues. @@ -206,6 +311,8 @@ def get_server_params(self) -> dict[str, Any]: # Pass through scheduling_users if configured (for TestScheduling generation) if "scheduling_users" in self.config: params["scheduling_users"] = self.config["scheduling_users"] + # setup is always needed, since start() also takes the session lock + params["setup"] = lambda _: self.start() # Check if server is already running (either started by us or externally) already_running = self._started or self.is_accessible() if already_running: @@ -213,8 +320,6 @@ def get_server_params(self) -> dict[str, Any]: # to avoid stopping a server that was running before tests started self._started = True else: - # Server needs to be started - add setup/teardown callbacks - params["setup"] = lambda _: self.start() params["teardown"] = lambda _: self.stop() return params @@ -340,7 +445,13 @@ def start(self) -> None: Raises: RuntimeError: If Docker is not available or container fails to start """ - if self._started or self.is_accessible(): + if self.claim(): + # Whatever was seen before the lock (e.g. at collection) may be + # stale: the previous holder may have stopped the container. + self._started = False + if self._started: + return + if self.is_accessible(): self._started = True # Mark as started even if already running # Don't set _started_by_us - we didn't start it this time print(f"[OK] {self.name} is already running") @@ -371,11 +482,8 @@ def _lock(self) -> Iterator[None]: repo share the same containers and ports. """ import fcntl - import tempfile - from pathlib import Path - lock_path = Path(tempfile.gettempdir()) / f"caldav-test-server-{self.name.lower()}.lock" - with open(lock_path, "w") as lock_file: + with open(_lock_path(self.name), "w") as lock_file: fcntl.flock(lock_file, fcntl.LOCK_EX) try: yield @@ -412,6 +520,13 @@ def _start_container(self) -> None: raise RuntimeError(f"{self.name} failed to start after {MAX_STARTUP_WAIT_SECONDS}s") + def get_server_params(self) -> dict[str, Any]: + params = super().get_server_params() + # A run that waited for the lock may have restarted a container that + # was up at collection; stop() leaves alone one we did not start. + params["teardown"] = lambda _: self.stop() + return params + def stop(self) -> None: """Stop the Docker container and cleanup. @@ -482,6 +597,7 @@ def start(self) -> None: # No accessibility check here - the caldav library handles URL # normalization, RFC6764 discovery, and will provide proper error # messages if the server is unreachable + self.claim() self._started = True def stop(self) -> None: diff --git a/tests/test_servers/embedded.py b/tests/test_servers/embedded.py index fac684d3..06a4bd0d 100644 --- a/tests/test_servers/embedded.py +++ b/tests/test_servers/embedded.py @@ -39,6 +39,7 @@ def is_accessible(self) -> bool: return self._core.is_accessible() def start(self) -> None: + self.claim() self._core.start() self._started = self._core._started @@ -73,6 +74,7 @@ def is_accessible(self) -> bool: return self._core.is_accessible() def start(self) -> None: + self.claim() self._core.start() self._started = self._core._started diff --git a/tests/test_servers/test_base.py b/tests/test_servers/test_base.py index cbe13e17..f9926b3d 100644 --- a/tests/test_servers/test_base.py +++ b/tests/test_servers/test_base.py @@ -5,9 +5,38 @@ import pytest +from . import base from .base import DockerTestServer +@pytest.fixture(autouse=True) +def isolated_session_locks(tmp_path: Path, monkeypatch: pytest.MonkeyPatch): + """Keep session locks taken by these tests out of the real tempdir.""" + monkeypatch.setattr("tempfile.tempdir", str(tmp_path)) + monkeypatch.setattr(base, "_session_locks", {}) + monkeypatch.setattr(base, "_session_lock_failures", {}) + yield + for f in base._session_locks.values(): + f.close() + + +@pytest.fixture +def held_elsewhere(tmp_path: Path): + """Hold a server's session lock through a separate open file, as another process would.""" + import fcntl + + files = [] + + def hold(name: str) -> None: + f = open(base._lock_path(name, ".session"), "a+") + files.append(f) + fcntl.flock(f, fcntl.LOCK_EX) + + yield hold + for f in files: + f.close() + + class UnreachableDockerServer(DockerTestServer): """A docker server whose start.sh fails and which never answers.""" @@ -64,3 +93,195 @@ def is_accessible(self) -> bool: assert counter.read_text().count("run") == 1 assert sum(s._started_by_us for s in servers) == 1 + + +class TestGetServerParams: + def test_teardown_set_for_running_server(self, tmp_path: Path) -> None: + """A run that restarts the container after waiting for the lock must stop it again.""" + + class RunningServer(UnreachableDockerServer): + def is_accessible(self) -> bool: + return True + + server = RunningServer({"name": "Lambda", "docker_dir": str(tmp_path)}) + assert "teardown" in server.get_server_params() + + +class TestSessionLock: + """Test runs sharing a server must not overlap; different servers may.""" + + CLAIM = ( + "import sys; sys.path.insert(0, {root!r}); " + "from tests.test_servers.base import TestServer; " + "TestServer.claim_server({name!r})" + ) + + def _claim_in_subprocess(self, tmp_path: Path, name: str) -> subprocess.CompletedProcess: + import os + import sys + + root = str(Path(__file__).parents[2]) + env = dict(os.environ, TMPDIR=str(tmp_path), PYTHON_CALDAV_TEST_SERVER_LOCK_TIMEOUT="1") + return subprocess.run( + [sys.executable, "-c", self.CLAIM.format(root=root, name=name)], + env=env, + capture_output=True, + text=True, + timeout=60, + ) + + def test_same_server_blocks_other_process(self, tmp_path: Path) -> None: + import os + + base.TestServer.claim_server("Alpha") + base.TestServer.claim_server("Alpha") # re-entrant within one process + blocked = self._claim_in_subprocess(tmp_path, "Alpha") + assert blocked.returncode != 0 + assert f"pid {os.getpid()}" in blocked.stderr + assert self._claim_in_subprocess(tmp_path, "Beta").returncode == 0 + + def test_start_claims_server(self, tmp_path: Path) -> None: + server = base.ExternalTestServer({"name": "Gamma", "url": "http://localhost:1/"}) + server.start() + blocked = self._claim_in_subprocess(tmp_path, "Gamma") + assert blocked.returncode != 0 + assert "in use" in blocked.stderr + + def test_setup_hook_set_for_running_server(self) -> None: + """test_caldav only reaches start() (and thus the lock) via the setup hook.""" + server = base.ExternalTestServer({"name": "Delta", "url": "http://localhost:1/"}) + assert "setup" in server.get_server_params() + + def test_failed_claim_releases_lock( + self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch + ) -> None: + """An error after flock() must not leave the lock held by a leaked file.""" + + def fail() -> int: + raise OSError("simulated") + + monkeypatch.setattr(base.os, "getpid", fail) + with pytest.raises(OSError, match="simulated") as excinfo: + base.TestServer.claim_server("Theta") + monkeypatch.undo() + assert "Theta" not in base._session_locks + # excinfo keeps the failed frame, and with it any unclosed file, alive + assert excinfo.traceback + assert self._claim_in_subprocess(tmp_path, "Theta").returncode == 0 + + def test_timeout_is_remembered(self, held_elsewhere, monkeypatch: pytest.MonkeyPatch) -> None: + """test_caldav claims per test; a timed-out server must not wait again each time.""" + import time + + held_elsewhere("Epsilon") + monkeypatch.setenv("PYTHON_CALDAV_TEST_SERVER_LOCK_TIMEOUT", "1") + with pytest.raises(RuntimeError, match="in use"): + base.TestServer.claim_server("Epsilon") + t0 = time.monotonic() + with pytest.raises(RuntimeError, match="in use"): + base.TestServer.claim_server("Epsilon") + assert time.monotonic() - t0 < 0.5 + + def test_zero_timeout_skips_wait(self, held_elsewhere) -> None: + """get_davclient()'s fallback must move on at once from a busy server.""" + import time + + held_elsewhere("Zeta") + t0 = time.monotonic() + with pytest.raises(RuntimeError, match="in use"): + base.TestServer.claim_server("Zeta", 0) + assert time.monotonic() - t0 < 0.5 + + def test_fallback_leaves_later_claims_waiting(self, monkeypatch: pytest.MonkeyPatch) -> None: + """A busy server skipped by get_davclient() must still be waited for later.""" + import fcntl + + from caldav import config + + busy = base.ExternalTestServer({"name": "Iota", "url": "http://localhost:1/Iota/"}) + free = base.ExternalTestServer({"name": "Kappa", "url": "http://localhost:1/Kappa/"}) + monkeypatch.setattr(config, "_collect_test_servers", lambda name, config_file: [busy, free]) + with open(base._lock_path("Iota", ".session"), "a+") as other: + fcntl.flock(other, fcntl.LOCK_EX) + params = config._get_test_server_config(None, environment=False) + assert params is not None and "Kappa" in params["url"] + monkeypatch.setenv("PYTHON_CALDAV_TEST_SERVER_LOCK_TIMEOUT", "5") + busy.start() + + def test_get_davclient_falls_through_busy_server( + self, held_elsewhere, monkeypatch: pytest.MonkeyPatch + ) -> None: + import time + + from caldav import config + + held_elsewhere("Busy") + monkeypatch.setenv("PYTHON_CALDAV_TEST_SERVER_LOCK_TIMEOUT", "30") + servers = [ + base.ExternalTestServer({"name": n, "url": f"http://localhost:1/{n}/"}) + for n in ("Busy", "Free") + ] + monkeypatch.setattr(config, "_collect_test_servers", lambda name, config_file: servers) + t0 = time.monotonic() + params = config._get_test_server_config(None, environment=False) + assert time.monotonic() - t0 < 5 + assert params is not None and "Free" in params["url"] + + def test_fallback_uses_servers_without_session_lock( + self, monkeypatch: pytest.MonkeyPatch + ) -> None: + """Pip-installed caldav has no tests/ and so no claim_server() on its servers.""" + from caldav import config + + server = config._ConfiguredServer("Lambda", {"url": "http://localhost:1/Lambda/"}) + monkeypatch.setattr(config, "_collect_test_servers", lambda name, config_file: [server]) + params = config._get_test_server_config(None, environment=False) + assert params is not None and "Lambda" in params["url"] + + def test_fallback_releases_server_that_failed_to_start( + self, monkeypatch: pytest.MonkeyPatch + ) -> None: + import fcntl + + from caldav import config + + class BrokenServer(base.ExternalTestServer): + def start(self) -> None: + self.claim() + raise RuntimeError("does not start") + + broken = BrokenServer({"name": "Mu", "url": "http://localhost:1/Mu/"}) + free = base.ExternalTestServer({"name": "Nu", "url": "http://localhost:1/Nu/"}) + monkeypatch.setattr( + config, "_collect_test_servers", lambda name, config_file: [broken, free] + ) + params = config._get_test_server_config(None, environment=False) + assert params is not None and "Nu" in params["url"] + assert "Mu" not in base._session_locks + with open(base._lock_path("Mu", ".session"), "a+") as other: + fcntl.flock(other, fcntl.LOCK_EX | fcntl.LOCK_NB) + + def test_claim_without_fcntl(self, monkeypatch: pytest.MonkeyPatch) -> None: + """No fcntl (Windows): no lock between processes, but claims still work.""" + import sys + + monkeypatch.setitem(sys.modules, "fcntl", None) + assert base.TestServer.claim_server("Xi") is True + assert base.TestServer.claim_server("Xi") is False + + def test_waiting_run_restarts_container_stopped_meanwhile(self, tmp_path: Path) -> None: + """Collection saw the container up, but its owner stopped it before we got the lock.""" + counter = tmp_path / "runs" + start_script = tmp_path / "start.sh" + start_script.write_text(f"#!/bin/sh\necho run >> {counter}\n") + start_script.chmod(0o755) + + class CountingServer(UnreachableDockerServer): + def is_accessible(self) -> bool: + return counter.exists() + + server = CountingServer({"name": "Eta", "docker_dir": str(tmp_path)}) + server.verify_docker = lambda: True # type: ignore[method-assign] + server._started = True # as get_server_params() leaves it at collection + server.start() + assert counter.read_text().count("run") == 1