test(web): add unit tests for healthz endpoint

- Refactor healthz route to use dependency injection pattern for testability
- Add comprehensive tests for success and error cases
- Tests verify response structure, error handling, and timestamp format

Prevents regressions in health check behavior.

Author: brandonkachen

web/src/app/api/healthz/__tests__/healthz.test.ts

@@ -0,0 +1,98 @@
+import { describe, test, expect } from 'bun:test'
+
+import { getHealthz } from '../_get'
+
+import type { HealthzDeps } from '../_get'
+
+describe('/api/healthz route', () => {
+  describe('Success cases', () => {
+    test('returns 200 with status ok and agent count', async () => {
+      const mockGetAgentCount = async () => 42
+
+      const response = await getHealthz({ getAgentCount: mockGetAgentCount })
+
+      expect(response.status).toBe(200)
+      const body = await response.json()
+      expect(body.status).toBe('ok')
+      expect(body.cached_agents).toBe(42)
+      expect(body.timestamp).toBeDefined()
+      expect(typeof body.timestamp).toBe('string')
+    })
+
+    test('returns correct count when no agents exist', async () => {
+      const mockGetAgentCount = async () => 0
+
+      const response = await getHealthz({ getAgentCount: mockGetAgentCount })
+
+      expect(response.status).toBe(200)
+      const body = await response.json()
+      expect(body.status).toBe('ok')
+      expect(body.cached_agents).toBe(0)
+    })
+
+    test('returns correct count for large number of agents', async () => {
+      const mockGetAgentCount = async () => 10000
+
+      const response = await getHealthz({ getAgentCount: mockGetAgentCount })
+
+      expect(response.status).toBe(200)
+      const body = await response.json()
+      expect(body.status).toBe('ok')
+      expect(body.cached_agents).toBe(10000)
+    })
+  })
+
+  describe('Error handling', () => {
+    test('returns 200 with error flag when getAgentCount throws', async () => {
+      const mockGetAgentCount = async () => {
+        throw new Error('Database connection failed')
+      }
+
+      const response = await getHealthz({ getAgentCount: mockGetAgentCount })
+
+      // Should still return 200 so health check passes
+      expect(response.status).toBe(200)
+      const body = await response.json()
+      expect(body.status).toBe('ok')
+      expect(body.agent_count_error).toBe(true)
+      expect(body.error).toBe('Database connection failed')
+      expect(body.cached_agents).toBeUndefined()
+    })
+
+    test('handles non-Error exceptions gracefully', async () => {
+      const mockGetAgentCount = async () => {
+        throw 'String error'
+      }
+
+      const response = await getHealthz({ getAgentCount: mockGetAgentCount })
+
+      expect(response.status).toBe(200)
+      const body = await response.json()
+      expect(body.status).toBe('ok')
+      expect(body.agent_count_error).toBe(true)
+      expect(body.error).toBe('Unknown error')
+    })
+  })
+
+  describe('Response format', () => {
+    test('response has correct Content-Type header', async () => {
+      const mockGetAgentCount = async () => 100
+
+      const response = await getHealthz({ getAgentCount: mockGetAgentCount })
+
+      expect(response.headers.get('content-type')).toContain('application/json')
+    })
+
+    test('timestamp is in ISO format', async () => {
+      const mockGetAgentCount = async () => 50
+
+      const response = await getHealthz({ getAgentCount: mockGetAgentCount })
+      const body = await response.json()
+
+      // Verify timestamp is valid ISO date
+      const timestamp = new Date(body.timestamp)
+      expect(timestamp.toString()).not.toBe('Invalid Date')
+      expect(body.timestamp).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/)
+    })
+  })
+})

web/src/app/api/healthz/_get.ts

@@ -0,0 +1,28 @@
+import { NextResponse } from 'next/server'
+
+export interface HealthzDeps {
+  getAgentCount: () => Promise<number>
+}
+
+export const getHealthz = async ({ getAgentCount }: HealthzDeps) => {
+  try {
+    // Get a lightweight count of agents without caching the full data
+    // This avoids the unstable_cache 2MB limit warning
+    const agentCount = await getAgentCount()
+
+    return NextResponse.json({
+      status: 'ok',
+      cached_agents: agentCount,
+      timestamp: new Date().toISOString(),
+    })
+  } catch (error) {
+    console.error('[Healthz] Failed to get agent count:', error)
+
+    // Still return 200 so health check passes, but indicate the error
+    return NextResponse.json({
+      status: 'ok',
+      agent_count_error: true,
+      error: error instanceof Error ? error.message : 'Unknown error',
+    })
+  }
+}

web/src/app/api/healthz/route.ts

@@ -1,25 +1,6 @@
-import { NextResponse } from 'next/server'
 import { getAgentCount } from '@/server/agents-data'
+import { getHealthz } from './_get'
 
 export const GET = async () => {
-  try {
-    // Get a lightweight count of agents without caching the full data
-    // This avoids the unstable_cache 2MB limit warning
-    const agentCount = await getAgentCount()
-
-    return NextResponse.json({
-      status: 'ok',
-      cached_agents: agentCount,
-      timestamp: new Date().toISOString(),
-    })
-  } catch (error) {
-    console.error('[Healthz] Failed to get agent count:', error)
-
-    // Still return 200 so health check passes, but indicate the error
-    return NextResponse.json({
-      status: 'ok',
-      agent_count_error: true,
-      error: error instanceof Error ? error.message : 'Unknown error',
-    })
-  }
+  return getHealthz({ getAgentCount })
 }