Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 25 additions & 52 deletions caldav/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -364,7 +364,7 @@ def _caldav_connections(

## TODO: the test server selection below, get_test_setting and
## get_all_test_servers are test tooling, not config; move them to
## caldav/testing.py (planned for 3.6.1).
## the caldav.testing package.
def _get_test_server_config(
name: str | None, environment: bool, config_file: str | None = None
) -> dict[str, Any] | None:
Expand All @@ -376,15 +376,15 @@ def _get_test_server_config(
(20) and configured / test_allowed servers (30) by default. Any server
can override its priority via ``test_priority: <int>`` in its config.

When running from the source tree the full registry is used (embedded +
docker + external). When caldav is pip-installed without the test
infrastructure, only embedded servers from ``caldav.testing`` plus any
``test_allowed`` config-file sections are available.
The servers are those of the ``caldav.testing`` registry (embedded,
docker and external), plus the ``test_allowed`` sections of
``config_file``.

Args:
name: Optional server name or server_type to restrict selection.
environment: Whether to read PYTHON_CALDAV_TEST_SERVER_NAME.
config_file: Explicit config file path (for test_allowed fallback).
environment: Whether to read PYTHON_CALDAV_TEST_SERVER_NAME, and to
find the config file through CALENDARING_CONFIG_FILE / CALDAV_CONFIG_FILE.
config_file: Explicit config file path, for its test_allowed sections.

Returns:
Connection parameters dict, or None if no server could be started.
Expand All @@ -401,7 +401,7 @@ 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
# A _ConfiguredServer has no session lock
claim = getattr(server, "claim_server", None)
claimed = False
try:
Expand All @@ -427,59 +427,32 @@ def _collect_test_servers(name: str | None, config_file: str | None) -> list[Any
"""
Return a priority-ordered list of available test servers.

Tries the full registry first (source tree); falls back to embedded
servers from ``caldav.testing`` plus ``test_allowed`` config sections
(pip-installed users).
The registry reads the default config file, so ``config_file`` adds
only what it holds beyond that: a file named explicitly or through
CALENDARING_CONFIG_FILE / CALDAV_CONFIG_FILE.
"""
try:
from tests.test_servers.registry import get_registry

servers: list[Any] = list(get_registry().enabled_servers())
except ImportError:
servers = _get_pip_test_servers(config_file)
from caldav.testing.registry import get_registry

servers: list[Any] = list(get_registry().enabled_servers())
if config_file:
known = {s.name.lower() for s in servers}
servers += [
_ConfiguredServer(section_name, params)
for section_name, params in get_all_test_servers(config_file).items()
if section_name.lower() not in known
]
servers.sort(key=lambda s: s.priority)

if name is not None:
servers = [s for s in servers if name.lower() in (s.name.lower(), s.server_type.lower())]
return servers


def _get_pip_test_servers(config_file: str | None) -> list[Any]:
"""
Build a server list for pip-installed users (no tests/ available).

Includes embedded servers from caldav.testing and any test_allowed
sections from config files, all sorted by priority.
"""
from caldav.testing import RadicaleServer, XandikosServer

servers: list[Any] = []

try:
import xandikos # noqa: F401

servers.append(XandikosServer())
except ImportError:
pass

try:
import radicale # noqa: F401

servers.append(RadicaleServer())
except ImportError:
pass

for section_name, params in get_all_test_servers(config_file).items():
servers.append(_ConfiguredServer(section_name, params))

return sorted(servers, key=lambda s: s.priority)


class _ConfiguredServer:
"""
Thin wrapper around a ``test_allowed`` config-file section.

Used only in pip-installed mode; in the source tree these sections are
loaded into the registry as ``ExternalTestServer`` instances instead.
Thin wrapper around a ``test_allowed`` section of a config file that
the registry does not read (see ``_collect_test_servers``); the
registry loads the default file's sections as ``ExternalTestServer``.
"""

server_type = "external"
Expand Down
12 changes: 6 additions & 6 deletions caldav/testing.py → caldav/testing/__init__.py
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
"""
Lightweight embedded CalDAV test servers.
CalDAV test servers, shipped with the package.

Provides XandikosServer and RadicaleServer that are part of the installed
package so that pip-installed users can use get_davclient() with
PYTHON_CALDAV_USE_TEST_SERVER=1 without needing the full test infrastructure
from the source tree.
This module holds the lightweight embedded XandikosServer and RadicaleServer,
used by get_davclient() with PYTHON_CALDAV_USE_TEST_SERVER=1.

Docker and external server support lives in tests/test_servers/ (source only).
The registry, config loader and the Docker and external server classes are
submodules of this package (base, registry, config_loader, docker, ...); the
docker-compose files stay in the source repository.
"""

import copy
Expand Down
24 changes: 17 additions & 7 deletions tests/test_servers/base.py → caldav/testing/base.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,22 @@

from caldav.config import get_test_setting

try:
import niquests as requests
except ImportError:
import requests # type: ignore

def docker_servers_dir() -> Path:
"""Directory holding the per-server ``start.sh``/``docker-compose.yml`` files.

These stay in the source repository, not in the installed package. Point
``CALDAV_DOCKER_TEST_SERVERS_DIR`` at ``tests/docker-test-servers`` of a
checkout to use them from an installed caldav; without it, the directory is
looked up relative to the module (found when caldav is a source checkout).
"""
env = os.environ.get("CALDAV_DOCKER_TEST_SERVERS_DIR")
if env:
return Path(env).expanduser()
return Path(__file__).resolve().parent.parent.parent / "tests" / "docker-test-servers"


from caldav.lib.http_sync import requests

# Constants - extracted from magic numbers in conf.py
DEFAULT_HTTP_TIMEOUT = 5
Expand Down Expand Up @@ -402,9 +414,7 @@ def __init__(self, config: dict[str, Any] | None = None) -> None:
# Docker directory - default to tests/docker-test-servers/<name>
from pathlib import Path

default_docker_dir = (
Path(__file__).parent.parent / "docker-test-servers" / self.name.lower()
)
default_docker_dir = docker_servers_dir() / self.name.lower()
self.docker_dir = Path(self.config.get("docker_dir", default_docker_dir))
# Set when start() fails, so later tests fail fast instead of
# re-running start.sh and waiting for the full timeout every time.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
# Test-specific config file locations (don't need test_allowed). The
# checkout's file is found relative to this module, not to the current
# directory, so projects running from elsewhere see it too.
_TESTS_DIR = Path(__file__).resolve().parent.parent
_TESTS_DIR = Path(__file__).resolve().parent.parent.parent / "tests"
TEST_CONFIG_LOCATIONS = [
str(_TESTS_DIR / "caldav_test_servers.yaml"),
str(_TESTS_DIR / "caldav_test_servers.json"),
Expand Down
6 changes: 1 addition & 5 deletions tests/test_servers/docker.py → caldav/testing/docker.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,8 @@
from typing import Any
from urllib.parse import quote

try:
import niquests as requests
except ImportError:
import requests # type: ignore

from caldav import compatibility_hints
from caldav.lib.http_sync import requests

from .base import DEFAULT_HTTP_TIMEOUT, DockerTestServer
from .registry import register_server_class
Expand Down
File renamed without changes.
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ def client_context(server_index: int = 0, server_name: str | None = None):

Usage::

from tests.test_servers import client_context
from caldav.testing.helpers import client_context

with client_context() as client:
principal = client.principal()
Expand Down
11 changes: 5 additions & 6 deletions tests/test_servers/registry.py → caldav/testing/registry.py
Original file line number Diff line number Diff line change
Expand Up @@ -302,17 +302,16 @@ def _discover_embedded_servers(self) -> None:

def _discover_docker_servers(self) -> None:
"""Discover available Docker servers."""
from pathlib import Path

from .base import DockerTestServer

docker_available = DockerTestServer.verify_docker()
from .base import docker_servers_dir as _docker_servers_dir

# Look for docker-test-servers directories
docker_servers_dir = Path(__file__).parent.parent / "docker-test-servers"
docker_servers_dir = _docker_servers_dir()
if not docker_servers_dir.exists():
return

docker_available = DockerTestServer.verify_docker()

# Check each subdirectory for a start.sh script
for server_dir in docker_servers_dir.iterdir():
if server_dir.is_dir() and (server_dir / "start.sh").exists():
Expand Down Expand Up @@ -378,7 +377,7 @@ def get_registry() -> ServerRegistry:

warnings.warn(
f"Failed to load test server configuration: {e}. "
"Check tests/caldav_test_servers.yaml for errors.",
"Check the test server configuration for errors.",
UserWarning,
stacklevel=2,
)
Expand Down
1 change: 1 addition & 0 deletions changes/+testing-registry-in-package.added.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
The test-server framework - `ServerRegistry`, `get_registry()`, the config loader and the Docker and external server classes - is now part of the installed package, as submodules of `caldav.testing`, so other projects can run their tests against caldav's test servers without a source checkout (https://github.com/python-caldav/caldav/issues/817). `tests/test_servers` re-exports it. The docker-compose files stay in the repository: set `CALDAV_DOCKER_TEST_SERVERS_DIR` to `tests/docker-test-servers` of a checkout to start the Docker servers from an installed caldav. `get_davclient()` with `PYTHON_CALDAV_USE_TEST_SERVER=1` now picks from that registry on an installed caldav too, so the servers in `~/.config/caldav/test_servers.yaml` are candidates there as well.
6 changes: 5 additions & 1 deletion docs/design/TODO.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ A response whose `Content-Type` says XML but whose body is not XML (an HTML erro

## A waiting session-lock claim blocks other threads

`TestServer.claim_server()` in `tests/test_servers/base.py` polls for the flock (up to `PYTHON_CALDAV_TEST_SERVER_LOCK_TIMEOUT`, 30 minutes by default) while holding the module-wide `_session_locks_mutex`. A thread waiting for one busy server therefore blocks every other thread claiming a different server, which contradicts "runs against different servers proceed in parallel". Harmless for single-threaded pytest. Fix: hold the mutex only around the `_session_locks` checks and inserts, with a per-name lock against double claims. Found in the review of https://github.com/python-caldav/caldav/pull/776.
`TestServer.claim_server()` in `caldav/testing/base.py` polls for the flock (up to `PYTHON_CALDAV_TEST_SERVER_LOCK_TIMEOUT`, 30 minutes by default) while holding the module-wide `_session_locks_mutex`. A thread waiting for one busy server therefore blocks every other thread claiming a different server, which contradicts "runs against different servers proceed in parallel". Harmless for single-threaded pytest. Fix: hold the mutex only around the `_session_locks` checks and inserts, with a per-name lock against double claims. Found in the review of https://github.com/python-caldav/caldav/pull/776.

## calendar_multiget() fails on an async client

Expand Down Expand Up @@ -72,3 +72,7 @@ On Nextcloud a deleted calendar moves to the trashbin, keeps its cal_id occupied
The tests and the caldav-server-tester leave calendars behind, and on servers that cap the number of calendars per principal (ecloud, see above) that eventually blocks all creation. On 2026-10-23 ecloud held 15 empty calendars with bare-uuid cal_ids and the uuid as display name; which code made them was not found. Every calendar the tests or the tester create should carry a cal_id prefix, like the caldav-server-tester's `csc_` UIDs, so a cleanup step can delete leftovers safely - with the purge from the section above where the server has a trashbin.
* caldav tests: there is no common cal_id prefix on every calendar, and no sweep. Several tests create calendars by name only (`test_caldav.py` "CalConfigA"/"CalConfigB", "XandikosMetaCal"/"RadicaleMetaCal", `test_get_calendars_sections.py`, `test_examples.py`), so `make_calendar()` gives them a bare uuid. Give all of them a `pythoncaldav-test` prefixed cal_id and add a session-level sweep.
* caldav-server-tester: has `PROBE_CALENDAR_PREFIXES` and a sweep matching cal_id or display name, but `CheckDuplicateUID` creates its second calendar by name only, so its cal_id is a bare uuid that the sweep cannot recognise when the server drops the display name. Pass a prefixed cal_id. Its sweep also only moves calendars to the Nextcloud trashbin.

## An installed caldav.testing looks for the checkout in site-packages

`caldav/testing/config_loader.py` (`_TESTS_DIR`) and `docker_servers_dir()` in `caldav/testing/base.py` look for a checkout's `tests/` three levels up from the module. For an installed caldav that is `site-packages/tests`, so a stray top-level `tests` directory left by another badly packaged wheel would be searched for `caldav_test_servers.yaml` and `docker-test-servers/`. Also, while `CALDAV_DOCKER_TEST_SERVERS_DIR` locates the compose files of a checkout, nothing locates its `caldav_test_servers.yaml`, so an installed caldav reads only `~/.config/caldav/test_servers.yaml`. Fix: use the `tests/` path only when it belongs to a caldav checkout (e.g. a sibling `pyproject.toml` naming caldav), and perhaps add a `CALDAV_TEST_SERVERS_CONFIG` variable. Found in the review of https://github.com/python-caldav/caldav/issues/817.
6 changes: 2 additions & 4 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -139,13 +139,11 @@ test = [
ignore = ["DEP002"] # Test dependencies (pytest, coverage, etc.) are not imported in main code

[tool.deptry.per_rule_ignores]
DEP001 = ["conf", "h2", "tests", "calendaring_jmap"] # conf: Local test config, h2: Optional HTTP/2 support, calendaring_jmap: optional dep for caldav.jmap.
DEP001 = ["conf", "h2", "calendaring_jmap"] # conf: Local test config, h2: Optional HTTP/2 support, calendaring_jmap: optional dep for caldav.jmap.
## httpxyz needed an entry here while it was imported by name; the httpx-family
## libraries are now imported dynamically (see _ASYNC_HTTPX_CANDIDATES), which
## deptry does not see at all.
## tests: caldav/config.py optionally imports tests.test_servers.registry (source
## tree only, guarded by ImportError) to auto-start a test server from a checkout.
DEP003 = ["aiohttp", "h2"] # aiohttp: optional dep used only in caldav/testing.py
DEP003 = ["aiohttp", "h2"] # aiohttp: optional dep used only in caldav/testing/__init__.py
## h2 needs an entry in both DEP001 and DEP003: which of the two the optional
## `import h2` in async_davclient.py trips depends on whether h2 happens to be
## installed - DEP001 "missing" when it is not (CI), DEP003 "transitive" when it
Expand Down
26 changes: 18 additions & 8 deletions tests/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -232,14 +232,24 @@ test-servers:

## Test Server Framework

The `test_servers/` directory contains the unified test server framework:

- `base.py` - Base classes for test servers
- `config_loader.py` - Configuration file loading
- `registry.py` - Server discovery and registration
- `embedded.py` - Embedded server implementations (Radicale, Xandikos)
- `docker.py` - Docker server implementations
- `helpers.py` - Test helper utilities
The framework is part of the installed package, as `caldav.testing`, so other
projects can use it without a source checkout:

- `caldav/testing/__init__.py` - the embedded Radicale and Xandikos servers
- `caldav/testing/base.py` - Base classes for test servers
- `caldav/testing/config_loader.py` - Configuration file loading
- `caldav/testing/registry.py` - Server discovery and registration
- `caldav/testing/embedded.py` - Registry wrappers for the embedded servers
- `caldav/testing/docker.py` - Docker server implementations
- `caldav/testing/helpers.py` - Test helper utilities

`tests/test_servers/` re-exports all of it, so `from tests.test_servers import ...`
keeps working. The docker-compose files (`tests/docker-test-servers/`) are not
shipped: they are found relative to a source checkout, or, from an installed
caldav, through `CALDAV_DOCKER_TEST_SERVERS_DIR` pointing at that directory.
Without them, a docker server that is already running (e.g. a CI service
container) is not discovered; give it a config entry instead (`type: baikal`
and its `url`).

## Continuous Integration

Expand Down
21 changes: 17 additions & 4 deletions tests/test_servers/__init__.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,11 @@
"""
Test server framework for caldav tests.

The implementation lives in caldav.testing (shipped with the package, so that
other projects can use it); this package re-exports it, and each submodule is
an alias of its caldav.testing counterpart, so existing imports and
monkeypatching keep working.

This package provides a unified framework for starting and managing
test servers (Radicale, Xandikos, Docker containers) for both sync
and async tests.
Expand All @@ -23,7 +28,10 @@
server.stop()
"""

from .base import (
import importlib
import sys

from caldav.testing.base import (
DEFAULT_HTTP_TIMEOUT,
MAX_STARTUP_WAIT_SECONDS,
STARTUP_POLL_INTERVAL,
Expand All @@ -32,9 +40,14 @@
ExternalTestServer,
TestServer,
)
from .config_loader import ConfigParseError, load_test_server_config
from .helpers import client_context, has_test_servers
from .registry import ServerRegistry, get_available_servers, get_registry
from caldav.testing.config_loader import ConfigParseError, load_test_server_config
from caldav.testing.helpers import client_context, has_test_servers
from caldav.testing.registry import ServerRegistry, get_available_servers, get_registry

for _name in ("base", "config_loader", "docker", "embedded", "helpers", "registry"):
sys.modules[f"{__name__}.{_name}"] = globals()[_name] = importlib.import_module(
f"caldav.testing.{_name}"
)

__all__ = [
# High-level helpers
Expand Down
Loading
Loading