Jazz Framework Testing: CRDT Operations and Collaborative App Testing

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, or BinaryCoStream
  • 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 vitest

test-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:

  1. CoMap operations — field mutations, last-write-wins semantics, independent field updates
  2. CoList operations — push, insert, delete, concurrent insert survival
  3. Group permissions — owner, writer, reader roles, member removal, non-member exclusion
  4. 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.

Start now free