download MongoMemoryServer in globalSetup

apps/app/test/setup/mongo/global-setup.ts

@@ -0,0 +1,17 @@
+import { MongoBinary } from 'mongodb-memory-server-core';
+
+import { MONGOMS_BINARY_OPTS } from './utils';
+
+/**
+ * Global setup: pre-download the MongoDB binary before any workers start.
+ * This prevents lock-file race conditions when multiple Vitest workers try to
+ * download the binary concurrently on the first run.
+ */
+export async function setup(): Promise<void> {
+  // Skip if using an external MongoDB (e.g. CI with GitHub Actions services)
+  if (process.env.MONGO_URI != null) {
+    return;
+  }
+
+  await MongoBinary.getPath(MONGOMS_BINARY_OPTS);
+}

apps/app/test/setup/mongo/index.ts

@@ -4,7 +4,7 @@ import { afterAll, beforeAll } from 'vitest';
 
 import { mongoOptions } from '~/server/util/mongoose-utils';
 
-import { getTestDbConfig } from './utils';
+import { getTestDbConfig, MONGOMS_BINARY_OPTS } from './utils';
 
 let mongoServer: MongoMemoryServer | undefined;
 
@@ -27,18 +27,11 @@ beforeAll(async () => {
   }
 
   // Use MongoMemoryServer for local development
-  // set debug flag
   process.env.MONGOMS_DEBUG = process.env.VITE_MONGOMS_DEBUG;
 
-  // set version
   mongoServer = await MongoMemoryServer.create({
-    instance: {
-      dbName,
-    },
-    binary: {
-      version: process.env.VITE_MONGOMS_VERSION,
-      downloadDir: 'node_modules/.cache/mongodb-binaries',
-    },
+    instance: { dbName },
+    binary: MONGOMS_BINARY_OPTS,
   });
 
   // biome-ignore lint/suspicious/noConsole: Allow logging

apps/app/test/setup/mongo/utils.ts

@@ -1,4 +1,10 @@
 import ConnectionString from 'mongodb-connection-string-url';
+import type { MongoBinary } from 'mongodb-memory-server-core';
+
+export const MONGOMS_BINARY_OPTS: Parameters<typeof MongoBinary.getPath>[0] = {
+  version: process.env.VITE_MONGOMS_VERSION,
+  downloadDir: 'node_modules/.cache/mongodb-binaries',
+};
 
 /**
  * Replace the database name in a MongoDB connection URI.

apps/app/vitest.workspace.mts

@@ -31,8 +31,8 @@ export default defineWorkspace([
       name: 'app-integration',
       environment: 'node',
       include: ['**/*.integ.ts'],
-      // Allow enough time for MongoMemoryServer to download the binary on first run
-      hookTimeout: 120_000,
+      // Pre-download the MongoDB binary before workers start to avoid lock-file race conditions
+      globalSetup: ['./test/setup/mongo/global-setup.ts'],
       setupFiles: [
         './test/setup/migrate-mongo.ts',
         './test/setup/mongo/index.ts',