:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import json
from posthog.test.base import BaseTest
from unittest import TestCase
from parameterized import parameterized
from posthog import redis
from products.notebooks.backend.collab import StepEntry, submit_steps
from products.notebooks.backend.collab_stream import STREAM_KEY_PATTERN, STREAM_MAX_LENGTH
from products.notebooks.backend.markdown_collab import (
MAX_PUBLISHED_DIFF_BYTES,
MarkdownDiff,
apply_utf16_text_changes,
build_markdown_update_diff,
fetch_missed_markdown_updates,
get_markdown_notebook_markdown,
markdown_crc,
publish_notebook_update,
submit_markdown_update,
utf16_single_span_diff,
)
from products.notebooks.backend.presence import PRESENCE_STREAM_KEY_PATTERN, PRESENCE_TTL_SECONDS, publish_presence
def markdown_doc(markdown: str) -> dict:
return {
"type": "doc",
"content": [{"type": "ph-markdown-notebook", "attrs": {"nodeId": "n1", "markdown": markdown}}],
}
class TestNotebookCollab(BaseTest):
def test_submit_to_empty_stream_seeds_position_from_caller(self):
# No init endpoint anymore — first writer trusts last_seen_version (loaded from Postgres).
result = submit_steps(
self.team.pk,
"nb1",
"client1",
[{"stepType": "replace", "from": 0, "to": 0}],
5,
last_saved_version=5,
)
assert result.status == "accepted"
assert result.version == 6
def test_submit_steps_accepted(self):
result = submit_steps(
self.team.pk,
"nb3",
"client1",
[{"stepType": "replace", "from": 0, "to": 0}],
0,
last_saved_version=0,
)
assert result.status == "accepted"
assert result.version == 1
def test_submit_steps_rejected_on_version_mismatch(self):
submit_steps(
self.team.pk,
"nb4",
"client1",
[{"stepType": "replace", "from": 0, "to": 0}],
0,
last_saved_version=0,
)
result = submit_steps(
self.team.pk,
"nb4",
"client2",
[{"stepType": "replace", "from": 1, "to": 1}],
0,
last_saved_version=1,
)
assert result.status == "conflict"
assert result.version == 1
assert result.steps_since == [
StepEntry(step={"stepType": "replace", "from": 0, "to": 0}, client_id="client1"),
]
def test_submit_multiple_steps_as_batch(self):
steps = [
{"stepType": "replace", "from": 0, "to": 0},
{"stepType": "replace", "from": 1, "to": 1},
{"stepType": "replace", "from": 2, "to": 2},
]
result = submit_steps(self.team.pk, "nb5", "client1", steps, 0, last_saved_version=0)
assert result.status == "accepted"
assert result.version == 3
@parameterized.expand(
[
("two_clients_sequential", "nb_multi_2", 2),
("three_clients_sequential", "nb_multi_3", 3),
]
)
def test_multiple_clients_sequential(self, _name, notebook_id, num_clients):
expected_version = 0
for i in range(num_clients):
result = submit_steps(
self.team.pk,
notebook_id,
f"client{i}",
[{"stepType": "replace", "from": i, "to": i}],
expected_version,
last_saved_version=expected_version,
)
assert result.status == "accepted"
expected_version += 1
assert expected_version == num_clients
def test_submit_steps_returns_stale_when_stream_trimmed(self):
submit_steps(
self.team.pk,
"nb_trimmed",
"client1",
[{"stepType": "replace", "from": 0, "to": 0}],
0,
last_saved_version=0,
)
submit_steps(
self.team.pk,
"nb_trimmed",
"client1",
[{"stepType": "replace", "from": 1, "to": 1}],
1,
last_saved_version=1,
)
client = redis.get_client()
# Force-trim past version 1 to simulate MAXLEN/TTL eviction; version 2 (id 2-0) survives.
client.xtrim(
STREAM_KEY_PATTERN.format(team_id=self.team.pk, notebook_id="nb_trimmed"),
minid="2-0",
)
result = submit_steps(
self.team.pk,
"nb_trimmed",
"client2",
[{"stepType": "replace", "from": 2, "to": 2}],
0,
last_saved_version=2,
)
assert result.status == "stale"
assert result.version == 2
assert result.steps_since is None
def test_empty_stream_with_stale_client_baseline_returns_stale(self):
# Stream lost (e.g. TTL expired) — Postgres still has the high version. A stale tab whose
# baseline doesn't match Postgres must not be accepted; otherwise its save would
# overwrite Postgres with a lower version. Client must reload from Postgres.
result = submit_steps(
self.team.pk,
"nb_stale_after_expiry",
"client_stale",
[{"stepType": "replace", "from": 0, "to": 0}],
last_seen_version=937,
last_saved_version=946,
)
assert result.status == "stale"
assert result.version == 946
assert result.steps_since is None
def test_empty_stream_with_client_ahead_of_postgres_returns_stale(self):
# Defensive: even if the client is somehow ahead of Postgres (legacy PATCH path went
# backwards, Postgres restore, etc.) we still cannot rebase against an empty stream.
result = submit_steps(
self.team.pk,
"nb_client_ahead",
"client_ahead",
[{"stepType": "replace", "from": 0, "to": 0}],
last_seen_version=946,
last_saved_version=937,
)
assert result.status == "stale"
assert result.version == 937
assert result.steps_since is None
def test_empty_stream_with_matching_postgres_accepts(self):
# The legitimate first save after a Redis flush: client baseline matches Postgres so
# the empty stream is safely seeded from there.
result = submit_steps(
self.team.pk,
"nb_first_save_after_flush",
"client1",
[{"stepType": "replace", "from": 0, "to": 0}],
last_seen_version=946,
last_saved_version=946,
)
assert result.status == "accepted"
assert result.version == 947
def test_non_empty_lagging_stream_with_postgres_matching_baseline_resyncs(self):
# Failed XADDs (publish errors are swallowed) can leave the stream behind Postgres.
# When the client's baseline matches Postgres, the save is accepted and the stream
# resyncs forward — otherwise every save would wedge on a permanently lagging stream.
submit_steps(
self.team.pk,
"nb_client_ahead_nonempty",
"client1",
[{"stepType": "replace", "from": 0, "to": 0}],
0,
last_saved_version=0,
)
result = submit_steps(
self.team.pk,
"nb_client_ahead_nonempty",
"client_resync",
[{"stepType": "replace", "from": 1, "to": 1}],
last_seen_version=5,
last_saved_version=5,
)
assert result.status == "accepted"
assert result.version == 6
def test_non_empty_lagging_stream_with_mismatched_baseline_returns_stale(self):
# Stream behind the caller AND the caller disagrees with Postgres: nothing to rebase
# against, the client must reload.
submit_steps(
self.team.pk,
"nb_client_ahead_mismatch",
"client1",
[{"stepType": "replace", "from": 0, "to": 0}],
0,
last_saved_version=0,
)
result = submit_steps(
self.team.pk,
"nb_client_ahead_mismatch",
"client_stale",
[{"stepType": "replace", "from": 1, "to": 1}],
last_seen_version=5,
last_saved_version=3,
)
assert result.status == "stale"
assert result.version == 1
assert result.steps_since is None
def test_submit_steps_continues_after_update_event(self):
publish_notebook_update(self.team.pk, "nb_update_event", 1)
result = submit_steps(
self.team.pk,
"nb_update_event",
"client1",
[{"stepType": "replace", "from": 0, "to": 0}],
1,
last_saved_version=1,
)
assert result.status == "accepted"
assert result.version == 2
def test_submit_steps_treats_missed_update_event_as_stale(self):
publish_notebook_update(self.team.pk, "nb_missed_update_event", 1)
result = submit_steps(
self.team.pk,
"nb_missed_update_event",
"client1",
[{"stepType": "replace", "from": 0, "to": 0}],
0,
last_saved_version=1,
)
assert result.status == "stale"
assert result.version == 1
assert result.steps_since is None
def test_stream_maxlen_constant_is_sane(self):
# Sanity: MAXLEN must comfortably hold an hour of edits. Adjust deliberately if changed.
assert STREAM_MAX_LENGTH >= 1000
class TestUtf16Diff(TestCase):
@parameterized.expand(
[
("insert_middle", "hello world", "hello brave world"),
("delete_middle", "hello brave world", "hello world"),
("replace_middle", "hello world", "hello there"),
("append", "hello", "hello world"),
("prepend", "world", "hello world"),
("delete_all", "hello", ""),
("insert_into_empty", "", "hello"),
("repeated_chars", "aaaa", "aaa"),
("emoji_replaced", "before 🦔 after", "before 🦕 after"),
("emoji_inserted", "before after", "before 🦔 after"),
("emoji_deleted", "before 🦔 after", "before after"),
("text_after_emoji", "🦔a", "🦔b"),
("only_emoji_swap_shared_high_surrogate", "🦔", "🦕"),
("multibyte_text", "naïve café", "naïve cafés ✨"),
]
)
def test_diff_round_trips_through_apply(self, _name, base, next_text):
change = utf16_single_span_diff(base, next_text)
assert change is not None
assert apply_utf16_text_changes(base, [change]) == next_text
def test_diff_of_equal_strings_is_none(self):
assert utf16_single_span_diff("same", "same") is None
def test_diff_offsets_are_utf16_code_units(self):
# "🦔" is two UTF-16 code units, so the trailing char sits at unit offset 2.
assert utf16_single_span_diff("🦔a", "🦔b") == {"start": 2, "end": 3, "text": "b"}
@parameterized.expand(
[
("end_beyond_base", "abc", [{"start": 0, "end": 4, "text": "x"}]),
("start_after_end", "abc", [{"start": 2, "end": 1, "text": "x"}]),
(
"overlapping_changes",
"abcdef",
[{"start": 0, "end": 3, "text": "x"}, {"start": 2, "end": 4, "text": "y"}],
),
("non_numeric_offsets", "abc", [{"start": "0", "end": 1, "text": "x"}]),
("missing_text", "abc", [{"start": 0, "end": 1}]),
]
)
def test_apply_rejects_invalid_changes(self, _name, base, changes):
assert apply_utf16_text_changes(base, changes) is None
def test_apply_multiple_ascending_changes(self):
assert (
apply_utf16_text_changes(
"abcdef", [{"start": 0, "end": 1, "text": "X"}, {"start": 3, "end": 5, "text": "Y"}]
)
== "XbcYf"
)
@parameterized.expand(
[
("empty", "", 0),
("ascii", "hello", 1427272415),
("emoji", "# Title\n\nSome text 🦔", 2055511376),
("multibyte", "naïve café ✨", 591606638),
]
)
def test_markdown_crc_vectors(self, _name, text, expected):
# Shared vectors with collaboration.test.ts — both sides hash UTF-16-LE bytes.
assert markdown_crc(text) == expected
class TestBuildMarkdownUpdateDiff(TestCase):
def test_returns_changes_and_base_crc(self):
diff = build_markdown_update_diff(markdown_doc("hello world"), markdown_doc("hello brave world"))
assert diff is not None
assert apply_utf16_text_changes("hello world", diff.changes) == "hello brave world"
assert diff.base_crc == markdown_crc("hello world")
@parameterized.expand(
[
("equal_markdown", markdown_doc("same"), markdown_doc("same")),
("previous_not_markdown", {"type": "doc", "content": []}, markdown_doc("hello")),
("next_not_markdown", markdown_doc("hello"), {"type": "doc", "content": []}),
("previous_none", None, markdown_doc("hello")),
]
)
def test_returns_none_when_not_diffable(self, _name, previous_content, next_content):
assert build_markdown_update_diff(previous_content, next_content) is None
def test_returns_none_when_diff_too_large(self):
huge = "x" * (MAX_PUBLISHED_DIFF_BYTES + 1)
assert build_markdown_update_diff(markdown_doc(""), markdown_doc(huge)) is None
@parameterized.expand(
[
("markdown", markdown_doc("# Hi"), "# Hi"),
("not_a_dict", "nope", None),
("rich_doc", {"type": "doc", "content": [{"type": "paragraph"}]}, None),
("two_nodes", {"type": "doc", "content": [markdown_doc("a")["content"][0]] * 2}, None),
(
"markdown_not_string",
{"type": "doc", "content": [{"type": "ph-markdown-notebook", "attrs": {"markdown": 5}}]},
None,
),
]
)
def test_get_markdown_notebook_markdown(self, _name, content, expected):
assert get_markdown_notebook_markdown(content) == expected
class TestMarkdownCollabStream(BaseTest):
def test_submit_markdown_update_accepted(self):
diff = MarkdownDiff(changes=[{"start": 0, "end": 0, "text": "hi"}], base_crc=markdown_crc(""))
result = submit_markdown_update(
self.team.pk, "md1", client_id="client1", diff=diff, last_seen_version=0, last_saved_version=0
)
assert result.status == "accepted"
assert result.version == 1
def test_submit_at_old_baseline_returns_missed_updates_in_order(self):
base = ""
for i, text in enumerate(["one", "one two", "one two three"]):
change = utf16_single_span_diff(base, text)
assert change is not None
diff = MarkdownDiff(changes=[change], base_crc=markdown_crc(base))
result = submit_markdown_update(
self.team.pk, "md2", client_id=f"client{i}", diff=diff, last_seen_version=i, last_saved_version=i
)
assert result.status == "accepted"
base = text
result = submit_markdown_update(
self.team.pk,
"md2",
client_id="client_behind",
diff=MarkdownDiff(changes=[{"start": 0, "end": 0, "text": "x"}], base_crc=markdown_crc("one")),
last_seen_version=1,
last_saved_version=3,
)
assert result.status == "conflict"
assert result.version == 3
assert result.updates is not None
assert [entry.version for entry in result.updates] == [2, 3]
# Folding the replayed diffs reconstructs the server state exactly
markdown = "one"
for entry in result.updates:
assert entry.base_crc == markdown_crc(markdown)
applied = apply_utf16_text_changes(markdown, entry.diff)
assert applied is not None
markdown = applied
assert markdown == "one two three"
def test_missed_range_with_diffless_ping_is_stale(self):
submit_markdown_update(
self.team.pk,
"md3",
client_id="client1",
diff=MarkdownDiff(changes=[{"start": 0, "end": 0, "text": "a"}], base_crc=markdown_crc("")),
last_seen_version=0,
last_saved_version=0,
)
publish_notebook_update(self.team.pk, "md3", 2)
result = submit_markdown_update(
self.team.pk,
"md3",
client_id="client2",
diff=None,
last_seen_version=0,
last_saved_version=2,
)
assert result.status == "stale"
assert result.version == 2
def test_missed_range_with_prosemirror_step_is_stale(self):
submit_steps(
self.team.pk,
"md4",
"pm_client",
[{"stepType": "replace", "from": 0, "to": 0}],
0,
last_saved_version=0,
)
result = submit_markdown_update(
self.team.pk,
"md4",
client_id="md_client",
diff=None,
last_seen_version=0,
last_saved_version=1,
)
assert result.status == "stale"
assert result.version == 1
def test_published_update_with_diff_is_replayable(self):
# The legacy PATCH path publishes `{version}-1` entries; they must replay like CAS entries.
diff = MarkdownDiff(changes=[{"start": 0, "end": 0, "text": "hello"}], base_crc=markdown_crc(""))
publish_notebook_update(self.team.pk, "md5", 1, diff=diff)
result = fetch_missed_markdown_updates(self.team.pk, "md5", last_seen_version=0, current_version=1)
assert result.status == "conflict"
assert result.updates is not None
assert result.updates[0].version == 1
assert result.updates[0].diff == diff.changes
assert result.updates[0].base_crc == diff.base_crc
assert result.updates[0].client_id is None
def test_submit_after_published_update_continues_version_sequence(self):
diff = MarkdownDiff(changes=[{"start": 0, "end": 0, "text": "hello"}], base_crc=markdown_crc(""))
publish_notebook_update(self.team.pk, "md6", 1, diff=diff)
result = submit_markdown_update(
self.team.pk,
"md6",
client_id="client1",
diff=MarkdownDiff(changes=[{"start": 5, "end": 5, "text": "!"}], base_crc=markdown_crc("hello")),
last_seen_version=1,
last_saved_version=1,
)
assert result.status == "accepted"
assert result.version == 2
def test_fetch_with_current_at_or_below_baseline_is_stale(self):
result = fetch_missed_markdown_updates(self.team.pk, "md7", last_seen_version=5, current_version=5)
assert result.status == "stale"
def test_submit_markdown_update_carries_author_presence(self):
diff = MarkdownDiff(changes=[{"start": 0, "end": 0, "text": "hi"}], base_crc=markdown_crc(""))
result = submit_markdown_update(
self.team.pk,
"md8",
client_id="client1",
diff=diff,
last_seen_version=0,
last_saved_version=0,
user_id=42,
user_name="Ada Lovelace",
cursor={"node_index": 0, "offset": 2},
)
assert result.status == "accepted"
client = redis.get_client()
entries = client.xrange(STREAM_KEY_PATTERN.format(team_id=self.team.pk, notebook_id="md8"))
payload = json.loads(entries[0][1][b"data"])
assert payload["user_id"] == 42
assert payload["user_name"] == "Ada Lovelace"
assert payload["cursor"] == {"node_index": 0, "offset": 2}
# Presence extras must not break diff replay for conflicting writers
replay = fetch_missed_markdown_updates(self.team.pk, "md8", last_seen_version=0, current_version=1)
assert replay.status == "conflict"
def test_submit_markdown_update_without_presence_omits_fields(self):
diff = MarkdownDiff(changes=[{"start": 0, "end": 0, "text": "hi"}], base_crc=markdown_crc(""))
submit_markdown_update(
self.team.pk, "md9", client_id="client1", diff=diff, last_seen_version=0, last_saved_version=0
)
client = redis.get_client()
entries = client.xrange(STREAM_KEY_PATTERN.format(team_id=self.team.pk, notebook_id="md9"))
payload = json.loads(entries[0][1][b"data"])
assert "user_id" not in payload
assert "user_name" not in payload
assert "cursor" not in payload
class TestPresenceStream(BaseTest):
def test_publish_presence_appends_entry_with_ttl(self):
publish_presence(
self.team.pk,
"pr1",
client_id="client1",
user_id=7,
user_name="Grace Hopper",
version=3,
cursor={"head": 12},
)
client = redis.get_client()
stream_key = PRESENCE_STREAM_KEY_PATTERN.format(team_id=self.team.pk, notebook_id="pr1")
entries = client.xrange(stream_key)
assert len(entries) == 1
payload = json.loads(entries[0][1][b"data"])
assert payload == {
"type": "presence",
"client_id": "client1",
"user_id": 7,
"user_name": "Grace Hopper",
"version": 3,
"cursor": {"head": 12},
}
assert 0 < client.ttl(stream_key) <= PRESENCE_TTL_SECONDS
def test_presence_stream_is_separate_from_content_stream(self):
publish_presence(
self.team.pk,
"pr2",
client_id="client1",
user_id=7,
user_name="Grace Hopper",
version=0,
cursor={"head": 0},
)
client = redis.get_client()
assert client.xrange(STREAM_KEY_PATTERN.format(team_id=self.team.pk, notebook_id="pr2")) == []