Testing OCC Improvements

[storm yoke]

Is there a way to reliably reproduce OCC conflicts to test and measure improvements?

I don't think it can be reproduced in convex-test since it runs mutations serially in memory. There's no concurrent transaction scheduling, so there's no opportunity for conflicts

[dull remnant]

Hi @storm yoke. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

---

You’re right that convex-test won’t help here: it’s a single-process mock and explicitly doesn’t model real OCC behavior or limits. [convex-test limits]

From the docs and Stack posts, there are two reliable ways to actually see OCC conflicts and measure improvements:

---

1. Use patterns that are known to conflict

Convex documents several “bad” patterns that reliably trigger OCC conflicts when driven with enough parallelism:

• A mutation that always reads and writes the same document (singleton counter): [Errors OCC]

  export const updateCounter = mutation({
    args: {},
    handler: async (ctx) => {
      const doc = await ctx.db.get("counts", process.env.COUNTER_ID!);
      await ctx.db.patch(doc!._id, { value: doc!.value + 1 });
    },
  });
  

  Calling this many times per second in parallel will produce OCC errors.

• A mutation that depends on a whole table or large index range, while another mutation writes into that range (e.g. writeCount + addTask): [Errors OCC]

These are good “stress tests” for OCC: you can hammer them with concurrent calls and then try improved designs (sharding, narrower queries, queue pattern, aggregates, Workpool, etc.) and compare error rates and throughput.

---

2. Run against a real backend (local OSS or cloud), not convex-test

To actually exercise OCC and measure improvements, you need the real Convex backend:

• The local open‑source backend is explicitly recommended for tests that should behave like production, including limits and concurrency. [Testing local backend]
• convex-test is positioned only for logic tests; it does not model OCC or many backend behaviors. [convex-test limits]

So for reproducible OCC conflicts:

1. Stand up the local backend (per the testing guide). [Testing local backend]
2. Implement one of the known-conflict patterns above.
3. Drive high parallelism from a load script or test runner (multiple concurrent mutation calls).
4. Observe:
   • OCC errors in logs / client
   • Throughput and latency
5. Apply your “improvement” (e.g. sharding, queue pattern, Workpool with maxParallelism: 1 to serialize a hot mutation) and repeat to compare. [Queue pattern; Workpool OCC]

---

There’s no documented way to force OCC conflicts inside convex-test; for realistic OCC behavior you need the real backend (local or cloud).

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: