Jazz Framework Testing: CRDT Operations and Collaborative App Testing
Jazz is a local-first framework built on CRDTs (Conflict-free Replicated Data Types). Unlike traditional sync frameworks, Jazz doesn't require a central server for conflict resolution — CRDT semantics mean concurrent edits from multiple users always merge deterministically. Testing Jazz means verifying that CoValue mutations work correctly, that merge semantics match your expectations, and that your collaborative scenarios behave correctly with multiple concurrent users.
Jazz's CRDT Mental Model
Before writing tests, understand Jazz's core abstractions:
- CoValue: A collaborative value — can be a
CoMap,CoList,CoStream, orBinaryCoStream - CoMap: Like a JavaScript object, but CRDT-merged (last-write-wins per field)
- CoList: Ordered list with CRDT merge (no lost inserts, no duplicate deletes)
- Group: Access control unit — accounts belong to groups, groups have permissions on CoValues
- Account: A user's persistent identity, owns CoValues
Setting Up the Test Environment
npm install jazz-tools @jazz-tools/test vitesttest-utils.ts:
import { co, Account, CoMap, CoList, Group } from "jazz-tools";
import { createJazzTestAccount, createJazzTestGuest } from "@jazz-tools/test";
// Define your app's schema
class Todo extends CoMap {
title = co.string;
completed = co.boolean;
createdAt = co.number;
}
class TodoList extends CoMap {
name = co.string;
todos = co.ref(CoList.Of(co.ref(Todo)));
}
class AppAccount extends Account {
profile = co.ref(CoMap.Record({ name: co.string }));
root = co.ref(TodoList);
}
export { Todo, TodoList, AppAccount };
export async function createTestAccount(name: string) {
const account = await createJazzTestAccount({
AccountSchema: AppAccount,
});
return account;
}Testing CoMap Operations
CoMap is Jazz's primary CRDT type for structured data:
import { describe, test, expect } from "vitest";
import { co, CoMap, CoList, Group } from "jazz-tools";
import { createJazzTestAccount } from "@jazz-tools/test";
describe("CoMap CRDT Operations", () => {
test("creating a CoMap stores initial values", async () => {
const { account } = await createTestAccount("Alice");
const group = Group.create({ owner: account });
const todo = Todo.create(
{ title: "Test todo", completed: false, createdAt: Date.now() },
{ owner: group }
);
expect(todo.title).toBe("Test todo");
expect(todo.completed).toBe(false);
});
test("CoMap field update changes value", async () => {
const { account } = await createTestAccount("Alice");
const group = Group.create({ owner: account });
const todo = Todo.create(
{ title: "Original", completed: false, createdAt: Date.now() },
{ owner: group }
);
todo.completed = true;
expect(todo.completed).toBe(true);
todo.title = "Updated title";
expect(todo.title).toBe("Updated title");
});
test("last-write-wins semantics on concurrent edits", async () => {
// Two accounts modify the same field concurrently
const { account: alice } = await createTestAccount("Alice");
const { account: bob } = await createTestAccount("Bob");
const group = Group.create({ owner: alice });
group.addMember(bob, "writer");
const todo = Todo.create(
{ title: "Initial", completed: false, createdAt: Date.now() },
{ owner: group }
);
// Both edit the title concurrently
// In LWW semantics, the edit with the later timestamp wins
const t1 = Date.now();
todo.title = "Alice's version";
// Simulate Bob's edit at a later timestamp
const t2 = t1 + 100;
// In real Jazz, each account's edit carries its own clock
// For testing, the last assignment wins
todo.title = "Bob's version";
expect(todo.title).toBe("Bob's version");
});
test("independent fields don't conflict", async () => {
const { account: alice } = await createTestAccount("Alice");
const { account: bob } = await createTestAccount("Bob");
const group = Group.create({ owner: alice });
group.addMember(bob, "writer");
const todo = Todo.create(
{ title: "Shared todo", completed: false, createdAt: Date.now() },
{ owner: group }
);
// Alice updates title, Bob updates completed — no conflict
todo.title = "New title";
todo.completed = true;
// Both changes survive
expect(todo.title).toBe("New title");
expect(todo.completed).toBe(true);
});
});Testing CoList CRDT Operations
CoList uses a CRDT algorithm that prevents lost inserts and duplicate deletes:
describe("CoList CRDT Operations", () => {
test("push appends item to list", async () => {
const { account } = await createTestAccount("Alice");
const group = Group.create({ owner: account });
const list = CoList.Of(co.string).create([], { owner: group });
list.push("first");
list.push("second");
list.push("third");
expect(list.length).toBe(3);
expect(list[0]).toBe("first");
expect(list[2]).toBe("third");
});
test("insert at index works correctly", async () => {
const { account } = await createTestAccount("Alice");
const group = Group.create({ owner: account });
const list = CoList.Of(co.string).create(["a", "c"], { owner: group });
list.splice(1, 0, "b"); // Insert "b" at index 1
expect(list.length).toBe(3);
expect([...list]).toEqual(["a", "b", "c"]);
});
test("delete removes item", async () => {
const { account } = await createTestAccount("Alice");
const group = Group.create({ owner: account });
const list = CoList.Of(co.string).create(["a", "b", "c"], { owner: group });
list.splice(1, 1); // Remove "b"
expect(list.length).toBe(2);
expect([...list]).toEqual(["a", "c"]);
});
test("concurrent insertions both survive", async () => {
// This is the key CRDT guarantee — no lost inserts
const { account: alice } = await createTestAccount("Alice");
const { account: bob } = await createTestAccount("Bob");
const group = Group.create({ owner: alice });
group.addMember(bob, "writer");
const list = CoList.Of(co.string).create(["start"], { owner: group });
// Both add to the list concurrently
list.push("alice-item");
list.push("bob-item");
// Both items should exist (no lost writes)
expect(list.length).toBe(3);
expect([...list]).toContain("alice-item");
expect([...list]).toContain("bob-item");
});
test("list of CoRefs works correctly", async () => {
const { account } = await createTestAccount("Alice");
const group = Group.create({ owner: account });
const todo1 = Todo.create(
{ title: "First", completed: false, createdAt: Date.now() },
{ owner: group }
);
const todo2 = Todo.create(
{ title: "Second", completed: false, createdAt: Date.now() },
{ owner: group }
);
const todoList = CoList.Of(co.ref(Todo)).create([todo1, todo2], { owner: group });
expect(todoList.length).toBe(2);
expect(todoList[0]?.title).toBe("First");
expect(todoList[1]?.title).toBe("Second");
});
});Testing Group Permissions
Jazz's permission system uses Groups with explicit roles:
describe("Group Permissions", () => {
test("owner can read and write", async () => {
const { account: alice } = await createTestAccount("Alice");
const group = Group.create({ owner: alice });
const todo = Todo.create(
{ title: "Alice's todo", completed: false, createdAt: Date.now() },
{ owner: group }
);
// Owner can read
expect(todo.title).toBe("Alice's todo");
// Owner can write
todo.completed = true;
expect(todo.completed).toBe(true);
});
test("writer role can read and write", async () => {
const { account: alice } = await createTestAccount("Alice");
const { account: bob } = await createTestAccount("Bob");
const group = Group.create({ owner: alice });
group.addMember(bob, "writer");
const todo = Todo.create(
{ title: "Shared todo", completed: false, createdAt: Date.now() },
{ owner: group }
);
// Bob (writer) can read
const bobTodo = await Todo.load(todo.id, bob, {});
expect(bobTodo?.title).toBe("Shared todo");
// Bob can write
if (bobTodo) {
bobTodo.completed = true;
expect(bobTodo.completed).toBe(true);
}
});
test("reader role cannot write", async () => {
const { account: alice } = await createTestAccount("Alice");
const { account: bob } = await createTestAccount("Bob");
const group = Group.create({ owner: alice });
group.addMember(bob, "reader");
const todo = Todo.create(
{ title: "Read-only todo", completed: false, createdAt: Date.now() },
{ owner: group }
);
const bobTodo = await Todo.load(todo.id, bob, {});
expect(bobTodo?.title).toBe("Read-only todo");
// Attempting to write should throw or be silently ignored
// Jazz throws an error for unauthorized writes
if (bobTodo) {
expect(() => {
bobTodo.completed = true;
}).toThrow();
}
});
test("non-member cannot access CoValue", async () => {
const { account: alice } = await createTestAccount("Alice");
const { account: charlie } = await createTestAccount("Charlie");
const group = Group.create({ owner: alice });
const todo = Todo.create(
{ title: "Private todo", completed: false, createdAt: Date.now() },
{ owner: group }
);
// Charlie has no access
const charlieTodo = await Todo.load(todo.id, charlie, {});
expect(charlieTodo).toBeNull();
});
test("member can be removed from group", async () => {
const { account: alice } = await createTestAccount("Alice");
const { account: bob } = await createTestAccount("Bob");
const group = Group.create({ owner: alice });
group.addMember(bob, "writer");
const todo = Todo.create(
{ title: "Revoke access", completed: false, createdAt: Date.now() },
{ owner: group }
);
// Bob has access
let bobTodo = await Todo.load(todo.id, bob, {});
expect(bobTodo).toBeDefined();
// Alice revokes access
group.removeMember(bob);
// Bob no longer has access
bobTodo = await Todo.load(todo.id, bob, {});
expect(bobTodo).toBeNull();
});
});Testing Collaborative Scenarios
The real test of a CRDT framework is multi-user collaboration:
describe("Collaborative Scenarios", () => {
test("two users editing same document concurrently", async () => {
const { account: alice } = await createTestAccount("Alice");
const { account: bob } = await createTestAccount("Bob");
const group = Group.create({ owner: alice });
group.addMember(bob, "writer");
// Shared document
const doc = CoMap.Record({
aliceField: co.string,
bobField: co.string,
sharedField: co.string
}).create(
{ aliceField: "", bobField: "", sharedField: "initial" },
{ owner: group }
);
// Alice and Bob edit different fields
doc.aliceField = "Alice wrote here";
doc.bobField = "Bob wrote here";
// Both edits survive
expect(doc.aliceField).toBe("Alice wrote here");
expect(doc.bobField).toBe("Bob wrote here");
});
test("real-time presence tracking", async () => {
const { account: alice } = await createTestAccount("Alice");
const { account: bob } = await createTestAccount("Bob");
const group = Group.create({ owner: alice });
group.addMember(bob, "writer");
// CoStream for ephemeral presence (e.g., cursor positions)
const presence = co.ref(CoMap.Record({
cursorX: co.number,
cursorY: co.number,
userId: co.string
}));
// Users update their presence
const alicePresence = CoMap.Record({
cursorX: co.number,
cursorY: co.number,
userId: co.string
}).create(
{ cursorX: 100, cursorY: 200, userId: "alice" },
{ owner: group }
);
alicePresence.cursorX = 150;
alicePresence.cursorY = 250;
expect(alicePresence.cursorX).toBe(150);
expect(alicePresence.userId).toBe("alice");
});
test("collaborative todo list — concurrent add and delete", async () => {
const { account: alice } = await createTestAccount("Alice");
const { account: bob } = await createTestAccount("Bob");
const group = Group.create({ owner: alice });
group.addMember(bob, "writer");
const list = CoList.Of(co.ref(Todo)).create([], { owner: group });
// Alice adds a todo
const aliceTodo = Todo.create(
{ title: "Alice's item", completed: false, createdAt: Date.now() },
{ owner: group }
);
list.push(aliceTodo);
// Bob adds a todo simultaneously
const bobTodo = Todo.create(
{ title: "Bob's item", completed: false, createdAt: Date.now() },
{ owner: group }
);
list.push(bobTodo);
// Both items should exist
expect(list.length).toBe(2);
const titles = [list[0]?.title, list[1]?.title];
expect(titles).toContain("Alice's item");
expect(titles).toContain("Bob's item");
});
test("CoValue loading by ID from another account", async () => {
const { account: alice } = await createTestAccount("Alice");
const { account: bob } = await createTestAccount("Bob");
const group = Group.create({ owner: alice });
group.addMember(bob, "reader");
const todo = Todo.create(
{ title: "Load by ID", completed: false, createdAt: Date.now() },
{ owner: group }
);
const todoId = todo.id;
// Bob loads the todo by ID
const loaded = await Todo.load(todoId, bob, {});
expect(loaded).toBeDefined();
expect(loaded?.title).toBe("Load by ID");
});
});Testing CoValue Subscriptions
Jazz's reactive system fires callbacks when CoValues change:
describe("CoValue Subscriptions", () => {
test("subscription fires on field change", async () => {
const { account } = await createTestAccount("Alice");
const group = Group.create({ owner: account });
const todo = Todo.create(
{ title: "Subscribe test", completed: false, createdAt: Date.now() },
{ owner: group }
);
const changes: string[] = [];
const unsubscribe = todo.subscribe({}, (updatedTodo) => {
changes.push(updatedTodo.title ?? "");
});
todo.title = "Changed title";
await new Promise(resolve => setTimeout(resolve, 10));
expect(changes).toContain("Changed title");
unsubscribe();
});
test("subscription fires for nested CoValue changes", async () => {
const { account } = await createTestAccount("Alice");
const group = Group.create({ owner: account });
const list = CoList.Of(co.ref(Todo)).create([], { owner: group });
const listChanges: number[] = [];
const unsubscribe = list.subscribe({}, (updatedList) => {
listChanges.push(updatedList.length);
});
const todo = Todo.create(
{ title: "New todo", completed: false, createdAt: Date.now() },
{ owner: group }
);
list.push(todo);
await new Promise(resolve => setTimeout(resolve, 10));
expect(listChanges).toContain(1);
unsubscribe();
});
});CI/CD Configuration
name: Jazz Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: "20"
cache: "npm"
- run: npm ci
- name: Run Jazz unit tests
run: npx vitest run tests/Monitoring Jazz Applications
CRDT merge correctness is hard to verify in production — merge conflicts are resolved silently, and subtle bugs show up as unexpected data states that users report as "my edits disappeared."
HelpMeTest provides multi-user end-to-end testing that simulates concurrent users editing the same Jazz documents and verifies that both edits survive. Run these collaborative tests continuously to catch CRDT regression bugs before users report lost work.
Summary
Jazz testing covers four areas:
- CoMap operations — field mutations, last-write-wins semantics, independent field updates
- CoList operations — push, insert, delete, concurrent insert survival
- Group permissions — owner, writer, reader roles, member removal, non-member exclusion
- Collaborative scenarios — concurrent edits, presence, cross-account loading
The most distinctive Jazz test is the concurrent-insert-both-survive test — this verifies the core CRDT guarantee. If your list implementation loses concurrent insertions, you have a data loss bug. Test it explicitly.