detquantlib 5.8.0__tar.gz → 5.9.1__tar.gz

{detquantlib-5.8.0 → detquantlib-5.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detquantlib
-Version: 5.8.0
+Version: 5.9.1
 Summary: An internal library containing functions and classes that can be used across Quant models.
 License-File: LICENSE.txt
 Author: Dynamic Energy Trading
@@ -37,6 +37,7 @@ Description-Content-Type: text/markdown
 - [DET Quant Library](#det-quant-library)
   - [Table of Contents](#table-of-contents)
   - [Overview](#overview)
+  - [Snapshot Testing](#snapshot-testing)
   - [Exposed Symbols](#exposed-symbols)
     - [List of Exposed Symbols](#list-of-exposed-symbols)
   - [Configuration](#configuration)
@@ -62,6 +63,17 @@ Description-Content-Type: text/markdown
 The DET Quant Library is an internal library containing functions and classes that can be used
 across Quant models.
 
+## Snapshot Testing
+
+The `detquantlib.snapshot_testing` package provides snapshot (regression) tests for Quant models:
+each test runs a model end to end on a fixed set of inputs, and compares its outputs with a
+reviewed reference copy. Database calls are recorded once, locally, and replayed from disk in CI,
+which has no database access. The `SnowflakeClient` and `AzureClient` classes are supported out of
+the box.
+
+See [the snapshot testing guide](detquantlib/snapshot_testing/README.md) for how the framework
+works and how to set it up in a model repository.
+
 ## Exposed Symbols
 
 Some of the package's symbols (i.e. functions, classes, modules, etc.) are exposed via
@@ -93,12 +105,18 @@ Classes:
 - `BatteryState`:
   - `from detquantlib.assets import BatteryState`
   - `from detquantlib.assets.battery import BatteryState`
+- `DbCacheMissError`:
+  - `from detquantlib.snapshot_testing import DbCacheMissError`
+  - `from detquantlib.snapshot_testing.errors import DbCacheMissError`
 - `DetDatabase`:
   - `from detquantlib.data import DetDatabase`
   - `from detquantlib.data.databases.detdatabase import DetDatabase`
 - `Entsoe`:
   - `from detquantlib.data import Entsoe`
   - `from detquantlib.data.entsoe.entsoe import Entsoe`
+- `NetworkAccessBlockedError`:
+  - `from detquantlib.snapshot_testing import NetworkAccessBlockedError`
+  - `from detquantlib.snapshot_testing.errors import NetworkAccessBlockedError`
 - `OutputItem`:
   - `from detquantlib.outputs import OutputItem`
   - `from detquantlib.outputs.outputs_interface import OutputItem`
@@ -111,6 +129,12 @@ Classes:
 - `Sftp`:
   - `from detquantlib.data import Sftp`
   - `from detquantlib.data.sftp.sftp import Sftp`
+- `SnapshotCase`:
+  - `from detquantlib.snapshot_testing import SnapshotCase`
+  - `from detquantlib.snapshot_testing.cases import SnapshotCase`
+- `SnapshotConfig`:
+  - `from detquantlib.snapshot_testing import SnapshotConfig`
+  - `from detquantlib.snapshot_testing.config import SnapshotConfig`
 - `SnowflakeClient`:
   - `from detquantlib.data import SnowflakeClient`
   - `from detquantlib.data.databases.snowflake_client import SnowflakeClient`
@@ -132,12 +156,21 @@ Classes:
 
 Functions:
 
+- `create_case`:
+  - `from detquantlib.snapshot_testing import create_case`
+  - `from detquantlib.snapshot_testing.cases import create_case`
+- `discover_cases`:
+  - `from detquantlib.snapshot_testing import discover_cases`
+  - `from detquantlib.snapshot_testing.cases import discover_cases`
 - `list_to_sql_columns`:
   - `from detquantlib.data import list_to_sql_columns`
   - `from detquantlib.data.databases.helpers import list_to_sql_columns`
 - `list_to_sql_set`:
   - `from detquantlib.data import list_to_sql_set`
   - `from detquantlib.data.databases.helpers import list_to_sql_set`
+- `print_cases`:
+  - `from detquantlib.snapshot_testing import print_cases`
+  - `from detquantlib.snapshot_testing.cases import print_cases`
 
 <!-- END EXPOSED SYMBOLS AUTO-GENERATED -->
 

{detquantlib-5.8.0 → detquantlib-5.9.1}/README.md

@@ -7,6 +7,7 @@
 - [DET Quant Library](#det-quant-library)
   - [Table of Contents](#table-of-contents)
   - [Overview](#overview)
+  - [Snapshot Testing](#snapshot-testing)
   - [Exposed Symbols](#exposed-symbols)
     - [List of Exposed Symbols](#list-of-exposed-symbols)
   - [Configuration](#configuration)
@@ -32,6 +33,17 @@
 The DET Quant Library is an internal library containing functions and classes that can be used
 across Quant models.
 
+## Snapshot Testing
+
+The `detquantlib.snapshot_testing` package provides snapshot (regression) tests for Quant models:
+each test runs a model end to end on a fixed set of inputs, and compares its outputs with a
+reviewed reference copy. Database calls are recorded once, locally, and replayed from disk in CI,
+which has no database access. The `SnowflakeClient` and `AzureClient` classes are supported out of
+the box.
+
+See [the snapshot testing guide](detquantlib/snapshot_testing/README.md) for how the framework
+works and how to set it up in a model repository.
+
 ## Exposed Symbols
 
 Some of the package's symbols (i.e. functions, classes, modules, etc.) are exposed via
@@ -63,12 +75,18 @@ Classes:
 - `BatteryState`:
   - `from detquantlib.assets import BatteryState`
   - `from detquantlib.assets.battery import BatteryState`
+- `DbCacheMissError`:
+  - `from detquantlib.snapshot_testing import DbCacheMissError`
+  - `from detquantlib.snapshot_testing.errors import DbCacheMissError`
 - `DetDatabase`:
   - `from detquantlib.data import DetDatabase`
   - `from detquantlib.data.databases.detdatabase import DetDatabase`
 - `Entsoe`:
   - `from detquantlib.data import Entsoe`
   - `from detquantlib.data.entsoe.entsoe import Entsoe`
+- `NetworkAccessBlockedError`:
+  - `from detquantlib.snapshot_testing import NetworkAccessBlockedError`
+  - `from detquantlib.snapshot_testing.errors import NetworkAccessBlockedError`
 - `OutputItem`:
   - `from detquantlib.outputs import OutputItem`
   - `from detquantlib.outputs.outputs_interface import OutputItem`
@@ -81,6 +99,12 @@ Classes:
 - `Sftp`:
   - `from detquantlib.data import Sftp`
   - `from detquantlib.data.sftp.sftp import Sftp`
+- `SnapshotCase`:
+  - `from detquantlib.snapshot_testing import SnapshotCase`
+  - `from detquantlib.snapshot_testing.cases import SnapshotCase`
+- `SnapshotConfig`:
+  - `from detquantlib.snapshot_testing import SnapshotConfig`
+  - `from detquantlib.snapshot_testing.config import SnapshotConfig`
 - `SnowflakeClient`:
   - `from detquantlib.data import SnowflakeClient`
   - `from detquantlib.data.databases.snowflake_client import SnowflakeClient`
@@ -102,12 +126,21 @@ Classes:
 
 Functions:
 
+- `create_case`:
+  - `from detquantlib.snapshot_testing import create_case`
+  - `from detquantlib.snapshot_testing.cases import create_case`
+- `discover_cases`:
+  - `from detquantlib.snapshot_testing import discover_cases`
+  - `from detquantlib.snapshot_testing.cases import discover_cases`
 - `list_to_sql_columns`:
   - `from detquantlib.data import list_to_sql_columns`
   - `from detquantlib.data.databases.helpers import list_to_sql_columns`
 - `list_to_sql_set`:
   - `from detquantlib.data import list_to_sql_set`
   - `from detquantlib.data.databases.helpers import list_to_sql_set`
+- `print_cases`:
+  - `from detquantlib.snapshot_testing import print_cases`
+  - `from detquantlib.snapshot_testing.cases import print_cases`
 
 <!-- END EXPOSED SYMBOLS AUTO-GENERATED -->
 

detquantlib-5.9.1/detquantlib/snapshot_testing/README.md

@@ -0,0 +1,511 @@
+# Snapshot Testing Framework
+
+The `detquantlib.snapshot_testing` package provides snapshot (regression) tests for Quant models.
+Each test runs a model end to end, through its real entry point `run.run(input_dir, output_dir)`,
+on a fixed set of inputs. It then compares every file of the produced outputs folder with a
+reviewed reference copy (the _snapshot_) committed in the model repository.
+
+Snapshot tests show whether outputs _changed_, not whether they are _correct_. Any change must
+either be fixed or explicitly accepted, and is reviewed in the pull request diff.
+
+Key properties:
+
+- **No database access needed in CI.** Database calls are recorded once, locally, with database
+  access, and replayed from disk in all other runs.
+- **Diffable recordings.** Recorded tables are stored as CSV + JSON files, so changes to recorded
+  data or queries show up as line diffs in pull requests.
+- **Explicit failures.** A changed query, an unrecorded database call or an attempt to reach the
+  network fails immediately with a clear error, instead of timing out or returning other data.
+- **Reproducible runs.** The time can be frozen per test case, so models that use the current date
+  issue the same queries every day.
+- **Isolated.** Every patch is undone after each test: unit tests in the same pytest process see
+  no leftovers.
+
+## Table of Contents
+
+- [How It Works](#how-it-works)
+- [Supported Database Clients](#supported-database-clients)
+- [Setting Up a Model Repository](#setting-up-a-model-repository)
+- [Test Cases](#test-cases)
+- [Day-to-Day Usage](#day-to-day-usage)
+- [The DB Cache](#the-db-cache)
+- [Configuration Reference](#configuration-reference)
+- [Troubleshooting](#troubleshooting)
+- [Limitations and Pitfalls](#limitations-and-pitfalls)
+- [Package Structure](#package-structure)
+
+## How It Works
+
+A snapshot test runs one test case in one of three modes:
+
+| Mode    | Command                                   | Databases          | Effect                                                       |
+|---------|-------------------------------------------|--------------------|--------------------------------------------------------------|
+| replay  | `pytest tests/snapshot`                   | replayed from disk | Compares the outputs with the snapshot (what CI runs)        |
+| update  | `pytest tests/snapshot --snapshot-update` | replayed from disk | Overwrites the snapshot with the outputs                     |
+| record  | `pytest tests/snapshot --snapshot-record` | live (local only)  | Re-records the database calls, and overwrites the snapshot   |
+
+A run goes through the following steps (see `run_snapshot_case()` in `pytest_plugin.py`):
+
+1. The outputs folder `tests/snapshot/.actual/CaseXX/Outputs` is emptied. It is kept after the run
+   for inspection, and uploaded as an artifact by CI when the test fails.
+2. The database functions are patched:
+   - record mode: they run normally, and their results are saved to the case's `db_cache` folder;
+   - replay and update modes: they never run; their recorded results are returned instead.
+3. In replay and update modes, the network is blocked and the local `.env` file is ignored, so
+   that local runs behave exactly like CI (which has no credentials).
+4. The model runs through its real entry point, with the time frozen if the test case says so,
+   and with its logging isolated from the rest of the pytest process. The test only prints the
+   name and description of the test case: everything the model prints or logs to the console is
+   written to `tests/snapshot/.actual/CaseXX/console.txt` instead.
+5. The outputs are compared with the snapshot (replay mode), or replace it (update and record
+   modes).
+
+### Record and Replay of Database Calls
+
+The framework intercepts database calls at the level of functions, listed as _targets_ in the
+configuration (e.g. `SnowflakeClient.query`). Every call gets a cache key: a hash of the function
+name and of its meaningful arguments.
+
+- SQL text is whitespace-normalized: reformatting a query does not invalidate the recording.
+  SQLAlchemy `text()` objects are keyed on their SQL.
+- Parameters, dates and other plain values are part of the key.
+- DataFrames (e.g. the data passed to `write_table()`) are keyed on their shape, column names,
+  data types and content.
+- Clients, connections and engines are replaced by a constant placeholder, so that a real client
+  (record mode) and a client without credentials (replay mode) produce the same key.
+
+In replay mode, a call whose key was not recorded raises a `DbCacheMissError`, showing the call
+and the command to re-record. It never silently returns other data.
+
+Functions that only create connections (e.g. `SnowflakeClient.connect`, called when entering a
+`with SnowflakeClient() as client:` block) are _connection targets_: in replay mode they return an
+offline stub instead of connecting. The stub supports `with` and `close()`. Any other use of it
+means that a database call is not recorded, and raises a `NetworkAccessBlockedError`.
+
+Every module-level alias of a patched function is patched too (e.g. created by
+`from pkg.db import query`), so a model cannot bypass the recording by importing a function by
+name.
+
+### Network Guard
+
+In replay and update modes, any connection to a non-local address fails immediately with a
+`NetworkAccessBlockedError`, including the connect functions of drivers that open sockets in C code
+(`pyodbc`, `pymssql`, `turbodbc`). A forgotten data source therefore fails explicitly, instead of
+timing out in CI.
+
+### Frozen Time
+
+A test case can freeze the time (`frozen_time` in `case.toml`), with
+[time-machine](https://pypi.org/project/time-machine/): `datetime.now()`, `date.today()`,
+`time.time()` and `pd.Timestamp.now()` then return that moment during the whole run. This is
+required whenever the model derives dates, and therefore queries, from "today".
+
+In record mode, the live database calls run on the real clock, even when the case freezes the
+time: database drivers use the clock, e.g. to sign authentication tokens. Only the model sees the
+frozen time.
+
+`datetime.now()` returns the frozen moment in the _local_ time zone. The local time zone of CI
+runners must therefore be the one of the developer machines that recorded the test cases (see
+[CI Workflow](#ci-workflow)).
+
+### Isolation
+
+`run.py` calls `logging.shutdown()`, which normally closes every logging handler in the process,
+including those of pytest and of unit tests. During a snapshot run, it only closes the handlers
+created by that run, which are also detached afterwards. The exception hooks replaced by
+`detquantlib.utils.setup_logger` are restored as well. The working directory and the
+`INPUT_DIR` / `OUTPUT_DIR` environment variables are restored after each test.
+
+The model's console output (stdout, stderr, and console log handlers created by the model) is
+muted and written to `tests/snapshot/.actual/CaseXX/console.txt`, also when the model crashes.
+The run log written to the outputs folder is not affected.
+
+### Output Comparison
+
+Each file of the outputs folder is compared with its snapshot according to its type:
+
+| File type                   | Comparison                                                          |
+|-----------------------------|---------------------------------------------------------------------|
+| `.csv`, `.parquet`, `.xlsx` | As DataFrames, with numerical tolerances (`rtol`, `atol`)           |
+| `.json`                     | Recursively, with numerical tolerances                              |
+| Text (`.txt`, `.sql`, ...)  | Line by line (line endings ignored), with a unified diff            |
+| Anything else               | Byte by byte                                                        |
+
+Missing and unexpected files are reported too. Run logs (`*.log`, timestamps) and HTML files
+(`*.html`, e.g. Plotly figures with random element identifiers and ~5 MB of embedded plotly.js) are
+not compared by default.
+
+## Supported Database Clients
+
+The default configuration covers the database clients of `detquantlib.data`:
+
+| Method                          | `SnowflakeClient`               | `AzureClient`                   |
+|---------------------------------|---------------------------------|---------------------------------|
+| `query()`                       | recorded                        | recorded                        |
+| `load_table()`                  | through `query()`               | through `query()`               |
+| `list_tables()`                 | recorded                        | through `query()`               |
+| `query_batches()`               | recorded (batches)              | recorded (batches)              |
+| `write_table()`                 | recorded (row count)            | recorded (row count)            |
+| `execute()`                     | recorded (row count)            | recorded (row count)            |
+| `connect()`                     | offline stub in replay mode     | offline stub in replay mode     |
+
+Notes:
+
+- Methods that only call another recorded method are not recorded themselves, otherwise their
+  results would be recorded twice.
+- `query_batches()` returns a generator. In record mode, it is consumed entirely during the call,
+  and each batch is stored separately. In replay mode, the batches are returned by a generator.
+- Writes (`write_table()`, `execute()`) are _executed_ against the live databases in record mode,
+  as in a normal model run. In replay mode, they return the recorded row count. Since the written
+  data is part of the cache key, a change in the written data fails the test with a
+  `DbCacheMissError`.
+
+## Setting Up a Model Repository
+
+The framework expects the standard layout of Quant model repositories: `run.py`, with a function
+`run(input_dir, output_dir)` that calls `load_dotenv()`, at the repository root.
+
+### Files
+
+```
+<repo>/
+├── run.py, constants.py, src/, pyproject.toml
+├── .github/workflows/python-ci.yml
+└── tests/
+    ├── unit/
+    └── snapshot/
+        ├── conftest.py
+        ├── test_snapshots.py
+        └── cases/
+            └── Case01/
+                ├── case.toml
+                ├── Inputs/
+                ├── db_cache/            created by --snapshot-record
+                └── ExpectedOutputs/     created by --snapshot-record / --snapshot-update
+```
+
+pytest requires two files: command line options can only be registered from a `conftest.py` file
+(or a plugin loaded at startup), and tests are only collected from `test_*.py` files.
+
+`tests/snapshot/conftest.py` activates the command line options and the `snapshot_mode` fixture
+for the snapshot tests only:
+
+```python
+"""pytest configuration of the snapshot tests (detquantlib.snapshot_testing)."""
+
+from detquantlib.snapshot_testing.pytest_plugin import (
+    pytest_addoption,
+    pytest_configure,
+    snapshot_mode,
+)
+
+__all__ = ["pytest_addoption", "pytest_configure", "snapshot_mode"]
+```
+
+`tests/snapshot/test_snapshots.py` holds the model-specific settings (`CONFIG`, see
+[Configuration Reference](#configuration-reference)) and defines one test per test case:
+
+```python
+"""Snapshot tests: run the model on every test case and compare the outputs with the snapshot."""
+
+from pathlib import Path
+
+import pytest
+from detquantlib.snapshot_testing import SnapshotConfig, discover_cases
+from detquantlib.snapshot_testing.pytest_plugin import run_snapshot_case
+
+import run as model_entry_point  # run.py at the project root
+
+CONFIG = SnapshotConfig(snapshot_dir=Path(__file__).resolve().parent)
+CASES = discover_cases(CONFIG.cases_dir)
+
+
+@pytest.mark.snapshot
+@pytest.mark.parametrize("case", CASES, ids=[c.name for c in CASES])
+def test_snapshot(case, snapshot_mode, monkeypatch):
+    run_snapshot_case(case, snapshot_mode, monkeypatch, CONFIG, entry_point=model_entry_point)
+```
+
+Code outside the tests that needs the test cases (e.g. Invoke tasks listing or creating them)
+should build the folder from the snapshot tests folder, e.g.
+`SnapshotConfig(snapshot_dir=...).cases_dir`, rather than import `test_snapshots.py`. Importing
+it would also import the model, and imports through the `tests` folder (e.g.
+`from tests.snapshot... import`) break when another package named `tests` is on the Python path
+(e.g. the one of an editable install of detquantlib).
+
+### Dependencies and pytest Settings
+
+Add the test dependencies to the development group of the repository:
+
+```cmd
+poetry add --group dev pytest time-machine
+```
+
+In `pyproject.toml`, list the test folders explicitly, so that pytest loads
+`tests/snapshot/conftest.py` (and its command line options) at startup, and add the project root
+to the Python path:
+
+```toml
+[tool.pytest.ini_options]
+testpaths = ["tests/unit", "tests/snapshot"]
+pythonpath = ["."]
+```
+
+In `.gitignore`, ignore the produced outputs and the staging folder of recordings:
+
+```gitignore
+tests/snapshot/.actual/
+tests/snapshot/cases/*/db_cache.staging/
+```
+
+### CI Workflow
+
+The CI workflow runs the snapshot tests without database secrets, in the time zone of the
+developer machines, and uploads the produced outputs when the tests fail:
+
+```yaml
+jobs:
+  python_ci:
+    runs-on: ubuntu-latest
+    env:
+      TZ: Europe/Amsterdam  # same local time as the machines that record the test cases
+    steps:
+      # ... checkout, Python, Poetry, dependencies ...
+      - name: Run snapshot tests
+        id: snapshot_tests
+        run: poetry run pytest tests/snapshot -v
+
+      - name: Upload outputs of snapshot tests on failure
+        if: ${{ !cancelled() && steps.snapshot_tests.outcome == 'failure' }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: snapshot-actual-outputs
+          path: tests/snapshot/.actual/
+          include-hidden-files: true
+          if-no-files-found: ignore
+```
+
+`--snapshot-record` is refused when the `CI` environment variable is set.
+
+## Test Cases
+
+### Folder Layout
+
+Test cases are folders of `tests/snapshot/cases`, named `Case01`, `Case02`, ... (two or more
+digits), and sorted by number. Each contains:
+
+- `case.toml`: the description and settings of the test case;
+- `Inputs/`: the model inputs (settings JSON file, CSV files, ...);
+- `db_cache/`: the recorded database calls;
+- `ExpectedOutputs/`: the snapshot.
+
+Folders starting with `.` or `_` are skipped. Any other invalid folder (wrong name, duplicate
+number, missing `case.toml`, unknown key in `case.toml`) raises an error when the tests are
+collected, so that a typo cannot silently drop a test case.
+
+### case.toml
+
+```toml
+# Multi-line text uses triple quotes. Indentation and the line breaks right after the opening
+# and before the closing quotes are removed automatically.
+description = """
+    Base scenario: default settings, front-month horizon.
+    Second line of the description.
+    """
+
+# Freezes the time during the run. Give a UTC offset: a time without offset is read as UTC.
+frozen_time = 2026-06-30T08:00:00+02:00
+
+# Optional overrides of the defaults of CONFIG in test_snapshots.py
+rtol = 1e-6
+atol = 1e-9
+ignore = ["plots/*.png"]
+```
+
+| Key           | Default          | Meaning                                                            |
+|---------------|------------------|--------------------------------------------------------------------|
+| `description` | `""`             | Description, listed by `print_cases()`                             |
+| `frozen_time` | none (real time) | Moment at which the time is frozen during the run                  |
+| `rtol`        | `config.rtol`    | Relative tolerance of numerical comparisons                        |
+| `atol`        | `config.atol`    | Absolute tolerance of numerical comparisons                        |
+| `ignore`      | `[]`             | Additional output files not compared (glob patterns)               |
+
+`print_cases(cases_root)` lists the test cases and their descriptions:
+
+```
+- Case01:
+  Base scenario: default settings, front-month horizon.
+  Second line of the description.
+- Case02:
+  This is another description
+```
+
+### Creating a Test Case
+
+Step 1: Execute `create_case(inputs_dir, cases_root)`. The function handles the following actions:
+- Creates the folder of a new test case, with the lowest free case number.
+- Copies the given inputs folder (typically the project's default `Inputs` folder).
+- Writes a `case.toml` file to complete, which freezes the time at the moment of creation.
+
+Alternatively, test cases can also be created manually: create the folder with a `case.toml`
+file and an `Inputs` folder. Freeze the time (_before_ recording) if the model uses the current
+date.
+
+Step 2: Record the new test case with the following command:
+
+```cmd
+pytest tests/snapshot --snapshot-record -k Case02
+```
+
+## Day-to-Day Usage
+
+```cmd
+pytest tests/snapshot                                  # replay: offline, what CI runs
+pytest tests/snapshot -k Case01                        # a single test case
+pytest tests/snapshot --snapshot-update                # accept the current outputs (offline)
+pytest tests/snapshot --snapshot-record                # LOCAL ONLY: re-record from the databases
+pytest tests/snapshot --snapshot-record -k Case01      # re-record a single test case
+```
+
+- **The model outputs changed on purpose** (e.g. a new feature): run `--snapshot-update`, and
+  review the changes to `ExpectedOutputs` in the pull request.
+- **The database queries changed**, or the recorded data should be refreshed: run
+  `--snapshot-record` locally, with database access. Review the changes to `db_cache` (queries,
+  data) and `ExpectedOutputs`.
+- **A test fails in CI**: download the `snapshot-actual-outputs` artifact of the workflow run to
+  inspect the produced outputs and the model's console output (`console.txt`).
+
+## The DB Cache
+
+```
+db_cache/
+├── manifest.json                       cache key -> function, call arguments, file
+├── 001_SnowflakeClient_query.csv       values of the 1st distinct table returned
+├── 001_SnowflakeClient_query.dtypes.json   its column data types
+├── 002_AzureClient_execute.pkl         a result that is not a table (e.g. a row count)
+├── 003_AzureClient_query_batches_001.csv   the batches returned by query_batches()
+└── ...
+```
+
+- Files are numbered in call order, so re-recording a changed query overwrites the same file
+  names, and the change shows up as a line diff in the pull request.
+- Identical repeated calls are stored once.
+- `manifest.json` shows each recorded call with its normalized arguments, e.g. the SQL text.
+- Recordings are written to `db_cache.staging` and replace `db_cache` only once the whole run has
+  succeeded.
+
+### Table Format
+
+Tables are stored as `<name>.csv` (the values) and `<name>.dtypes.json` (the column names and
+data types). The round trip is exact, and verified when recording:
+
+- integers, floats (written with `repr`, without rounding), booleans and nullable types;
+- naive and time-zone-aware datetimes: values are written with their UTC offset, e.g.
+  `2026-03-29T03:00:00+02:00`, and converted back to their original time zone (IANA name and
+  `zoneinfo` / `pytz` library), so that daylight saving time switches are handled correctly;
+- timedeltas, string dtypes, and object columns holding one kind of value (`str`, `int`, `float`,
+  `bool`, `Decimal`, `date`, `time`, `datetime`);
+- NULL values (`None`, `NaN`, `NaT`, `NA` are restored as they were);
+- named, datetime and multi-level indexes.
+
+Tables that cannot be stored exactly (categorical columns, columns mixing value types, columns
+with both empty strings and NULLs) are stored as pickle files instead, with a warning: replay
+works, but the recording is not diffable. Results that are not tables (e.g. row counts) are
+always stored as pickle files.
+
+Do not store recordings with Git LFS: GitHub does not show diffs of LFS files. Keep recordings
+small instead, by querying only the data that a test case needs.
+
+## Configuration Reference
+
+`SnapshotConfig` holds the settings of the snapshot tests of a model repository:
+
+| Field                   | Default                         | Meaning                                       |
+|-------------------------|---------------------------------|-----------------------------------------------|
+| `snapshot_dir`          | (required)                      | Folder of the snapshot tests                  |
+| `project_root`          | grandparent of `snapshot_dir`   | Folder in which the model runs                |
+| `db_query_targets`      | `DEFAULT_DB_QUERY_TARGETS`      | Functions recorded and replayed               |
+| `db_connection_targets` | `DEFAULT_DB_CONNECTION_TARGETS` | Connection factories (stubbed in replay mode) |
+| `ignore_patterns`       | `DEFAULT_IGNORE_PATTERNS`       | Output files not compared (glob patterns)     |
+| `rtol`                  | `1e-8`                          | Relative tolerance of numerical comparisons   |
+| `atol`                  | `1e-10`                         | Absolute tolerance of numerical comparisons   |
+
+`cases_dir` (`snapshot_dir / "cases"`) and `actual_dir` (`snapshot_dir / ".actual"`) are derived
+from `snapshot_dir`.
+
+### Adding Database Functions
+
+If a model reaches a database without the clients of `detquantlib.data` (e.g. with its own helper
+functions), add those functions to the targets of `CONFIG`, in `tests/snapshot/test_snapshots.py`:
+
+```python
+from detquantlib.snapshot_testing import (
+    DEFAULT_DB_CONNECTION_TARGETS,
+    DEFAULT_DB_QUERY_TARGETS,
+    SnapshotConfig,
+)
+
+CONFIG = SnapshotConfig(
+    snapshot_dir=Path(__file__).resolve().parent,
+    db_query_targets=[*DEFAULT_DB_QUERY_TARGETS, "src.data_access:load_prices"],
+    db_connection_targets=[*DEFAULT_DB_CONNECTION_TARGETS, "src.data_access:connect"],
+)
+```
+
+- Targets use the format `"package.module:function"` or `"package.module:Class.method"`.
+- Prefer the highest-level function that both connects and returns data.
+- Do not list a function that only calls another listed function: its results would be recorded
+  twice, and the inner recordings would be reported as unused in replay mode.
+- List functions that only create connections as connection targets.
+
+## Troubleshooting
+
+| Error or warning                                    | Cause and solution                                                                                                                                |
+|-----------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
+| `DbCacheMissError: No DB cache found`               | The test case was never recorded. Record it locally with `--snapshot-record`.                                                                    |
+| `DbCacheMissError: No recorded result for ...`      | A query, its parameters or the written data changed, or a new database call was added. Re-record the test case. If the call depends on the current date, freeze the time in `case.toml`. |
+| `NetworkAccessBlockedError`                         | The model reaches the network or a database through a function that is not recorded. Add the function to the targets.                           |
+| `Snapshot mismatch for case ...`                    | The outputs changed. Fix the model, or accept the change with `--snapshot-update`.                                                               |
+| `No snapshot for case ...`                          | The test case has a DB cache but no snapshot. Create it with `--snapshot-update`.                                                                |
+| `... recorded DB result(s) were not requested`      | The model no longer makes some recorded calls: the recording may be stale. Re-record the test case.                                               |
+| `... cannot be stored as CSV + JSON ... pickle`     | A recorded table has an unsupported data type (see [Table Format](#table-format)). Replay works, but the recording is not diffable.             |
+| `--snapshot-record needs database access ...`       | Recording is refused in CI (`CI` environment variable set).                                                                                       |
+
+## Limitations and Pitfalls
+
+- **Time zone.** With a frozen time, `datetime.now()` depends on the local time zone. CI must use
+  the time zone of the machines that recorded the test cases (`TZ: Europe/Amsterdam`).
+- **Default database of a client.** The cache key does not include the client's configuration,
+  which differs between record mode (credentials) and replay mode (none). Identical SQL sent to
+  different default databases in one run shares one recording: qualify table names or pass
+  `database=...` in that case.
+- **Writes in record mode.** Recording runs the model against the live databases, including its
+  writes. Use credentials of a development environment.
+- **Multiprocessing.** Patches do not reach child processes: database calls made in child
+  processes are neither recorded nor blocked.
+- **Module-level caches.** Query results cached at module level (e.g. with `functools.cache`)
+  survive between test cases in the same pytest process. Clear them between runs.
+- **Binary outputs.** Binary files (e.g. PNG, PDF) are compared byte by byte and often embed
+  timestamps. Add them to the ignore patterns if they cause false failures.
+- **Recorded data is committed.** Make sure that the access rights of the repository suit the
+  sensitivity of the recorded data.
+- **Randomness.** The framework does not fix random seeds: models must make their results
+  reproducible themselves.
+- **Python 3.10.** `case.toml` files are read with `tomllib` (Python 3.11+) or, on Python 3.10,
+  with `tomli` (installed with pytest).
+
+## Package Structure
+
+| Module             | Content                                                                      |
+|--------------------|------------------------------------------------------------------------------|
+| `config.py`        | `SnapshotConfig` and the default targets, ignore patterns and tolerances     |
+| `cases.py`         | `SnapshotCase`, `discover_cases()`, `print_cases()`, `create_case()`         |
+| `recording.py`     | Cache keys, `DbRecorder` (record/replay), patching of the targets            |
+| `tables.py`        | DataFrame <-> CSV + dtypes JSON, with an exact round trip                    |
+| `isolation.py`     | Network guard, frozen time, logging isolation                                |
+| `comparison.py`    | Comparison of the outputs with the snapshot                                  |
+| `pytest_plugin.py` | pytest hooks, `snapshot_mode` fixture, `run_snapshot_case()` (needs pytest)  |
+| `errors.py`        | `DbCacheMissError`, `NetworkAccessBlockedError`                              |
+
+The package can be imported without pytest: only `pytest_plugin.py` needs it, and is not imported
+by `detquantlib.snapshot_testing`. The tests of the framework are in `tests/snapshot_testing`.