test: align jest db bootstrap with ci

.gitea/workflows/ci.yml

@@ -26,6 +26,7 @@ jobs:
       DATABASE_URL: postgresql://postgres:postgres@postgres:5432/merchantsofhope_test
       JWT_SECRET: merchantsofhope_test_secret
       NODE_ENV: test
+      USE_DOCKER_TEST_DB: "false"
     steps:
       - name: Checkout
         uses: actions/checkout@v4

README.md

@@ -150,7 +150,7 @@ The application comes with pre-seeded demo accounts:
 
 ### Quality Gates & Tests
 
-`npm run lint` and `npm test` must pass in both the backend and frontend. The backend Jest suite bootstraps a disposable Postgres instance via Docker (using `docker-compose.test.yml`), so Docker must be available on your workstation.
+`npm run lint` and `npm test` must pass in both the backend and frontend. By default, the backend Jest suite bootstraps a disposable Postgres instance via Docker (using `docker-compose.test.yml`), so Docker must be available on your workstation. To point the tests at an existing database (e.g., CI runners), set `USE_DOCKER_TEST_DB=false` and supply `DATABASE_URL`/`POSTGRES_*`.
 
 Quick commands:
 

backend/src/tests/globalSetup.js

@@ -12,6 +12,15 @@ module.exports = async () => {
   process.env.POSTGRES_HOST = process.env.POSTGRES_HOST || '127.0.0.1';
   process.env.POSTGRES_PORT = process.env.POSTGRES_PORT || '55432';
 
+const useDocker = process.env.USE_DOCKER_TEST_DB !== 'false';
+
+if (useDocker) {
+  process.env.POSTGRES_DB = process.env.POSTGRES_DB || 'merchantsofhope_test';
+  process.env.POSTGRES_USER = process.env.POSTGRES_USER || 'postgres';
+  process.env.POSTGRES_PASSWORD = process.env.POSTGRES_PASSWORD || 'postgres';
+  process.env.POSTGRES_HOST = process.env.POSTGRES_HOST || '127.0.0.1';
+  process.env.POSTGRES_PORT = process.env.POSTGRES_PORT || '55432';
+
   const composeFile = path.join(__dirname, '..', '..', '..', 'docker-compose.test.yml');
 
   const upResult = spawnSync(
@@ -47,10 +56,21 @@ module.exports = async () => {
 
     sleep(1000);
   }
-
   if (!ready) {
     throw new Error('Database did not become ready in time');
   }
+}
+
+const waitScript = path.join(__dirname, '..', '..', 'scripts', 'wait-for-db.js');
+const waitResult = spawnSync('node', [waitScript], {
+  cwd: path.join(__dirname, '..', '..'),
+  stdio: 'inherit',
+  env: process.env
+});
+
+if (waitResult.status !== 0) {
+  throw new Error('Database wait script failed');
+}
 
 const migratePath = path.join(__dirname, '..', 'database', 'migrate.js');
 const result = spawnSync('node', [migratePath], {

backend/src/tests/globalTeardown.js

@@ -7,6 +7,7 @@ module.exports = async () => {
   await cleanupUploads();
   await pool.end();
 
+  if (process.env.USE_DOCKER_TEST_DB !== 'false') {
     const composeFile = path.join(__dirname, '..', '..', '..', 'docker-compose.test.yml');
     spawnSync(
       'docker',
@@ -17,4 +18,5 @@ module.exports = async () => {
         env: process.env
       }
     );
+  }
 };

docs/OPERATIONS_RUNBOOK.md

@@ -28,6 +28,7 @@ This document captures the operational playbooks for the MerchantsOfHope Supply
 | `DB_WAIT_TIMEOUT_MS` | Maximum wait for database readiness in entrypoint | 60000 |
 | `RUN_MIGRATIONS` | Run schema migrations on container boot | `true` |
 | `RUN_SEED` | Run seed data on container boot | `false` |
+| `USE_DOCKER_TEST_DB` | Jest helper flag (set to `false` in CI to reuse managed Postgres) | `true` locally |
 | `UPLOAD_DIR` | Resume storage path | `uploads/resumes` |
 
 ## 3. Deployments (Coolify)

scripts/run-ci-tests.sh

@@ -8,7 +8,7 @@ echo ">>> Running frontend lint locally"
 (cd frontend && npm run lint)
 
 echo ">>> Running backend test suite"
-(cd backend && npm test -- --runInBand --coverage)
+(USE_DOCKER_TEST_DB=${USE_DOCKER_TEST_DB:-true} cd backend && npm test -- --runInBand --coverage)
 
 echo ">>> Running frontend test suite"
 (cd frontend && npm test -- --watchAll=false --coverage)