fix(backend): Prevent integration test flake from container startup timeouts

The suite hooks (beforeAll/afterAll) used the same 120s budget as the
container startup timeout, leaving zero headroom for migrations and app
boot. Under load (e.g. pre-push hooks running tests, PHP tests, and
builds concurrently) a slow container start ate the whole hook budget
and the suite failed with "Hook timed out in 120000ms".

Introduce shared timeout constants in tests/integration/timeouts.ts and
use them everywhere: container startup stays at 120s, suite hooks get
300s to leave headroom.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: enko

apps/backend/tests/integration/auth.helpers.ts

@@ -13,6 +13,7 @@ import { resetAuth } from '../../src/lib/auth.js';
 import { resetRateLimiters } from '../../src/middleware/rate-limit.js';
 import type { AppContext } from '../../src/types/context.js';
 import { resetConfig } from '../../src/utils/config.js';
+import { CONTAINER_STARTUP_TIMEOUT_MS, SUITE_HOOK_TIMEOUT_MS } from './timeouts.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -33,7 +34,7 @@ export async function setupAuthTests(): Promise<AuthTestContext> {
     .withDatabase('test')
     .withUsername('test')
     .withPassword('test')
-    .withStartupTimeout(120000)
+    .withStartupTimeout(CONTAINER_STARTUP_TIMEOUT_MS)
     .withWaitStrategy(Wait.forHealthCheck())
     .start();
 
@@ -373,7 +374,7 @@ export function setupAuthTestSuite() {
     vi.stubEnv('LOG_LEVEL', 'silent');
 
     context = await setupAuthTests();
-  }, 120000); // 120 second timeout for container startup
+  }, SUITE_HOOK_TIMEOUT_MS);
 
   beforeEach(() => {
     // Reset rate limiters before each test to avoid test interference
@@ -384,7 +385,7 @@ export function setupAuthTestSuite() {
     await teardownAuthTests(context);
     vi.unstubAllEnvs();
     resetConfig();
-  }, 120000);
+  }, SUITE_HOOK_TIMEOUT_MS);
 
   return {
     getContext: () => context,

apps/backend/tests/integration/friends.helpers.ts

@@ -11,6 +11,7 @@ import {
   setupAuthTests,
   teardownAuthTests,
 } from './auth.helpers.js';
+import { SUITE_HOOK_TIMEOUT_MS } from './timeouts.js';
 
 export interface FriendsTestContext extends AuthTestContext {
   testUser: {
@@ -182,7 +183,7 @@ export function setupFriendsTestSuite() {
       ...authContext,
       testUser,
     };
-  }, 120000);
+  }, SUITE_HOOK_TIMEOUT_MS);
 
   beforeEach(async () => {
     resetRateLimiters();
@@ -196,7 +197,7 @@ export function setupFriendsTestSuite() {
     await teardownAuthTests(context);
     vi.unstubAllEnvs();
     resetConfig();
-  }, 120000);
+  }, SUITE_HOOK_TIMEOUT_MS);
 
   return {
     getContext: () => context,

apps/backend/tests/integration/health.test.ts

@@ -7,6 +7,7 @@ import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
 import { createApp } from '../../src/index.js';
 import type { AppContext } from '../../src/types/context.js';
 import { resetConfig } from '../../src/utils/config.js';
+import { CONTAINER_STARTUP_TIMEOUT_MS, SUITE_HOOK_TIMEOUT_MS } from './timeouts.js';
 
 describe('Health Endpoint Integration Tests', () => {
   let container: StartedPostgreSqlContainer;
@@ -27,7 +28,7 @@ describe('Health Endpoint Integration Tests', () => {
       .withDatabase('test')
       .withUsername('test')
       .withPassword('test')
-      .withStartupTimeout(120000)
+      .withStartupTimeout(CONTAINER_STARTUP_TIMEOUT_MS)
       .withWaitStrategy(Wait.forHealthCheck())
       .start();
 
@@ -49,7 +50,7 @@ describe('Health Endpoint Integration Tests', () => {
 
     // Create the Hono app
     app = await createApp(pool);
-  }, 120000); // 120 second timeout for container startup
+  }, SUITE_HOOK_TIMEOUT_MS);
 
   afterAll(async () => {
     // Clean up
@@ -61,7 +62,7 @@ describe('Health Endpoint Integration Tests', () => {
     }
     vi.unstubAllEnvs();
     resetConfig();
-  }, 120000);
+  }, SUITE_HOOK_TIMEOUT_MS);
 
   describe('GET /health', () => {
     it('should return 200 and healthy status when database is connected', async () => {

apps/backend/tests/integration/postgis.helpers.ts

@@ -9,6 +9,7 @@ import { Wait } from 'testcontainers';
 import { afterAll, beforeAll, vi } from 'vitest';
 import { PostGISAddressClient } from '../../src/services/external/postgis-address.client.js';
 import { resetConfig } from '../../src/utils/config.js';
+import { CONTAINER_STARTUP_TIMEOUT_MS, SUITE_HOOK_TIMEOUT_MS } from './timeouts.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -43,7 +44,7 @@ export async function setupPostGISTests(): Promise<PostGISTestContext> {
     .withDatabase('test')
     .withUsername('test')
     .withPassword('test')
-    .withStartupTimeout(120000)
+    .withStartupTimeout(CONTAINER_STARTUP_TIMEOUT_MS)
     .withWaitStrategy(Wait.forHealthCheck())
     .start();
 
@@ -181,13 +182,13 @@ export function setupPostGISTestSuite() {
     vi.stubEnv('LOG_LEVEL', 'silent');
 
     context = await setupPostGISTests();
-  }, 180000); // 180 second timeout for container startup
+  }, SUITE_HOOK_TIMEOUT_MS);
 
   afterAll(async () => {
     await teardownPostGISTests(context);
     vi.unstubAllEnvs();
     resetConfig();
-  }, 60000);
+  }, SUITE_HOOK_TIMEOUT_MS);
 
   return {
     getContext: () => context,

apps/backend/tests/integration/search.helpers.ts

@@ -10,6 +10,7 @@ import {
   createTestFriend,
   type FriendsTestContext,
 } from './friends.helpers.js';
+import { SUITE_HOOK_TIMEOUT_MS } from './timeouts.js';
 
 // Re-export common helpers
 export { authHeaders, createTestFriend };
@@ -323,7 +324,7 @@ export function setupSearchTestSuite() {
       ...authContext,
       testUser,
     };
-  }, 120000);
+  }, SUITE_HOOK_TIMEOUT_MS);
 
   beforeEach(async () => {
     resetRateLimiters();
@@ -340,7 +341,7 @@ export function setupSearchTestSuite() {
     await teardownAuthTests(context);
     vi.unstubAllEnvs();
     resetConfig();
-  }, 120000);
+  }, SUITE_HOOK_TIMEOUT_MS);
 
   return {
     getContext: () => context,

apps/backend/tests/integration/timeouts.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared timeouts for integration test suites.
+ *
+ * The integration tests start one PostGIS testcontainer per test file. The
+ * suite hooks (beforeAll/afterAll) must allow for the container startup
+ * timeout PLUS migrations and app boot - if both budgets are equal, a slow
+ * container start (e.g. while pre-push hooks run tests, PHP tests, and builds
+ * concurrently) eats the whole hook budget and the suite flakes with
+ * "Hook timed out".
+ */
+
+/** Maximum time for the PostgreSQL/PostGIS container itself to become healthy. */
+export const CONTAINER_STARTUP_TIMEOUT_MS = 120_000;
+
+/**
+ * Timeout for beforeAll/afterAll suite hooks. Deliberately larger than
+ * CONTAINER_STARTUP_TIMEOUT_MS to leave headroom for migrations, app boot,
+ * and teardown under load.
+ */
+export const SUITE_HOOK_TIMEOUT_MS = 300_000;