Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.

0 downloads

dbbasic-object-server/tests/test_conversions.py
Download zip
Clone
Clone with git
git clone https://gitstable.com/git/askrobots/dbbasic-object-server.git
HTTPS
https://gitstable.com/git/askrobots/dbbasic-object-server.git
SSH
ssh://git@gitstable.com:2222/askrobots/dbbasic-object-server.git

Cloning needs no sign-in. Pushing over HTTPS asks for your username and an access token. SSH needs your key under SSH keys.

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
3Three things had to be true before `/visitors` could answer "did any of
4that work", and each of them is a place where the obvious implementation
5is dishonest rather than merely wrong.
6
7**The cookie.** A first-party token is what turns Monday's reader and
8Thursday's buyer into one person instead of two strangers. It is also the
9point at which analytics products usually stop being honest, so every
10rule in docs/analytics.md is asserted here as behaviour and not as prose:
11set once and reused, never when Do Not Track or Global Privacy Control
12says no, never on a path a browser did not choose to visit, and NEVER in
13the same row as a `user_id`. That last one is one line of code away at all
14times, which is exactly why it is pinned by a test rather than by a
15comment.
16
17**The conversion.** The change dispatcher promises at-least-once
18delivery, and `status is confirmed` is a state an order SITS in rather
19than an edge it crosses, so this handler WILL see the same order again
20and again. A double-counted conversion is a permanent overcount in a
21report nothing will ever correct, so the replay test is the point of this
22file rather than a footnote to it.
23
24**The folds.** A funnel that hides its own uncertainty, a returning-
25visitor count presented as a census, and a median that quietly drops the
26journeys whose beginning aged out are all numbers that mislead precisely
27when somebody is relying on them. Each fold returns its caveat as DATA,
28and the tests assert the caveat is there.
29"""
30
31import asyncio
32import datetime
33import json
34import pathlib
35import shutil
36
37import pytest
38from conftest import stage_collection
39
40import object_analytics
41import object_conversions
42import object_execution
43import object_records
44import object_server
45import python_object_runtime
46
47REPO_ROOT = pathlib.Path(__file__).resolve().parents[1]
48PACKAGES = REPO_ROOT / "packages"
49ANALYTICS_OBJECTS = PACKAGES / "app-analytics" / "objects"
50RUNTIME = python_object_runtime.PythonObjectRuntime()
51
52UTC = datetime.timezone.utc
53NOW = datetime.datetime(2026, 7, 26, 12, 0, tzinfo=UTC)
54BROWSER = "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()
62def 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()
95def 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
114def 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
145def 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
151def page_views(data_dir):
152 return object_records.read_collection_records("page_views",
153 base_dir=data_dir)
154
155
156def 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
181def 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
192def 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
203def 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
210def 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
217def 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
230def 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
249def 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
258def 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
266def 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
281def 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
298def 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
308def 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
316def 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
332def 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
362def 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
372def 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
384def 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
395def 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
413def 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
428def 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
441def conversions(data_dir):
442 return object_records.read_collection_records("conversions",
443 base_dir=data_dir)
444
445
446def 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
457def 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
467def 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
476def 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
485def 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
515def 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
527def 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
541def 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
548def 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
560def 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
579def 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
591def 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
604def 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
620def 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
631def 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
636def 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
645def 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
666def 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
676def 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
695def 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
704def 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
717def 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
726def 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
735def 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
745def 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
762def 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
769def 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
781def 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
791def 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
798def 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
811def 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
824def 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
838def 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
853def 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
863def 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
870def 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
880def 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
891def 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
906def 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
914def 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
942def 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
959def 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
974def 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
983def 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
992def 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
1000def 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
1012def 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
1023def 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