# Technical Documentation: Kozea/Radicale

> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/Kozea/Radicale)

### Overview (`README.md`)

# Radicale

[](https://github.com/Kozea/Radicale/actions/workflows/test.yml)
[](https://coveralls.io/github/Kozea/Radicale?branch=master)

Radicale is a small but powerful CalDAV (calendars, to-do lists) and CardDAV
(contacts) server, that:

* Shares calendars and contact lists through CalDAV, CardDAV and HTTP.
* Supports events, todos, journal entries and business cards.
* Works out-of-the-box, no complicated setup or configuration required.
* Can limit access by authentication.
* Can secure connections with TLS.
* Works with many CalDAV and CardDAV clients
* Stores all data on the file system in a simple folder structure.
* Can be extended with plugins.
* Is GPLv3-licensed free software.

For the complete documentation, please visit
[Radicale master Documentation](https://radicale.org/master.html).

Additional hints can be found
* [Radicale Wiki](https://github.com/Kozea/Radicale/wiki)
* [Radicale Issues](https://github.com/Kozea/Radicale/issues)
* [Radicale Discussions](https://github.com/Kozea/Radicale/discussions)

Before reporting an issue, please check
* [Radicale Wiki / Reporting Issues](https://github.com/Kozea/Radicale/wiki/01-‐-Reporting-Issues)

---

### Overview (`caldav_compat_tests/README.md`)

# CalDAV compatibility tests

These tests use the [caldav](https://pypi.org/project/caldav/) client
library together with
[caldav-server-tester](https://pypi.org/project/caldav-server-tester/) to
run a battery of CalDAV client/server interoperability checks against a
real Radicale server (started as a subprocess, listening on a free
localhost port).

The observed feature-support levels are compared against a known baseline
(`EXPECTED_DEVIATIONS` in `test_compatibility.py`). The goal is to catch
compatibility *regressions*: if Radicale starts failing (or passing) a
check differently than before, this test fails.

See also: [Kozea/Radicale#1911](https://github.com/Kozea/Radicale/issues/1911).

## Running the tests

### UV

```lang=shell
uv run --extra caldav_test pytest caldav_compat_tests
```

### Tox

```lang=shell
tox -c pyproject.toml -e caldav_compat_test
```

### Pip

```lang=shell
pip install -e ".[caldav_test]"
pytest caldav_compat_tests
```

## Pinned client library versions

The observed feature report depends not only on `caldav-server-tester`, but
also on the `caldav` client library (which defines the feature model and
how results are reported) and on the libraries it uses to evaluate search
and recurrence results (`icalendar`, `icalendar-searcher`,
`recurring-ical-events`). A new release of any of them can change the
report without any change to Radicale.

They are therefore all pinned to exact, known-good versions in the
`caldav_test` extra in `pyproject.toml`. That is the only place they are
pinned: CI, tox, uv and pip all install them via that extra. Bump them
deliberately in their own PR, updating `EXPECTED_DEVIATIONS` in the same
PR if the new versions change observed behaviour.

## Updating the baseline

If a change to Radicale (or a new release of `caldav-server-tester`)
intentionally changes the observed compatibility, run the tests, inspect
the failure output (it includes the full compatibility report and diff),
and update `EXPECTED_DEVIATIONS` in `test_compatibility.py` accordingly.
Please explain the change in the pull request description.

To print a full compatibility report by hand, point `caldav-server-tester`
(installed as part of the `caldav_test` extra) directly at a running
Radicale instance:

```lang=shell
caldav-server-tester --caldav-url http://127.0.0.1:5232/ \
    --caldav-username tester --caldav-password testpassword \
    --diff
```

---

### Overview (`integ_tests/README.md`)

# Integration tests

These tests use Playwright to run the tests agains a full Radicale instance.

## First time install

You need to install playwright. The easiest way to do this is to create a .venv with playwright inside. You can do this by trying to run the integ tests and then entering the .venv

### UV

Assuming you use uv to run/create your .venvs, note that the invocation will fail:

```lang=shell
uv run --extra integ_test pytest integ_tests
source .venv/bin/activate
```

then run

```lang=shell
playwright install --with-deps
```

### Tox

Tox will install the needed browser automatically. However, it will not automatically install the needed system depedencies, since those would need root permissions. To install all playwright with all needed libraries, run:

```lang=shell
tox -c pyproject.toml -e integ_test exec -- playwright install --with-deps
```

## Running the tests

### UV

if you use uv, you can run

```lang=shell
uv run --extra dev pytest integ_tests
```

### Tox

if you use tox, you can run

```lang=shell
tox -c pyproject.toml -e integ_test
```

---

### Overview (`radicale/web/README.md`)

# Built-in web UI

If you have tsc installed, you can type-check all JavaScript using

``` lang=shell
tsc -p radicale/web/jsconfig.json --noEmit --pretty
```

---

--- METRICS ---
- Files Extracted: 4
- Estimated Token Budget: ~1252 tokens
- Canonical Reference: https://codewiki.google/github.com/Kozea/Radicale