askrobots / dbbasic-object-server
Public
Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.
danq9
signup: the person chooses the password and name on the confirm page
83c7aa6
2 weeks, 5 days ago
History
test_conversions.py · 46.6 KB · 1035 lines
| 1 | """Goals, funnels, and the one cookie this server sets. |
| 2 | |
| 3 | Three things had to be true before `/visitors` could answer "did any of |
| 4 | that work", and each of them is a place where the obvious implementation |
| 5 | is dishonest rather than merely wrong. |
| 6 | |
| 7 | **The cookie.** A first-party token is what turns Monday's reader and |
| 8 | Thursday's buyer into one person instead of two strangers. It is also the |
| 9 | point at which analytics products usually stop being honest, so every |
| 10 | rule in docs/analytics.md is asserted here as behaviour and not as prose: |
| 11 | set once and reused, never when Do Not Track or Global Privacy Control |
| 12 | says no, never on a path a browser did not choose to visit, and NEVER in |
| 13 | the same row as a `user_id`. That last one is one line of code away at all |
| 14 | times, which is exactly why it is pinned by a test rather than by a |
| 15 | comment. |
| 16 | |
| 17 | **The conversion.** The change dispatcher promises at-least-once |
| 18 | delivery, and `status is confirmed` is a state an order SITS in rather |
| 19 | than an edge it crosses, so this handler WILL see the same order again |
| 20 | and again. A double-counted conversion is a permanent overcount in a |
| 21 | report nothing will ever correct, so the replay test is the point of this |
| 22 | file rather than a footnote to it. |
| 23 | |
| 24 | **The folds.** A funnel that hides its own uncertainty, a returning- |
| 25 | visitor count presented as a census, and a median that quietly drops the |
| 26 | journeys whose beginning aged out are all numbers that mislead precisely |
| 27 | when somebody is relying on them. Each fold returns its caveat as DATA, |
| 28 | and the tests assert the caveat is there. |
| 29 | """ |
| 30 | |
| 31 | import asyncio |
| 32 | import datetime |
| 33 | import json |
| 34 | import pathlib |
| 35 | import shutil |
| 36 | |
| 37 | import pytest |
| 38 | from conftest import stage_collection |
| 39 | |
| 40 | import object_analytics |
| 41 | import object_conversions |
| 42 | import object_execution |
| 43 | import object_records |
| 44 | import object_server |
| 45 | import python_object_runtime |
| 46 | |
| 47 | REPO_ROOT = pathlib.Path(__file__).resolve().parents[1] |
| 48 | PACKAGES = REPO_ROOT / "packages" |
| 49 | ANALYTICS_OBJECTS = PACKAGES / "app-analytics" / "objects" |
| 50 | RUNTIME = python_object_runtime.PythonObjectRuntime() |
| 51 | |
| 52 | UTC = datetime.timezone.utc |
| 53 | NOW = datetime.datetime(2026, 7, 26, 12, 0, tzinfo=UTC) |
| 54 | BROWSER = "Mozilla/5.0 (Macintosh) AppleWebKit/537.36 Chrome/128 Safari/537.36" |
| 55 | |
| 56 | |
| 57 | # =========================================================================== |
| 58 | # 1. The visitor cookie |
| 59 | # =========================================================================== |
| 60 | |
| 61 | @pytest.fixture() |
| 62 | def site(tmp_path, monkeypatch): |
| 63 | """An ASGI server with analytics on, the visitor cookie deliberately |
| 64 | switched ON, and one page object to hit. |
| 65 | |
| 66 | None of the cookie behaviour is testable in-process: the header is |
| 67 | added by the response layer and the token is stamped by the capture |
| 68 | hook, so a test that calls an object directly proves nothing about |
| 69 | either. These drive the app, same as tests/test_site_cookies.py. |
| 70 | |
| 71 | The cookie is OFF by default now, so this fixture has to ask for it. |
| 72 | That is the point rather than an inconvenience: every test below |
| 73 | describes a box whose operator made a deliberate choice, and the |
| 74 | default box -- the one that stores nothing on anybody's device -- is |
| 75 | covered by its own tests further down. |
| 76 | """ |
| 77 | data_dir = tmp_path / "data" |
| 78 | stage_collection(data_dir, "app-analytics", "page_views") |
| 79 | objects_dir = tmp_path / "objects" |
| 80 | (objects_dir / "site").mkdir(parents=True) |
| 81 | (objects_dir / "site" / "probe.py").write_text( |
| 82 | "import json\n" |
| 83 | "def GET(request):\n" |
| 84 | " return {'status': 200, 'content_type': 'application/json',\n" |
| 85 | " 'body': json.dumps(request.get('_cookies'))}\n") |
| 86 | monkeypatch.setenv("DBBASIC_OBJECTS_DIR", str(objects_dir)) |
| 87 | monkeypatch.setenv("DBBASIC_DATA_DIR", str(data_dir)) |
| 88 | monkeypatch.setenv("DBBASIC_ENABLE_SITE_ROUTES", "true") |
| 89 | monkeypatch.setenv("DBBASIC_ANALYTICS", "on") |
| 90 | monkeypatch.setenv("DBBASIC_ANALYTICS_VISITOR_COOKIE", "on") |
| 91 | return data_dir |
| 92 | |
| 93 | |
| 94 | @pytest.fixture() |
| 95 | def default_site(tmp_path, monkeypatch): |
| 96 | """The same server with nothing switched on but capture -- the |
| 97 | DEFAULT box. Analytics is recording, and still nothing is stored on |
| 98 | anybody's device.""" |
| 99 | data_dir = tmp_path / "data" |
| 100 | stage_collection(data_dir, "app-analytics", "page_views") |
| 101 | objects_dir = tmp_path / "objects" |
| 102 | (objects_dir / "site").mkdir(parents=True) |
| 103 | (objects_dir / "site" / "probe.py").write_text( |
| 104 | "def GET(request):\n" |
| 105 | " return {'status': 200, 'content_type': 'text/plain', 'body': 'ok'}\n") |
| 106 | monkeypatch.setenv("DBBASIC_OBJECTS_DIR", str(objects_dir)) |
| 107 | monkeypatch.setenv("DBBASIC_DATA_DIR", str(data_dir)) |
| 108 | monkeypatch.setenv("DBBASIC_ENABLE_SITE_ROUTES", "true") |
| 109 | monkeypatch.setenv("DBBASIC_ANALYTICS", "on") |
| 110 | monkeypatch.delenv("DBBASIC_ANALYTICS_VISITOR_COOKIE", raising=False) |
| 111 | return data_dir |
| 112 | |
| 113 | |
| 114 | def call(path, *, method="GET", headers=None): |
| 115 | sent = {} |
| 116 | |
| 117 | async def run(): |
| 118 | scope = {"type": "http", "method": method, "path": path, |
| 119 | "query_string": b"", |
| 120 | "headers": [(k.lower().encode(), v.encode()) |
| 121 | for k, v in (headers or {}).items()]} |
| 122 | received = {"done": False} |
| 123 | |
| 124 | async def receive(): |
| 125 | if received["done"]: |
| 126 | return {"type": "http.disconnect"} |
| 127 | received["done"] = True |
| 128 | return {"type": "http.request", "body": b"", "more_body": False} |
| 129 | |
| 130 | async def send(message): |
| 131 | if message["type"] == "http.response.start": |
| 132 | sent["status"] = message["status"] |
| 133 | sent["headers"] = [(k.decode("latin-1"), v.decode("latin-1")) |
| 134 | for k, v in message["headers"]] |
| 135 | elif message["type"] == "http.response.body": |
| 136 | sent.setdefault("body", b"") |
| 137 | sent["body"] += message.get("body", b"") |
| 138 | |
| 139 | await object_server.app(scope, receive, send) |
| 140 | |
| 141 | asyncio.run(run()) |
| 142 | return sent |
| 143 | |
| 144 | |
| 145 | def visitor_cookies(sent): |
| 146 | return [value for key, value in sent.get("headers", []) |
| 147 | if key.lower() == "set-cookie" |
| 148 | and value.startswith(object_analytics.VISITOR_COOKIE_NAME + "=")] |
| 149 | |
| 150 | |
| 151 | def page_views(data_dir): |
| 152 | return object_records.read_collection_records("page_views", |
| 153 | base_dir=data_dir) |
| 154 | |
| 155 | |
| 156 | def test_the_cookie_is_set_once_and_then_reused(site): |
| 157 | """Set on the first page and never again. A token reissued on every |
| 158 | request is not a thread at all -- every visit would look new, which is |
| 159 | the exact failure the cookie exists to fix, wearing a cookie's |
| 160 | clothes.""" |
| 161 | first = call("/probe") |
| 162 | minted = visitor_cookies(first) |
| 163 | assert len(minted) == 1 |
| 164 | assert "Path=/" in minted[0] and "HttpOnly" in minted[0] |
| 165 | assert "SameSite=Lax" in minted[0] |
| 166 | assert f"Max-Age={object_analytics.DEFAULT_VISITOR_DAYS * 86400}" in minted[0] |
| 167 | |
| 168 | token = minted[0].split("=", 1)[1].split(";", 1)[0] |
| 169 | assert token |
| 170 | |
| 171 | second = call("/probe", headers={ |
| 172 | "cookie": f"{object_analytics.VISITOR_COOKIE_NAME}={token}"}) |
| 173 | assert visitor_cookies(second) == [] |
| 174 | |
| 175 | # And both requests are threaded to the same visitor -- including the |
| 176 | # FIRST one, whose cookie the browser had not sent back yet. |
| 177 | rows = page_views(site) |
| 178 | assert [row["session_id"] for row in rows] == [token, token] |
| 179 | |
| 180 | |
| 181 | def test_the_token_is_opaque_and_carries_no_identity(site): |
| 182 | """Rule 2. Nothing derived from the request, so nothing reversible |
| 183 | back into one: a token hashed from IP and user agent would be a stable |
| 184 | identifier nobody could ever clear.""" |
| 185 | tokens = set() |
| 186 | for _ in range(3): |
| 187 | tokens.add(visitor_cookies(call("/probe", headers={ |
| 188 | "user-agent": BROWSER, "x-forwarded-for": "203.0.113.9"}))[0]) |
| 189 | assert len(tokens) == 3 |
| 190 | |
| 191 | |
| 192 | def test_do_not_track_suppresses_the_cookie_entirely(site): |
| 193 | """Rule 5, and note what it does NOT do: the request is still counted |
| 194 | as a page view. Refusing to be remembered is not refusing to be |
| 195 | counted, and dropping the row would quietly under-report traffic in |
| 196 | exactly the population most likely to notice.""" |
| 197 | sent = call("/probe", headers={"dnt": "1"}) |
| 198 | assert visitor_cookies(sent) == [] |
| 199 | rows = page_views(site) |
| 200 | assert len(rows) == 1 and rows[0]["session_id"] == "" |
| 201 | |
| 202 | |
| 203 | def test_global_privacy_control_suppresses_it_too(site): |
| 204 | """The same refusal in a different vocabulary, and it has to be |
| 205 | honoured in both -- a server that reads one header and not the other |
| 206 | honours whichever one its author happened to have heard of.""" |
| 207 | assert visitor_cookies(call("/probe", headers={"sec-gpc": "1"})) == [] |
| 208 | |
| 209 | |
| 210 | def test_dnt_zero_is_consent_and_not_a_refusal(site): |
| 211 | """`DNT: 0` is a positive statement, and an absent header is no |
| 212 | statement at all. Reading either as a refusal would mean this server |
| 213 | never remembered anybody, which is not honesty, just breakage.""" |
| 214 | assert len(visitor_cookies(call("/probe", headers={"dnt": "0"}))) == 1 |
| 215 | |
| 216 | |
| 217 | def test_it_is_never_set_on_an_asset_or_api_path(site): |
| 218 | """Two different refusals. An asset is not a page anyone chose to |
| 219 | visit; the API is a surface a SCRIPT talks to, and handing a cookie to |
| 220 | somebody's automation writes an identifier into a cron job.""" |
| 221 | assert visitor_cookies(call("/static/app.css")) == [] |
| 222 | assert visitor_cookies(call("/favicon.ico")) == [] |
| 223 | assert visitor_cookies(call("/healthz")) == [] |
| 224 | assert visitor_cookies(call("/api/mcp", method="POST")) == [] |
| 225 | assert visitor_cookies(call("/collections/notes/records")) == [] |
| 226 | |
| 227 | |
| 228 | # --- the default: nothing is stored on anybody's device ----------------------- |
| 229 | |
| 230 | def test_no_visitor_cookie_is_set_by_default(default_site): |
| 231 | """The posture the whole privacy design rests on. |
| 232 | |
| 233 | With DBBASIC_ANALYTICS_VISITOR_COOKIE unset -- the default -- this |
| 234 | server sets NO visitor cookie on any response, even with analytics |
| 235 | recording. It behaves exactly as it did before the cookie existed: |
| 236 | visitors counted by address, nothing written to a device, and so no |
| 237 | ePrivacy consent trigger anywhere in the world. A banner is not |
| 238 | needed because there is nothing to ask about. |
| 239 | """ |
| 240 | for path in ("/probe", "/", "/nope", "/probe?x=1"): |
| 241 | sent = call(path) |
| 242 | assert visitor_cookies(sent) == [], path |
| 243 | # And not by any other name either: no set-cookie at all on a |
| 244 | # page nobody signed in on and no basket was touched. |
| 245 | assert [value for key, value in sent["headers"] |
| 246 | if key.lower() == "set-cookie"] == [], path |
| 247 | |
| 248 | |
| 249 | def test_the_default_still_counts_visitors_by_address(default_site): |
| 250 | """Off is not broken. Rows are still written and still threadless, |
| 251 | which is the trade being made rather than a failure of it.""" |
| 252 | call("/probe") |
| 253 | rows = page_views(default_site) |
| 254 | assert rows and all(row["session_id"] == "" for row in rows) |
| 255 | assert rows[0]["ip"] or rows[0]["ip"] == "" # a row exists at all |
| 256 | |
| 257 | |
| 258 | def test_turning_it_on_is_the_only_thing_that_changes(site): |
| 259 | """The same server, one env var different, and now exactly one |
| 260 | identifier is stored -- with the lifetime the setting states.""" |
| 261 | minted = visitor_cookies(call("/probe")) |
| 262 | assert len(minted) == 1 |
| 263 | assert f"Max-Age={object_analytics.DEFAULT_VISITOR_DAYS * 86400}" in minted[0] |
| 264 | |
| 265 | |
| 266 | def test_the_switch_is_pure_and_defaults_off(): |
| 267 | assert not object_analytics.visitor_cookie_enabled({}) |
| 268 | assert not object_analytics.visitor_cookie_enabled( |
| 269 | {"DBBASIC_ANALYTICS_VISITOR_COOKIE": "off"}) |
| 270 | assert object_analytics.visitor_cookie_enabled( |
| 271 | {"DBBASIC_ANALYTICS_VISITOR_COOKIE": "on"}) |
| 272 | # Analytics being on is not enough on its own: a log and a device |
| 273 | # identifier are separate acts and this is the separate switch. |
| 274 | assert not object_analytics.should_set_visitor_cookie( |
| 275 | "/", {}, env={"DBBASIC_ANALYTICS": "on"}) |
| 276 | assert object_analytics.should_set_visitor_cookie( |
| 277 | "/", {}, env={"DBBASIC_ANALYTICS": "on", |
| 278 | "DBBASIC_ANALYTICS_VISITOR_COOKIE": "on"}) |
| 279 | |
| 280 | |
| 281 | def test_the_boot_line_states_the_obligation_rather_than_the_setting(): |
| 282 | """`DBBASIC_ANALYTICS_VISITOR_COOKIE=on` is not information; what it |
| 283 | commits an operator to is. Both the daemon and the server print this |
| 284 | line, so an operator who flips the switch is told what they took on |
| 285 | without having to go and read a document.""" |
| 286 | on = object_analytics.visitor_cookie_posture( |
| 287 | {"DBBASIC_ANALYTICS_VISITOR_COOKIE": "on"}) |
| 288 | assert "stores an identifier on a visitor's device" in on |
| 289 | assert "in the EU/UK that requires consent" in on |
| 290 | assert object_analytics.VISITOR_COOKIE_NAME in on |
| 291 | |
| 292 | off = object_analytics.visitor_cookie_posture({}) |
| 293 | assert "off (default)" in off |
| 294 | assert "no identifier is stored on any device" in off |
| 295 | assert "requires consent" not in off |
| 296 | |
| 297 | |
| 298 | def test_dnt_and_gpc_still_suppress_it_when_it_is_switched_on(site): |
| 299 | """Switching the cookie on does not switch the refusals off. These |
| 300 | are the two ways a browser says no, and both mean no cookie -- not a |
| 301 | shorter one, not an anonymised one.""" |
| 302 | assert visitor_cookies(call("/probe", headers={"dnt": "1"})) == [] |
| 303 | assert visitor_cookies(call("/probe", headers={"sec-gpc": "1"})) == [] |
| 304 | # DNT: 0 is a positive statement of consent, not a refusal. |
| 305 | assert len(visitor_cookies(call("/probe", headers={"dnt": "0"}))) == 1 |
| 306 | |
| 307 | |
| 308 | def test_nothing_is_set_when_analytics_is_off(tmp_path, monkeypatch, site): |
| 309 | """An identifier collected for no purpose is the worst trade |
| 310 | available: nothing is being recorded, so the cookie could not answer a |
| 311 | question even in principle.""" |
| 312 | monkeypatch.delenv("DBBASIC_ANALYTICS", raising=False) |
| 313 | assert visitor_cookies(call("/probe")) == [] |
| 314 | |
| 315 | |
| 316 | def test_the_visitor_token_is_never_handed_to_a_page_object(site): |
| 317 | """It is not a credential -- it is worth nothing to the object, which |
| 318 | is the point. What an object COULD do with it is write it next to a |
| 319 | user_id in a collection of its own: the forbidden join, performed by a |
| 320 | package the operator installed rather than by anything in this repo. A |
| 321 | token only the capture hook can see cannot be joined to anything.""" |
| 322 | sent = call("/probe", headers={ |
| 323 | "cookie": (f"cart=abc; {object_analytics.VISITOR_COOKIE_NAME}=TOKEN123; " |
| 324 | "dbbasic_session=SECRET")}) |
| 325 | assert json.loads(sent["body"]) == {"cart": "abc"} |
| 326 | assert b"TOKEN123" not in sent["body"] |
| 327 | assert b"SECRET" not in sent["body"] |
| 328 | |
| 329 | |
| 330 | # --- the join that must never happen ------------------------------------------ |
| 331 | |
| 332 | def test_a_page_view_never_carries_a_token_and_a_user_id_together(): |
| 333 | """docs/analytics.md, cookie rule 4. A row holding an opaque visitor |
| 334 | token AND an account id de-anonymises every page view that token ever |
| 335 | made, retroactively, for a person who was never asked. Enforced in |
| 336 | build_page_view rather than trusted to call sites, because the |
| 337 | enforcement has to survive a call site written by somebody who has not |
| 338 | read the docstring.""" |
| 339 | row = object_analytics.build_page_view( |
| 340 | path="/invoices", method="GET", status=200, ip="198.51.100.4", |
| 341 | headers={"cookie": f"{object_analytics.VISITOR_COOKIE_NAME}=tok"}, |
| 342 | owners=frozenset(), user_id="dana") |
| 343 | assert row["session_id"] == "tok" |
| 344 | assert row["user_id"] == "" |
| 345 | |
| 346 | # Same for the token this very response is minting. |
| 347 | minted = object_analytics.build_page_view( |
| 348 | path="/", method="GET", status=200, ip="198.51.100.4", headers={}, |
| 349 | owners=frozenset(), user_id="dana", minted_visitor_token="fresh") |
| 350 | assert minted["session_id"] == "fresh" and minted["user_id"] == "" |
| 351 | |
| 352 | # With no token there is nothing to correlate WITH, so a signed-in |
| 353 | # member's traffic is still labelled -- which pages members use is one |
| 354 | # of the most useful things this collection knows. |
| 355 | plain = object_analytics.build_page_view( |
| 356 | path="/invoices", method="GET", status=200, ip="198.51.100.4", |
| 357 | headers={"cookie": "dbbasic_session=abc"}, owners=frozenset(), |
| 358 | user_id="dana") |
| 359 | assert plain["session_id"] == "" and plain["user_id"] == "dana" |
| 360 | |
| 361 | |
| 362 | def test_a_conversion_never_carries_a_token_and_a_user_id_together(): |
| 363 | both = object_conversions.build_conversion( |
| 364 | event_type="order_confirmed", session_id="tok", user_id="dana") |
| 365 | assert both["session_id"] == "tok" and both["user_id"] == "" |
| 366 | |
| 367 | named = object_conversions.build_conversion( |
| 368 | event_type="order_confirmed", user_id="dana") |
| 369 | assert named["session_id"] == "" and named["user_id"] == "dana" |
| 370 | |
| 371 | |
| 372 | def test_no_row_the_server_writes_ever_joins_the_two(site): |
| 373 | """The property end-to-end rather than per-function: drive real |
| 374 | requests, signed-in and not, and assert no page_views row on disk has |
| 375 | both columns populated.""" |
| 376 | call("/probe") |
| 377 | call("/probe", headers={"cookie": "dbbasic_session=SECRET"}) |
| 378 | call("/probe", headers={"dnt": "1"}) |
| 379 | rows = page_views(site) |
| 380 | assert rows |
| 381 | assert not any(row["session_id"] and row["user_id"] for row in rows) |
| 382 | |
| 383 | |
| 384 | def test_the_cookie_lifetime_is_stated_and_never_indefinite(): |
| 385 | """Rule 3. "Indefinite" is how a session identifier quietly becomes a |
| 386 | permanent one, so junk and non-positive values fall back to the |
| 387 | default rather than being read as unbounded.""" |
| 388 | assert object_analytics.visitor_days({"DBBASIC_ANALYTICS_VISITOR_DAYS": "30"}) == 30 |
| 389 | assert object_analytics.visitor_days({}) == 180 |
| 390 | assert object_analytics.visitor_days({"DBBASIC_ANALYTICS_VISITOR_DAYS": "0"}) == 180 |
| 391 | assert object_analytics.visitor_days({"DBBASIC_ANALYTICS_VISITOR_DAYS": "-1"}) == 180 |
| 392 | assert object_analytics.visitor_days({"DBBASIC_ANALYTICS_VISITOR_DAYS": "soon"}) == 180 |
| 393 | |
| 394 | |
| 395 | def test_an_older_session_id_cookie_is_still_read(): |
| 396 | """`build_page_view` read a cookie named `session_id` before this |
| 397 | existed. It is never SET now -- two names would be two populations of |
| 398 | visitors that cannot be compared -- but a box that has one keeps its |
| 399 | thread instead of being counted as a stranger on the day this |
| 400 | shipped.""" |
| 401 | row = object_analytics.build_page_view( |
| 402 | path="/", method="GET", status=200, ip="1.2.3.4", |
| 403 | headers={"cookie": "session_id=legacy42"}, owners=frozenset()) |
| 404 | assert row["session_id"] == "legacy42" |
| 405 | assert not object_analytics.should_set_visitor_cookie( |
| 406 | "/", {"cookie": "session_id=legacy42"}, env={"DBBASIC_ANALYTICS": "on"}) |
| 407 | |
| 408 | |
| 409 | # =========================================================================== |
| 410 | # 2. Recording a conversion |
| 411 | # =========================================================================== |
| 412 | |
| 413 | def conversion_env(tmp_path, monkeypatch): |
| 414 | data_dir = tmp_path / "data" |
| 415 | for package, collection in (("app-analytics", "conversions"), |
| 416 | ("app-orders", "orders"), |
| 417 | ("app-invoices", "invoices"), |
| 418 | ("app-payments", "payments"), |
| 419 | ("app-intake", "scans")): |
| 420 | stage_collection(data_dir, package, collection) |
| 421 | objects_root = tmp_path / "objects" |
| 422 | shutil.copytree(ANALYTICS_OBJECTS, objects_root, dirs_exist_ok=True) |
| 423 | monkeypatch.setenv("DBBASIC_DATA_DIR", str(data_dir)) |
| 424 | monkeypatch.setenv("DBBASIC_OBJECTS_DIR", str(objects_root)) |
| 425 | return data_dir, objects_root |
| 426 | |
| 427 | |
| 428 | def fire(objects_root, collection, record_id, action="update"): |
| 429 | """One change event, shaped exactly as object_change_dispatch sends |
| 430 | them (raw verb in `action`, participle in `event`).""" |
| 431 | return object_execution.execute_object( |
| 432 | RUNTIME, |
| 433 | object_execution.ObjectExecutionRequest( |
| 434 | "system_record_conversion", method="EVENT", |
| 435 | payload={"event": f"{collection}.record.{action}d", |
| 436 | "collection": collection, "record_id": record_id, |
| 437 | "action": action}), |
| 438 | roots=[objects_root]).result |
| 439 | |
| 440 | |
| 441 | def conversions(data_dir): |
| 442 | return object_records.read_collection_records("conversions", |
| 443 | base_dir=data_dir) |
| 444 | |
| 445 | |
| 446 | def an_order(data_dir, order_id="ord-1", *, status="confirmed", **fields): |
| 447 | record = {"id": order_id, "doc_type": "sale", "number": "SO-0001", |
| 448 | "customer_name": "Ada Lovelace", "customer_email": "ada@x.test", |
| 449 | "currency": "USD", "status": status, "order_date": "2026-07-01", |
| 450 | "subtotal_cents": "2400", "total_cents": "2400", |
| 451 | "owner_id": "shop"} |
| 452 | record.update({key: str(value) for key, value in fields.items()}) |
| 453 | return object_records.create_collection_record( |
| 454 | "orders", record, base_dir=data_dir, preserve_read_only=True) |
| 455 | |
| 456 | |
| 457 | def an_invoice(data_dir, invoice_id="inv-1"): |
| 458 | return object_records.create_collection_record( |
| 459 | "invoices", |
| 460 | {"id": invoice_id, "number": "INV-1", "customer_name": "Ada", |
| 461 | "customer_email": "ada@x.test", "currency": "USD", "status": "sent", |
| 462 | "issue_date": "2026-07-01", "due_date": "2026-07-15", |
| 463 | "total_cents": "2400", "owner_id": "shop"}, |
| 464 | base_dir=data_dir, preserve_read_only=True) |
| 465 | |
| 466 | |
| 467 | def a_payment(data_dir, payment_id="pay-1", *, status="received", cents=2400): |
| 468 | return object_records.create_collection_record( |
| 469 | "payments", |
| 470 | {"id": payment_id, "invoice_id": "inv-1", "amount_cents": str(cents), |
| 471 | "method": "card", "received_on": "2026-07-02", "status": status, |
| 472 | "owner_id": "shop"}, |
| 473 | base_dir=data_dir) |
| 474 | |
| 475 | |
| 476 | def a_scan(data_dir, scan_id="scan-1", *, status="confirmed"): |
| 477 | return object_records.create_collection_record( |
| 478 | "scans", |
| 479 | {"id": scan_id, "filename": "receipt.jpg", "content_type": "image/jpeg", |
| 480 | "source": "phone", "category_hint": "receipt", "status": status, |
| 481 | "owner_id": "dana"}, |
| 482 | base_dir=data_dir) |
| 483 | |
| 484 | |
| 485 | def test_a_confirmed_order_is_counted_once_and_a_replay_counts_nothing( |
| 486 | tmp_path, monkeypatch): |
| 487 | """THE test in this file. The dispatcher is at-least-once by design |
| 488 | and `confirmed` is a state an order sits in, so this handler sees the |
| 489 | same order on every later write. Twice counted is a report that says |
| 490 | the shop did double the business it did, and nothing downstream will |
| 491 | ever correct it.""" |
| 492 | data_dir, objects_root = conversion_env(tmp_path, monkeypatch) |
| 493 | an_order(data_dir) |
| 494 | |
| 495 | result = fire(objects_root, "orders", "ord-1") |
| 496 | assert result["recorded"] == ["order_confirmed"] |
| 497 | |
| 498 | rows = conversions(data_dir) |
| 499 | assert len(rows) == 1 |
| 500 | assert rows[0]["event_type"] == "order_confirmed" |
| 501 | assert json.loads(rows[0]["metadata"]) == { |
| 502 | "amount_cents": 2400, "currency": "USD", "order_number": "SO-0001", |
| 503 | "source": "orders/ord-1"} |
| 504 | |
| 505 | replay = fire(objects_root, "orders", "ord-1") |
| 506 | assert replay["recorded"] == [] |
| 507 | assert replay["skipped_already_counted"] == ["order_confirmed"] |
| 508 | assert len(conversions(data_dir)) == 1 |
| 509 | |
| 510 | # And a third time, through the `created` door rather than `updated`. |
| 511 | fire(objects_root, "orders", "ord-1", action="create") |
| 512 | assert len(conversions(data_dir)) == 1 |
| 513 | |
| 514 | |
| 515 | def test_the_marker_is_the_source_in_the_metadata_blob(tmp_path, monkeypatch): |
| 516 | """The claim being recorded is "this transition was counted", so it is |
| 517 | recorded on the count. A stamped flag on the order would be a second |
| 518 | record that can disagree with the first -- and the schema is fixed and |
| 519 | correct, so a private bookkeeping column would be the worse trade.""" |
| 520 | data_dir, objects_root = conversion_env(tmp_path, monkeypatch) |
| 521 | an_order(data_dir) |
| 522 | fire(objects_root, "orders", "ord-1") |
| 523 | assert object_conversions.already_recorded( |
| 524 | conversions(data_dir), "order_confirmed", "orders/ord-1") |
| 525 | |
| 526 | |
| 527 | def test_a_collected_order_is_a_second_goal_not_a_duplicate(tmp_path, monkeypatch): |
| 528 | """The money was taken when the order was confirmed and the food was |
| 529 | handed over when somebody walked in for it. A shop that wants to know |
| 530 | how many ready orders were actually collected cannot ask that of |
| 531 | `order_confirmed`.""" |
| 532 | data_dir, objects_root = conversion_env(tmp_path, monkeypatch) |
| 533 | an_order(data_dir, status="collected", fulfillment_method="pickup") |
| 534 | |
| 535 | result = fire(objects_root, "orders", "ord-1") |
| 536 | assert sorted(result["recorded"]) == ["order_collected", "order_confirmed"] |
| 537 | assert len(conversions(data_dir)) == 2 |
| 538 | assert fire(objects_root, "orders", "ord-1")["recorded"] == [] |
| 539 | |
| 540 | |
| 541 | def test_a_draft_order_is_not_a_conversion(tmp_path, monkeypatch): |
| 542 | data_dir, objects_root = conversion_env(tmp_path, monkeypatch) |
| 543 | an_order(data_dir, status="draft") |
| 544 | assert fire(objects_root, "orders", "ord-1")["recorded"] == [] |
| 545 | assert conversions(data_dir) == [] |
| 546 | |
| 547 | |
| 548 | def test_a_purchase_order_is_money_going_out_and_is_never_counted( |
| 549 | tmp_path, monkeypatch): |
| 550 | """One shared schema carries both sales and purchases here. Counting a |
| 551 | confirmed PO as a conversion would report a shop's own buying as its |
| 552 | business won.""" |
| 553 | data_dir, objects_root = conversion_env(tmp_path, monkeypatch) |
| 554 | an_order(data_dir, doc_type="purchase") |
| 555 | result = fire(objects_root, "orders", "ord-1") |
| 556 | assert result["recorded"] == [] |
| 557 | assert "purchase" in result["skipped"] |
| 558 | |
| 559 | |
| 560 | def test_a_payment_is_counted_once_and_a_bounced_one_never_is( |
| 561 | tmp_path, monkeypatch): |
| 562 | data_dir, objects_root = conversion_env(tmp_path, monkeypatch) |
| 563 | an_invoice(data_dir) |
| 564 | a_payment(data_dir) |
| 565 | a_payment(data_dir, "pay-2", status="bounced", cents=900) |
| 566 | |
| 567 | assert fire(objects_root, "payments", "pay-1", |
| 568 | action="create")["recorded"] == ["payment_received"] |
| 569 | assert fire(objects_root, "payments", "pay-2", |
| 570 | action="create")["recorded"] == [] |
| 571 | assert fire(objects_root, "payments", "pay-1", |
| 572 | action="create")["recorded"] == [] |
| 573 | |
| 574 | rows = conversions(data_dir) |
| 575 | assert len(rows) == 1 |
| 576 | assert json.loads(rows[0]["metadata"])["amount_cents"] == 2400 |
| 577 | |
| 578 | |
| 579 | def test_a_confirmed_scan_is_counted_and_an_unconfirmed_one_is_not( |
| 580 | tmp_path, monkeypatch): |
| 581 | data_dir, objects_root = conversion_env(tmp_path, monkeypatch) |
| 582 | a_scan(data_dir) |
| 583 | a_scan(data_dir, "scan-2", status="extracted") |
| 584 | |
| 585 | assert fire(objects_root, "scans", "scan-1")["recorded"] == ["scan_confirmed"] |
| 586 | assert fire(objects_root, "scans", "scan-2")["recorded"] == [] |
| 587 | assert fire(objects_root, "scans", "scan-1")["recorded"] == [] |
| 588 | assert len(conversions(data_dir)) == 1 |
| 589 | |
| 590 | |
| 591 | def test_a_conversion_row_never_carries_a_visitor_token(tmp_path, monkeypatch): |
| 592 | """Honest rather than lazy. These four goals are back-office |
| 593 | transitions with no browser anywhere near them, and the basket's |
| 594 | `carts.session_token` is a DIFFERENT identifier in a different |
| 595 | namespace -- stamping it here would silently merge two populations and |
| 596 | produce a funnel that looks stitched and is not.""" |
| 597 | data_dir, objects_root = conversion_env(tmp_path, monkeypatch) |
| 598 | an_order(data_dir) |
| 599 | fire(objects_root, "orders", "ord-1") |
| 600 | row = conversions(data_dir)[0] |
| 601 | assert row["session_id"] == "" and row["user_id"] == "" |
| 602 | |
| 603 | |
| 604 | def test_no_analytics_installed_degrades_honestly(tmp_path, monkeypatch): |
| 605 | """Silence here would look exactly like "already counted", and the |
| 606 | shop would never find out it had no numbers.""" |
| 607 | data_dir = tmp_path / "data" |
| 608 | stage_collection(data_dir, "app-orders", "orders") |
| 609 | objects_root = tmp_path / "objects" |
| 610 | shutil.copytree(ANALYTICS_OBJECTS, objects_root, dirs_exist_ok=True) |
| 611 | monkeypatch.setenv("DBBASIC_DATA_DIR", str(data_dir)) |
| 612 | an_order(data_dir) |
| 613 | |
| 614 | result = fire(objects_root, "orders", "ord-1") |
| 615 | assert result["ok"] is True |
| 616 | assert result["recorded"] == [] |
| 617 | assert "app-analytics not installed" in result["skipped"] |
| 618 | |
| 619 | |
| 620 | def test_a_vanished_record_is_a_skip_and_never_a_crash(tmp_path, monkeypatch): |
| 621 | """A reaction may never fail the write that triggered it.""" |
| 622 | data_dir, objects_root = conversion_env(tmp_path, monkeypatch) |
| 623 | assert fire(objects_root, "orders", "gone")["skipped"] == "order gone" |
| 624 | assert fire(objects_root, "contacts", "c-1")["recorded"] == [] |
| 625 | |
| 626 | |
| 627 | # =========================================================================== |
| 628 | # 3. The folds |
| 629 | # =========================================================================== |
| 630 | |
| 631 | def view(token, path, *, ip="10.0.0.1", at="2026-07-20T09:00:00Z"): |
| 632 | return {"session_id": token, "ip": ip, "path": path, "created_at": at, |
| 633 | "status": "200", "user_agent": BROWSER, "is_owner": "false"} |
| 634 | |
| 635 | |
| 636 | def conversion(event_type, token="", *, at="2026-07-20T10:00:00Z", source=""): |
| 637 | row = object_conversions.build_conversion( |
| 638 | event_type=event_type, session_id=token, source=source) |
| 639 | row["created_at"] = at |
| 640 | return row |
| 641 | |
| 642 | |
| 643 | # --- the funnel ----------------------------------------------------------------- |
| 644 | |
| 645 | def test_the_funnel_counts_distinct_visitors_at_each_step(): |
| 646 | """Distinct visitors, not requests. Somebody who reloads the checkout |
| 647 | four times is one person deciding, and counting the reloads turns a |
| 648 | hesitation into a crowd.""" |
| 649 | rows = [ |
| 650 | view("a", "/shop", at="2026-07-20T09:00:00Z"), |
| 651 | view("a", "/shop", at="2026-07-20T09:01:00Z"), |
| 652 | view("a", "/checkout", at="2026-07-20T09:05:00Z"), |
| 653 | view("a", "/checkout", at="2026-07-20T09:06:00Z"), |
| 654 | view("b", "/shop", ip="10.0.0.2", at="2026-07-20T10:00:00Z"), |
| 655 | view("c", "/checkout", ip="10.0.0.3", at="2026-07-20T11:00:00Z"), |
| 656 | ] |
| 657 | fold = object_conversions.funnel(rows, [], ["/shop", "/checkout"]) |
| 658 | assert [step["visitors"] for step in fold["steps"]] == [2, 1] |
| 659 | assert fold["steps"][1]["drop_off"] == 1 |
| 660 | assert fold["steps"][1]["drop_off_pct"] == 50.0 |
| 661 | # c reached /checkout without ever passing /shop: a funnel is a |
| 662 | # sequence, not a set of independent counts. |
| 663 | assert fold["entered"] == 2 and fold["converted"] == 1 |
| 664 | |
| 665 | |
| 666 | def test_a_step_must_happen_after_the_one_before_it(): |
| 667 | """Somebody who bought last week and browsed today did not convert |
| 668 | today. Without the ordering rule a funnel is a Venn diagram wearing a |
| 669 | funnel's labels, and it always flatters.""" |
| 670 | rows = [view("a", "/checkout", at="2026-07-20T09:00:00Z"), |
| 671 | view("a", "/shop", at="2026-07-21T09:00:00Z")] |
| 672 | fold = object_conversions.funnel(rows, [], ["/shop", "/checkout"]) |
| 673 | assert [step["visitors"] for step in fold["steps"]] == [1, 0] |
| 674 | |
| 675 | |
| 676 | def test_the_funnel_reports_how_much_of_itself_is_ip_stitched(): |
| 677 | """The point of the whole module. Rows with no token can only be |
| 678 | threaded by address, which is better than dropping them and is not the |
| 679 | same as knowing: an office behind one connection is one thread that |
| 680 | looks like a very decisive shopper. So the fraction is returned as |
| 681 | data, next to the numbers it qualifies.""" |
| 682 | rows = [ |
| 683 | view("a", "/shop"), view("a", "/checkout"), |
| 684 | view("", "/shop", ip="10.0.0.9"), view("", "/checkout", ip="10.0.0.9"), |
| 685 | view("", "/shop", ip="10.0.0.8"), |
| 686 | ] |
| 687 | fold = object_conversions.funnel(rows, [], ["/shop", "/checkout"]) |
| 688 | assert fold["entered"] == 3 |
| 689 | assert fold["ip_stitched"] == 2 |
| 690 | assert fold["ip_stitched_pct"] == 66.7 |
| 691 | assert fold["steps"][1]["ip_stitched"] == 1 |
| 692 | assert any("stitched by IP address" in text for text in fold["caveats"]) |
| 693 | |
| 694 | |
| 695 | def test_an_event_step_matches_a_conversion_on_the_same_thread(): |
| 696 | rows = [view("a", "/shop", at="2026-07-20T09:00:00Z"), |
| 697 | view("b", "/shop", ip="10.0.0.2", at="2026-07-20T09:00:00Z")] |
| 698 | goals = [conversion("order_confirmed", "a", at="2026-07-20T09:30:00Z")] |
| 699 | fold = object_conversions.funnel(rows, goals, ["/shop", "order_confirmed"]) |
| 700 | assert [step["visitors"] for step in fold["steps"]] == [2, 1] |
| 701 | assert fold["steps"][1]["kind"] == "event" |
| 702 | |
| 703 | |
| 704 | def test_conversions_with_no_token_are_named_rather_than_dropped(): |
| 705 | """Today that is most of them, because a back-office transition has no |
| 706 | browser anywhere near it. A funnel whose last step reads zero without |
| 707 | explaining why is a funnel somebody will conclude is broken -- or |
| 708 | worse, believe.""" |
| 709 | rows = [view("a", "/shop")] |
| 710 | goals = [conversion("order_confirmed"), conversion("order_confirmed")] |
| 711 | fold = object_conversions.funnel(rows, goals, ["/shop", "order_confirmed"]) |
| 712 | assert fold["unthreaded_conversions"] == 2 |
| 713 | assert fold["steps"][1]["visitors"] == 0 |
| 714 | assert any("no visitor token" in text for text in fold["caveats"]) |
| 715 | |
| 716 | |
| 717 | def test_a_path_step_is_a_prefix_and_an_event_step_is_exact(): |
| 718 | rows = [view("a", "/shop/product/mug")] |
| 719 | goals = [conversion("order_confirmed", "a", at="2026-07-20T12:00:00Z")] |
| 720 | fold = object_conversions.funnel(rows, goals, ["/shop", "order_confirmed"]) |
| 721 | assert [step["visitors"] for step in fold["steps"]] == [1, 1] |
| 722 | assert object_conversions.funnel( |
| 723 | rows, goals, ["/shop", "order"])["steps"][1]["visitors"] == 0 |
| 724 | |
| 725 | |
| 726 | def test_steps_can_be_written_as_strings_or_as_labelled_objects(): |
| 727 | assert object_conversions.normalize_steps(["/shop", "order_confirmed"]) == [ |
| 728 | {"label": "/shop", "kind": "path", "match": "/shop"}, |
| 729 | {"label": "order_confirmed", "kind": "event", "match": "order_confirmed"}] |
| 730 | assert object_conversions.normalize_steps( |
| 731 | [{"label": "Browsed", "path": "/shop"}]) == [ |
| 732 | {"label": "Browsed", "kind": "path", "match": "/shop"}] |
| 733 | |
| 734 | |
| 735 | def test_normalizing_steps_is_idempotent(): |
| 736 | """A page validates the setting once so it can report a bad row before |
| 737 | rendering anything, then hands the result to `funnel`, which |
| 738 | normalizes again. A normalizer that rejects its own output turns that |
| 739 | entirely reasonable sequence into a 500 -- which is how this was |
| 740 | found.""" |
| 741 | once = object_conversions.normalize_steps(["/shop", "order_confirmed"]) |
| 742 | assert object_conversions.normalize_steps(once) == once |
| 743 | |
| 744 | |
| 745 | def test_a_malformed_funnel_setting_is_reported_not_raised(): |
| 746 | """An operator who typed bad JSON into a settings row needs to be told |
| 747 | which row and why, on the screen where they typed it. A misconfigured |
| 748 | funnel and a funnel nobody entered look identical, and only one of |
| 749 | them is your fault.""" |
| 750 | steps, error = object_conversions.parse_funnel_steps("{not json") |
| 751 | assert steps == [] and "not valid JSON" in error |
| 752 | steps, error = object_conversions.parse_funnel_steps('"/shop"') |
| 753 | assert steps == [] and "JSON list" in error |
| 754 | steps, error = object_conversions.parse_funnel_steps( |
| 755 | '[{"path": "/shop", "event_type": "x"}]') |
| 756 | assert steps == [] and "one or the other" in error |
| 757 | assert object_conversions.parse_funnel_steps("") == ([], "") |
| 758 | assert object_conversions.parse_funnel_steps( |
| 759 | '["/shop", "order_confirmed"]')[0][0]["match"] == "/shop" |
| 760 | |
| 761 | |
| 762 | def test_an_unconfigured_funnel_is_not_an_empty_one(): |
| 763 | fold = object_conversions.funnel([view("a", "/shop")], [], []) |
| 764 | assert fold["configured"] is False and fold["steps"] == [] |
| 765 | |
| 766 | |
| 767 | # --- new versus returning ---------------------------------------------------------- |
| 768 | |
| 769 | def test_returning_visitors_are_counted_by_token_across_days(): |
| 770 | """The most useful ratio a site has, and invisible without the cookie: |
| 771 | somebody who reads the pitch on Monday and comes back on Thursday was |
| 772 | three strangers before this.""" |
| 773 | rows = [view("a", "/", at="2026-07-24T09:00:00Z"), |
| 774 | view("a", "/shop", at="2026-07-26T09:00:00Z"), |
| 775 | view("b", "/", ip="10.0.0.2", at="2026-07-26T09:00:00Z")] |
| 776 | fold = object_conversions.returning_visitors(rows, 7, now=NOW) |
| 777 | assert fold["returning"] == 1 and fold["new"] == 1 |
| 778 | assert fold["returning_pct"] == 50.0 |
| 779 | |
| 780 | |
| 781 | def test_several_pages_in_one_visit_is_not_a_return(): |
| 782 | """A person reading three pages over lunch has not returned; they are |
| 783 | still here.""" |
| 784 | rows = [view("a", "/", at="2026-07-26T09:00:00Z"), |
| 785 | view("a", "/shop", at="2026-07-26T09:05:00Z"), |
| 786 | view("a", "/pricing", at="2026-07-26T09:09:00Z")] |
| 787 | fold = object_conversions.returning_visitors(rows, 7, now=NOW) |
| 788 | assert fold == dict(fold, new=1, returning=0) |
| 789 | |
| 790 | |
| 791 | def test_a_token_first_seen_before_the_window_is_returning(): |
| 792 | rows = [view("a", "/", at="2026-06-01T09:00:00Z"), |
| 793 | view("a", "/shop", at="2026-07-26T09:00:00Z")] |
| 794 | fold = object_conversions.returning_visitors(rows, 7, now=NOW) |
| 795 | assert fold["returning"] == 1 and fold["new"] == 0 |
| 796 | |
| 797 | |
| 798 | def test_the_returning_count_says_it_is_a_floor(): |
| 799 | """Returned as DATA, not as prose in a docstring, so a surface cannot |
| 800 | render the number without being handed the caveat to render beside |
| 801 | it. Every error in it points the same way -- a cleared cookie, a |
| 802 | private window, a second browser and a phone are each a new visitor -- |
| 803 | which is the right direction to be wrong in, and still wrong.""" |
| 804 | fold = object_conversions.returning_visitors( |
| 805 | [view("a", "/", at="2026-07-26T09:00:00Z")], 7, now=NOW) |
| 806 | assert fold["floor"] is True |
| 807 | assert "never a census" in fold["caveat"] |
| 808 | assert "cleared cookie" in fold["caveat"] |
| 809 | |
| 810 | |
| 811 | def test_the_size_of_the_blind_spot_is_reported_beside_the_number(): |
| 812 | """Anyone who sent Do Not Track has no token and cannot appear on |
| 813 | either side of the split. How many of them there are belongs on the |
| 814 | same screen as the ratio they are missing from.""" |
| 815 | rows = [view("a", "/", at="2026-07-26T09:00:00Z"), |
| 816 | view("", "/", ip="10.0.0.7", at="2026-07-26T09:00:00Z"), |
| 817 | view("", "/shop", ip="10.0.0.8", at="2026-07-26T09:00:00Z")] |
| 818 | fold = object_conversions.returning_visitors(rows, 7, now=NOW) |
| 819 | assert fold["counted"] == 1 and fold["no_token_addresses"] == 2 |
| 820 | |
| 821 | |
| 822 | # --- time to conversion ------------------------------------------------------------- |
| 823 | |
| 824 | def test_time_to_conversion_measures_from_the_first_page_seen(): |
| 825 | rows = [view("a", "/", at="2026-07-20T09:00:00Z"), |
| 826 | view("a", "/shop", at="2026-07-22T09:00:00Z"), |
| 827 | view("b", "/", ip="10.0.0.2", at="2026-07-25T09:00:00Z")] |
| 828 | goals = [conversion("order_confirmed", "a", at="2026-07-24T09:00:00Z"), |
| 829 | conversion("order_confirmed", "b", at="2026-07-25T21:00:00Z")] |
| 830 | fold = object_conversions.time_to_conversion(rows, goals) |
| 831 | assert fold["count"] == 2 |
| 832 | assert fold["max_days"] == 4.0 |
| 833 | assert fold["min_days"] == 0.5 |
| 834 | assert fold["median_days"] == 2.25 |
| 835 | assert fold["same_day"] == 1 |
| 836 | |
| 837 | |
| 838 | def test_a_visitor_whose_first_page_predates_the_window_is_counted_apart(): |
| 839 | """page_views is bounded by days AND rows, so the slowest journeys are |
| 840 | exactly the ones whose beginning ages out first. Dropping them |
| 841 | silently would bias the median toward fast conversions -- the number |
| 842 | would improve every time retention was shortened, which is the most |
| 843 | dangerous shape a metric can have.""" |
| 844 | rows = [view("a", "/", at="2026-07-25T09:00:00Z")] |
| 845 | goals = [conversion("order_confirmed", "a", at="2026-07-26T09:00:00Z"), |
| 846 | conversion("order_confirmed", "gone", at="2026-07-26T09:00:00Z")] |
| 847 | fold = object_conversions.time_to_conversion(rows, goals) |
| 848 | assert fold["count"] == 1 and fold["median_days"] == 1.0 |
| 849 | assert fold["no_first_view"] == 1 |
| 850 | assert any("aged out" in text for text in fold["caveats"]) |
| 851 | |
| 852 | |
| 853 | def test_a_first_page_far_outside_any_window_still_measures_correctly(): |
| 854 | """The row is here, so the duration is knowable, and it is knowably |
| 855 | long: 40 days is the answer, not a number clipped to the report's |
| 856 | window.""" |
| 857 | rows = [view("a", "/", at="2026-06-01T00:00:00Z"), |
| 858 | view("a", "/shop", at="2026-07-10T00:00:00Z")] |
| 859 | goals = [conversion("order_confirmed", "a", at="2026-07-11T00:00:00Z")] |
| 860 | assert object_conversions.time_to_conversion(rows, goals)["median_days"] == 40.0 |
| 861 | |
| 862 | |
| 863 | def test_a_conversion_before_its_first_page_view_is_clamped_and_counted(): |
| 864 | rows = [view("a", "/", at="2026-07-26T09:00:00Z")] |
| 865 | goals = [conversion("order_confirmed", "a", at="2026-07-20T09:00:00Z")] |
| 866 | fold = object_conversions.time_to_conversion(rows, goals) |
| 867 | assert fold["median_days"] == 0.0 and fold["before_first_view"] == 1 |
| 868 | |
| 869 | |
| 870 | def test_unthreaded_conversions_are_reported_apart_from_aged_out_ones(): |
| 871 | """Different causes with different fixes: one is a goal recorded away |
| 872 | from any browser, the other is retention. Merging them into one |
| 873 | 'unmatched' count would hide which.""" |
| 874 | fold = object_conversions.time_to_conversion( |
| 875 | [], [conversion("order_confirmed"), conversion("x", "ghost")]) |
| 876 | assert fold["unthreaded"] == 1 and fold["no_first_view"] == 1 |
| 877 | assert fold["count"] == 0 and fold["median_days"] is None |
| 878 | |
| 879 | |
| 880 | def test_conversions_group_by_event_type_with_their_threaded_share(): |
| 881 | goals = [conversion("order_confirmed", at="2026-07-20T09:00:00Z"), |
| 882 | conversion("order_confirmed", "a", at="2026-07-21T09:00:00Z"), |
| 883 | conversion("payment_received", at="2026-07-21T09:00:00Z")] |
| 884 | summary = object_conversions.by_event_type(goals) |
| 885 | assert summary[0] == {"event_type": "order_confirmed", "count": 2, |
| 886 | "threaded": 1, "first": "2026-07-20T09:00:00Z", |
| 887 | "last": "2026-07-21T09:00:00Z"} |
| 888 | assert summary[1]["event_type"] == "payment_received" |
| 889 | |
| 890 | |
| 891 | def test_a_metadata_blob_that_is_not_json_never_breaks_a_report(): |
| 892 | """It is a free-text column; a report must survive whatever ended up |
| 893 | in it.""" |
| 894 | assert object_conversions.parse_metadata("not json at all") == {} |
| 895 | assert object_conversions.parse_metadata("[1,2,3]") == {} |
| 896 | assert object_conversions.parse_metadata('{"source": "orders/1"}') == { |
| 897 | "source": "orders/1"} |
| 898 | assert object_conversions.recorded_sources( |
| 899 | [{"event_type": "x", "metadata": "junk"}]) == set() |
| 900 | |
| 901 | |
| 902 | # =========================================================================== |
| 903 | # 4. The page |
| 904 | # =========================================================================== |
| 905 | |
| 906 | def render(payload=None): |
| 907 | return object_execution.execute_object( |
| 908 | RUNTIME, |
| 909 | object_execution.ObjectExecutionRequest( |
| 910 | "site_visitors", method="GET", payload=payload or {}), |
| 911 | roots=[ANALYTICS_OBJECTS]).result |
| 912 | |
| 913 | |
| 914 | def page_env(tmp_path, monkeypatch, *, settings=(), views=(), goals=()): |
| 915 | data_dir = tmp_path / "data" |
| 916 | stage_collection(data_dir, "app-analytics", "page_views") |
| 917 | stage_collection(data_dir, "app-analytics", "conversions") |
| 918 | rows = "".join(f"s{index}\t{key}\t{value}\t\n" |
| 919 | for index, (key, value) in enumerate(settings)) |
| 920 | stage_collection(data_dir, "app-settings", "app_settings", rows=rows) |
| 921 | monkeypatch.setenv("DBBASIC_DATA_DIR", str(data_dir)) |
| 922 | monkeypatch.setenv("DBBASIC_ANALYTICS", "on") |
| 923 | # These describe the box whose operator chose the visitor cookie -- |
| 924 | # new-versus-returning, the floor caveat and the cookie note only |
| 925 | # exist there. The default box gets its own test below, which asserts |
| 926 | # the page says the question is not asked rather than answering it |
| 927 | # with a zero. |
| 928 | monkeypatch.setenv("DBBASIC_ANALYTICS_VISITOR_COOKIE", "on") |
| 929 | for row in views: |
| 930 | row = dict(row) |
| 931 | row.pop("created_at", None) |
| 932 | object_records.create_collection_record("page_views", row, |
| 933 | base_dir=data_dir, actor="test") |
| 934 | for row in goals: |
| 935 | row = dict(row) |
| 936 | row.pop("created_at", None) |
| 937 | object_records.create_collection_record("conversions", row, |
| 938 | base_dir=data_dir, actor="test") |
| 939 | return data_dir |
| 940 | |
| 941 | |
| 942 | def test_the_page_says_what_to_configure_when_no_funnel_is_set( |
| 943 | tmp_path, monkeypatch): |
| 944 | """An empty funnel table would read as "nobody converted". A funnel |
| 945 | nobody has described yet is a settings row away, and the example is |
| 946 | built from what THIS server actually recorded, so it can be copied |
| 947 | rather than invented.""" |
| 948 | page_env(tmp_path, monkeypatch, |
| 949 | views=[view("a", "/shop", at="") for _ in range(2)], |
| 950 | goals=[conversion("order_confirmed", source="orders/ord-1")]) |
| 951 | body = render({"_identity": {"user_id": "dan"}})["body"] |
| 952 | |
| 953 | assert "No funnel is configured" in body |
| 954 | assert "analytics.funnel_steps" in body |
| 955 | assert "order_confirmed" in body # copied from the real goals |
| 956 | assert "/shop" in body |
| 957 | |
| 958 | |
| 959 | def test_the_page_renders_a_configured_funnel(tmp_path, monkeypatch): |
| 960 | page_env( |
| 961 | tmp_path, monkeypatch, |
| 962 | settings=(("analytics.funnel_steps", |
| 963 | '["/shop", "/checkout", "order_confirmed"]'),), |
| 964 | views=[view("a", "/shop", at=""), view("a", "/checkout", at=""), |
| 965 | view("b", "/shop", ip="10.0.0.2", at="")], |
| 966 | goals=[conversion("order_confirmed", source="orders/ord-1")]) |
| 967 | body = render({"_identity": {"user_id": "dan"}})["body"] |
| 968 | |
| 969 | assert "No funnel is configured" not in body |
| 970 | assert "IP-stitched" in body |
| 971 | assert "/checkout" in body |
| 972 | |
| 973 | |
| 974 | def test_the_page_reports_a_broken_funnel_setting_rather_than_an_empty_one( |
| 975 | tmp_path, monkeypatch): |
| 976 | page_env(tmp_path, monkeypatch, |
| 977 | settings=(("analytics.funnel_steps", "{nope"),), |
| 978 | views=[view("a", "/shop", at="")]) |
| 979 | body = render({"_identity": {"user_id": "dan"}})["body"] |
| 980 | assert "could not be read" in body |
| 981 | |
| 982 | |
| 983 | def test_the_page_shows_new_versus_returning_with_the_floor_note( |
| 984 | tmp_path, monkeypatch): |
| 985 | page_env(tmp_path, monkeypatch, views=[view("a", "/shop", at="")]) |
| 986 | body = render({"_identity": {"user_id": "dan"}})["body"] |
| 987 | assert "New versus returning" in body |
| 988 | assert "floor, never a census" in body.lower() or "A floor, never a census" in body |
| 989 | assert "cleared cookie" in body |
| 990 | |
| 991 | |
| 992 | def test_the_page_lists_goals_by_event_type(tmp_path, monkeypatch): |
| 993 | page_env(tmp_path, monkeypatch, views=[view("a", "/shop", at="")], |
| 994 | goals=[conversion("order_confirmed", source="orders/ord-1"), |
| 995 | conversion("payment_received", source="payments/pay-1")]) |
| 996 | body = render({"_identity": {"user_id": "dan"}})["body"] |
| 997 | assert "order_confirmed" in body and "payment_received" in body |
| 998 | |
| 999 | |
| 1000 | def test_the_page_says_so_when_conversions_was_never_installed( |
| 1001 | tmp_path, monkeypatch): |
| 1002 | """A confident zero where the truth is "nothing was ever recorded" is |
| 1003 | the exact failure this whole page is written against.""" |
| 1004 | data_dir = tmp_path / "data" |
| 1005 | stage_collection(data_dir, "app-analytics", "page_views") |
| 1006 | monkeypatch.setenv("DBBASIC_DATA_DIR", str(data_dir)) |
| 1007 | monkeypatch.setenv("DBBASIC_ANALYTICS", "on") |
| 1008 | body = render({"_identity": {"user_id": "dan"}})["body"] |
| 1009 | assert "No <code>conversions</code> collection" in body |
| 1010 | |
| 1011 | |
| 1012 | def test_the_page_still_says_an_ip_is_not_a_person(tmp_path, monkeypatch): |
| 1013 | """The cookie improves the RETURNING question and moves no ceiling at |
| 1014 | all. The day that note disappears is the day this page starts |
| 1015 | over-claiming.""" |
| 1016 | page_env(tmp_path, monkeypatch, views=[view("a", "/shop", at="")]) |
| 1017 | body = render({"_identity": {"user_id": "dan"}})["body"] |
| 1018 | assert "distinct IP address" in body |
| 1019 | assert "dbbasic_visitor" in body |
| 1020 | assert "Do Not Track" in body |
| 1021 | |
| 1022 | |
| 1023 | def test_the_page_does_not_answer_new_versus_returning_when_no_cookie_is_set( |
| 1024 | tmp_path, monkeypatch): |
| 1025 | """The default box. "0% returning" would be a confident zero where |
| 1026 | the truth is that the question is not asked -- the exact failure this |
| 1027 | page is written against -- and it would also have /visitors quietly |
| 1028 | disagreeing with /privacy, which says no identifier is stored.""" |
| 1029 | page_env(tmp_path, monkeypatch, views=[view("a", "/shop", at="")]) |
| 1030 | monkeypatch.delenv("DBBASIC_ANALYTICS_VISITOR_COOKIE", raising=False) |
| 1031 | body = render({"_identity": {"user_id": "dan"}})["body"] |
| 1032 | assert "Not measured on this server" in body |
| 1033 | assert "% returning" not in body |
| 1034 | assert "asks the browser to remember nothing at all" in body |
| 1035 | assert "distinct IP address" in body # the ceiling note stays |