import { PostHog } from '@/entrypoints/index.node' import { captureCalls, captureRequests, sentEventsOf, v1Response } from './utils' vi.mock('../version', () => ({ version: '1.2.3' })) const mockedFetch = vi.spyOn(globalThis, 'fetch').mockImplementation() const DEBOUNCE_MS = 50 const HALF_DEBOUNCE_MS = DEBOUNCE_MS / 2 function getFlushedBatches(): any[][] { return captureRequests(mockedFetch).map(sentEventsOf) } describe('flush combines events and spans', () => { it('waits for the span export even when the event delivery fails', async () => { // `Promise.all` settled on the event rejection, so a serverless host could // freeze the invocation with the span request still open. vi.useRealTimers() const order: string[] = [] mockedFetch.mockImplementation(async (url: any) => { if (String(url).includes('/i/v1/traces')) { order.push('traces-start') await new Promise((resolve) => setTimeout(resolve, 30)) order.push('traces-done') return { status: 200, text: () => Promise.resolve('{}'), json: () => Promise.resolve({}) } as any } return new Response('events endpoint down', { status: 400 }) }) const posthog = new PostHog('key', { host: 'http://example.com', flushAt: 1, fetchRetryCount: 0, traces: { serviceName: 'svc' }, disableCompression: true, }) const errors: unknown[] = [] posthog.on('error', (error) => errors.push(error)) try { posthog.capture({ distinctId: 'u', event: 'e' }) posthog.startSpan('s').end() await expect(posthog.flush()).resolves.toBeUndefined() order.push('flush-returned') // Exact, not an index comparison: before the fix `traces-done` is absent // when flush returns, and `indexOf` gives -1, which passes any `lessThan`. expect(order).toEqual(['traces-start', 'traces-done', 'flush-returned']) expect(errors).toEqual([expect.objectContaining({ name: 'CaptureError', retryExhausted: [expect.any(String)] })]) } finally { await posthog.shutdown() vi.useFakeTimers() } }) }) describe('waitUntil debounced flush', () => { vi.useFakeTimers() afterEach(async () => { vi.clearAllMocks() vi.clearAllTimers() }) describe('debounce behavior', () => { let posthog: PostHog let mockWaitUntil: vi.Mock beforeEach(() => { mockWaitUntil = vi.fn() posthog = new PostHog('TEST_API_KEY', { host: 'http://example.com', flushAt: 100, // High threshold so normal flushAt doesn't trigger flushInterval: 60000, // Long interval so timer doesn't trigger fetchRetryCount: 0, disableCompression: true, captureAiCompression: 'none', waitUntil: mockWaitUntil, waitUntilDebounceMs: DEBOUNCE_MS, }) mockedFetch.mockResolvedValue(v1Response()) }) afterEach(async () => { await posthog.shutdown() }) it('calls waitUntil with a promise on first capture', async () => { posthog.capture({ distinctId: 'user-1', event: 'test_event' }) await vi.advanceTimersByTimeAsync(0) expect(mockWaitUntil).toHaveBeenCalledTimes(1) expect(mockWaitUntil).toHaveBeenCalledWith(expect.any(Promise)) }) it('schedules a waitUntil flush for an event dropped while its properties are read', async () => { const errors: unknown[] = [] posthog.on('error', (error) => errors.push(error)) const properties = Object.defineProperty({}, 'value', { enumerable: true, get: () => { throw new Error('getter failed') }, }) posthog.capture({ distinctId: 'user-1', event: 'unreadable', properties }) await vi.advanceTimersByTimeAsync(0) expect(mockWaitUntil).toHaveBeenCalledTimes(1) await vi.advanceTimersByTimeAsync(DEBOUNCE_MS) await expect(mockWaitUntil.mock.calls[0][0]).resolves.toBeUndefined() expect(errors).toEqual([ expect.objectContaining({ name: 'CaptureError', message: expect.stringContaining('could not be serialized') }), ]) expect(mockedFetch).not.toHaveBeenCalled() }) it('does not call waitUntil again on subsequent captures in same batch', async () => { posthog.capture({ distinctId: 'user-1', event: 'event_1' }) posthog.capture({ distinctId: 'user-1', event: 'event_2' }) await vi.advanceTimersByTimeAsync(0) expect(mockWaitUntil).toHaveBeenCalledTimes(1) }) it('flushes 50ms after the last capture', async () => { posthog.capture({ distinctId: 'user-1', event: 'event_1' }) await vi.advanceTimersByTimeAsync(DEBOUNCE_MS - 1) expect(mockedFetch).not.toHaveBeenCalled() await vi.advanceTimersByTimeAsync(1) const batches = getFlushedBatches() expect(batches).toHaveLength(1) expect(batches[0]).toHaveLength(1) expect(batches[0][0].event).toBe('event_1') }) it('resets debounce timer on each capture', async () => { posthog.capture({ distinctId: 'user-1', event: 'event_1' }) await vi.advanceTimersByTimeAsync(0) vi.advanceTimersByTime(DEBOUNCE_MS - 1) posthog.capture({ distinctId: 'user-1', event: 'event_2' }) await vi.advanceTimersByTimeAsync(0) vi.advanceTimersByTime(HALF_DEBOUNCE_MS) // Not yet flushed (only 25ms since last capture's enqueue) expect(mockedFetch).not.toHaveBeenCalled() await vi.advanceTimersByTimeAsync(HALF_DEBOUNCE_MS) // Now flushed with both events const batches = getFlushedBatches() expect(batches).toHaveLength(1) expect(batches[0]).toHaveLength(2) }) it('resolves the waitUntil promise after flush completes', async () => { let completeDelivery!: () => void const delivery = new Promise((resolve) => { completeDelivery = resolve }) mockedFetch.mockImplementationOnce(async () => { await delivery return v1Response() }) try { posthog.capture({ distinctId: 'user-1', event: 'test_event' }) await vi.advanceTimersByTimeAsync(0) const waitUntilPromise = mockWaitUntil.mock.calls[0][0] as Promise const settled = vi.fn() void waitUntilPromise.then(settled) await vi.advanceTimersByTimeAsync(DEBOUNCE_MS) expect(getFlushedBatches().map((batch) => batch.map(({ event }) => event))).toEqual([['test_event']]) expect(settled).not.toHaveBeenCalled() completeDelivery() await expect(waitUntilPromise).resolves.toBeUndefined() expect(settled).toHaveBeenCalledTimes(1) } finally { completeDelivery() } }) it('drains both capture lanes before resolving the waitUntil promise', async () => { let releaseAi!: () => void mockedFetch.mockImplementation((url: any) => String(url).includes('/i/v1/ai/events') ? new Promise((resolve) => (releaseAi = () => resolve(v1Response()))) : Promise.resolve(v1Response()) ) const settled = vi.fn() posthog.capture({ distinctId: 'user-1', event: 'analytics_event' }) posthog.captureAi({ distinctId: 'user-1', event: '$ai_generation' }) await vi.advanceTimersByTimeAsync(0) const waitUntilPromise = mockWaitUntil.mock.calls[0][0] as Promise void waitUntilPromise.then(settled) await vi.advanceTimersByTimeAsync(DEBOUNCE_MS) expect(getFlushedBatches().map((batch) => batch.map(({ event }) => event))).toEqual([['analytics_event']]) expect(captureCalls(mockedFetch, '/i/v1/ai/events')).toHaveLength(1) expect(settled).not.toHaveBeenCalled() releaseAi() await expect(waitUntilPromise).resolves.toBeUndefined() }) it('does not activate debounced flush when no waitUntil in options', async () => { const posthogNoWaitUntil = new PostHog('TEST_API_KEY', { host: 'http://example.com', flushAt: 100, flushInterval: 60000, fetchRetryCount: 0, disableCompression: true, }) posthogNoWaitUntil.capture({ distinctId: 'user-1', event: 'test_event' }) await vi.advanceTimersByTimeAsync(0) await vi.advanceTimersByTimeAsync(DEBOUNCE_MS) // With flushAt=100 and only 1 event, no flush should happen from debounce expect(mockedFetch).not.toHaveBeenCalled() await posthogNoWaitUntil.shutdown() }) it('starts a new debounce cycle for captures after flush', async () => { // First cycle posthog.capture({ distinctId: 'user-1', event: 'event_1' }) await vi.advanceTimersByTimeAsync(DEBOUNCE_MS) // Second capture should start a new cycle posthog.capture({ distinctId: 'user-1', event: 'event_2' }) await vi.advanceTimersByTimeAsync(DEBOUNCE_MS) expect(getFlushedBatches().length).toEqual(2) expect(getFlushedBatches()[0][0].event).toBe('event_1') expect(getFlushedBatches()[1][0].event).toBe('event_2') }) it('does not flush after shutdown when debounce timer is pending', async () => { posthog.capture({ distinctId: 'user-1', event: 'event_1' }) await vi.advanceTimersByTimeAsync(0) const sentinelPromise = mockWaitUntil.mock.calls[0][0] as Promise await posthog.shutdown() mockedFetch.mockClear() await vi.advanceTimersByTimeAsync(DEBOUNCE_MS * 2) expect(mockedFetch).not.toHaveBeenCalled() // Shutdown must resolve the sentinel so the serverless runtime can terminate await expect(sentinelPromise).resolves.toBeUndefined() }) it('resolves the waitUntil promise even when flush fails', async () => { mockedFetch.mockRejectedValueOnce(new Error('Network error')) posthog.capture({ distinctId: 'user-1', event: 'test_event' }) await vi.advanceTimersByTimeAsync(0) const waitUntilPromise = mockWaitUntil.mock.calls[0][0] as Promise await vi.advanceTimersByTimeAsync(DEBOUNCE_MS) await expect(waitUntilPromise).resolves.toBeUndefined() }) }) describe('max time cap', () => { let posthog: PostHog let mockWaitUntil: vi.Mock const MAX_DEBOUNCE_MS = 500 beforeEach(() => { mockWaitUntil = vi.fn() posthog = new PostHog('TEST_API_KEY', { host: 'http://example.com', flushAt: 100, flushInterval: 60000, fetchRetryCount: 0, disableCompression: true, waitUntil: mockWaitUntil, waitUntilDebounceMs: DEBOUNCE_MS, waitUntilMaxWaitMs: MAX_DEBOUNCE_MS, }) mockedFetch.mockResolvedValue(v1Response()) }) afterEach(async () => { await posthog.shutdown() }) it('flushes when max time cap is exceeded instead of resetting debounce', async () => { posthog.capture({ distinctId: 'user-1', event: 'event_1' }) await vi.advanceTimersByTimeAsync(0) // Advance past the max wait (default 500ms), capturing along the way // to keep resetting the debounce timer. Each iteration advances DEBOUNCE_MS - 1ms // (under the 50ms debounce) so the debounce never fires on its own. for (let i = 0; i < 11; i++) { vi.advanceTimersByTime(DEBOUNCE_MS - 1) posthog.capture({ distinctId: 'user-1', event: `event_${i + 2}` }) // Flush microtasks so enqueue completes. This also fires the 0ms // max-cap timer on the iteration where elapsed exceeds 500ms. await vi.advanceTimersByTimeAsync(0) } // The max cap triggered a flush during the loop (not the 50ms debounce) expect(getFlushedBatches().length).toEqual(1) }) it('respects custom waitUntilMaxWaitMs', async () => { const posthogCustomMax = new PostHog('TEST_API_KEY', { host: 'http://example.com', flushAt: 100, flushInterval: 60000, fetchRetryCount: 0, disableCompression: true, waitUntil: mockWaitUntil, waitUntilDebounceMs: DEBOUNCE_MS, waitUntilMaxWaitMs: 100, }) try { posthogCustomMax.capture({ distinctId: 'user-1', event: 'event_1' }) await vi.advanceTimersByTimeAsync(0) await vi.advanceTimersByTimeAsync(40) posthogCustomMax.capture({ distinctId: 'user-1', event: 'event_2' }) await vi.advanceTimersByTimeAsync(0) await vi.advanceTimersByTimeAsync(40) posthogCustomMax.capture({ distinctId: 'user-1', event: 'event_3' }) await vi.advanceTimersByTimeAsync(0) // At 100ms the ordinary debounce is still pending until 130ms. await vi.advanceTimersByTimeAsync(20) expect(getFlushedBatches()).toHaveLength(0) posthogCustomMax.capture({ distinctId: 'user-1', event: 'event_4' }) await vi.advanceTimersByTimeAsync(0) expect(getFlushedBatches().map((batch) => batch.map(({ event }) => event))).toEqual([ ['event_1', 'event_2', 'event_3', 'event_4'], ]) } finally { await posthogCustomMax.shutdown() } }) }) describe('flush() override', () => { let posthog: PostHog let mockWaitUntil: vi.Mock beforeEach(() => { mockWaitUntil = vi.fn() posthog = new PostHog('TEST_API_KEY', { host: 'http://example.com', flushAt: 2, // Low threshold to trigger flushAt flushInterval: 60000, fetchRetryCount: 0, disableCompression: true, waitUntil: mockWaitUntil, }) mockedFetch.mockResolvedValue(v1Response()) }) afterEach(async () => { await posthog.shutdown() }) it('wraps flushAt-triggered flushes in waitUntil', async () => { const posthogFlushAt = new PostHog('TEST_API_KEY', { host: 'http://example.com', flushAt: 2, flushInterval: 60000, fetchRetryCount: 0, disableCompression: true, waitUntil: mockWaitUntil, waitUntilDebounceMs: 60000, // Long debounce so it doesn't fire first }) // First capture: registers debounce waitUntil sentinel posthogFlushAt.capture({ distinctId: 'user-1', event: 'event_1' }) await vi.advanceTimersByTimeAsync(0) expect(mockWaitUntil).toHaveBeenCalledTimes(1) const sentinelPromise = mockWaitUntil.mock.calls[0][0] as Promise // Second capture triggers flushAt (threshold is 2) posthogFlushAt.capture({ distinctId: 'user-1', event: 'event_2' }) await vi.advanceTimersByTimeAsync(0) // flushAt-triggered flush should have sent the data expect(mockedFetch).toHaveBeenCalled() // No additional waitUntil call — debounce sentinel already keeps runtime alive expect(mockWaitUntil).toHaveBeenCalledTimes(1) await posthogFlushAt.shutdown() // Sentinel resolves after shutdown await expect(sentinelPromise).resolves.toBeUndefined() }) it('wraps flushInterval-triggered flushes in waitUntil', async () => { const posthogWithInterval = new PostHog('TEST_API_KEY', { host: 'http://example.com', flushAt: 100, // High so flushAt doesn't trigger flushInterval: 500, fetchRetryCount: 0, disableCompression: true, waitUntil: mockWaitUntil, waitUntilDebounceMs: 60000, // Longer than flushInterval so it doesn't fire first }) posthogWithInterval.capture({ distinctId: 'user-1', event: 'event_1' }) await vi.advanceTimersByTimeAsync(0) // Debounce sentinel registered on first capture expect(mockWaitUntil).toHaveBeenCalledTimes(1) const sentinelPromise = mockWaitUntil.mock.calls[0][0] as Promise expect(mockedFetch).not.toHaveBeenCalled() // Fire the flushInterval timer (before debounce at 60s) await vi.advanceTimersByTimeAsync(500) // flushInterval-triggered flush should have sent the data expect(mockedFetch).toHaveBeenCalled() // No additional waitUntil call — debounce sentinel already keeps runtime alive expect(mockWaitUntil).toHaveBeenCalledTimes(1) await posthogWithInterval.shutdown() // Sentinel resolves after shutdown await expect(sentinelPromise).resolves.toBeUndefined() }) it('wraps manual flush() calls in waitUntil when no debounce sentinel is active', async () => { // No captures, so no debounce sentinel registered mockWaitUntil.mockClear() await posthog.flush() // flush() should register with waitUntil since no debounce sentinel exists expect(mockWaitUntil).toHaveBeenCalledTimes(1) expect(mockWaitUntil).toHaveBeenCalledWith(expect.any(Promise)) }) it('skips waitUntil registration on manual flush() when debounce sentinel is active', async () => { const posthogDebounce = new PostHog('TEST_API_KEY', { host: 'http://example.com', flushAt: 100, flushInterval: 60000, fetchRetryCount: 0, disableCompression: true, waitUntil: mockWaitUntil, waitUntilDebounceMs: 60000, // Long debounce so it doesn't fire }) // Capture establishes a debounce sentinel posthogDebounce.capture({ distinctId: 'user-1', event: 'event_1' }) await vi.advanceTimersByTimeAsync(0) expect(mockWaitUntil).toHaveBeenCalledTimes(1) // Manual flush() should skip waitUntil — sentinel already keeps runtime alive await posthogDebounce.flush() expect(mockWaitUntil).toHaveBeenCalledTimes(1) await posthogDebounce.shutdown() }) it('handles waitUntil throwing', async () => { const throwingWaitUntil = vi.fn(() => { throw new Error('Not in request context') }) const posthogThrowing = new PostHog('TEST_API_KEY', { host: 'http://example.com', flushAt: 100, flushInterval: 60000, fetchRetryCount: 0, disableCompression: true, waitUntil: throwingWaitUntil, }) posthogThrowing.capture({ distinctId: 'user-1', event: 'test_event' }) await vi.advanceTimersByTimeAsync(0) // flush() should not throw even if waitUntil throws await expect(posthogThrowing.flush()).resolves.toBeUndefined() }) it('handles waitUntil throwing during first capture scheduling', async () => { const throwingWaitUntil = vi.fn(() => { throw new Error('Not in request context') }) const posthogThrowing = new PostHog('TEST_API_KEY', { host: 'http://example.com', flushAt: 100, flushInterval: 60000, fetchRetryCount: 0, disableCompression: true, waitUntil: throwingWaitUntil, waitUntilDebounceMs: DEBOUNCE_MS, }) const captureError = vi.spyOn(console, 'error').mockImplementation(() => {}) try { expect(() => { posthogThrowing.capture({ distinctId: 'user-1', event: 'test_event' }) }).not.toThrow() await vi.advanceTimersByTimeAsync(0) expect(throwingWaitUntil).toHaveBeenCalledTimes(1) expect(throwingWaitUntil).toHaveBeenCalledWith(expect.any(Promise)) expect(captureError).not.toHaveBeenCalled() await expect(posthogThrowing.flush()).resolves.toBeUndefined() expect(getFlushedBatches().map((batch) => batch.map(({ event }) => event))).toEqual([['test_event']]) } finally { await posthogThrowing.shutdown() captureError.mockRestore() } }) }) describe('disabled client', () => { it('does not schedule debounced flush when disabled', async () => { const mockWaitUntil = vi.fn() const posthog = new PostHog('TEST_API_KEY', { host: 'http://example.com', flushAt: 100, flushInterval: 60000, fetchRetryCount: 0, disableCompression: true, disabled: true, waitUntil: mockWaitUntil, waitUntilDebounceMs: DEBOUNCE_MS, }) posthog.capture({ distinctId: 'user-1', event: 'test_event' }) await vi.advanceTimersByTimeAsync(0) // waitUntil should never be called when client is disabled expect(mockWaitUntil).not.toHaveBeenCalled() await vi.advanceTimersByTimeAsync(DEBOUNCE_MS) // No flush should have happened expect(mockedFetch).not.toHaveBeenCalled() await posthog.shutdown() }) }) describe('opted out client', () => { it('does not schedule debounced flush when opted out', async () => { const mockWaitUntil = vi.fn() const posthog = new PostHog('TEST_API_KEY', { host: 'http://example.com', flushAt: 100, flushInterval: 60000, fetchRetryCount: 0, disableCompression: true, defaultOptIn: false, waitUntil: mockWaitUntil, waitUntilDebounceMs: DEBOUNCE_MS, }) posthog.capture({ distinctId: 'user-1', event: 'test_event' }) await vi.advanceTimersByTimeAsync(0) // waitUntil should never be called when client is opted out expect(mockWaitUntil).not.toHaveBeenCalled() await vi.advanceTimersByTimeAsync(DEBOUNCE_MS) // No flush should have happened expect(mockedFetch).not.toHaveBeenCalled() await posthog.shutdown() }) }) describe('shutdown with waitUntil', () => { it('flushes all queued events during shutdown', async () => { const mockWaitUntil = vi.fn() const posthog = new PostHog('TEST_API_KEY', { host: 'http://example.com', flushAt: 100, flushInterval: 60000, fetchRetryCount: 0, disableCompression: true, waitUntil: mockWaitUntil, waitUntilDebounceMs: DEBOUNCE_MS, }) mockedFetch.mockResolvedValue(v1Response()) posthog.capture({ distinctId: 'user-1', event: 'event_1' }) posthog.capture({ distinctId: 'user-1', event: 'event_2' }) await vi.advanceTimersByTimeAsync(0) // No flush yet — debounce hasn't fired expect(mockedFetch).not.toHaveBeenCalled() await posthog.shutdown() const batches = getFlushedBatches() expect(batches).toHaveLength(1) expect(batches[0]).toHaveLength(2) expect(batches[0][0].event).toBe('event_1') expect(batches[0][1].event).toBe('event_2') }) it('flushes all queued events during shutdown when waitUntil throws', async () => { const throwingWaitUntil = vi.fn(() => { throw new Error('Not in request context') }) const posthog = new PostHog('TEST_API_KEY', { host: 'http://example.com', flushAt: 100, flushInterval: 60000, fetchRetryCount: 0, disableCompression: true, waitUntil: throwingWaitUntil, waitUntilDebounceMs: DEBOUNCE_MS, }) mockedFetch.mockResolvedValue(v1Response()) posthog.capture({ distinctId: 'user-1', event: 'event_1' }) posthog.capture({ distinctId: 'user-1', event: 'event_2' }) await vi.advanceTimersByTimeAsync(0) await posthog.shutdown() const batches = getFlushedBatches() expect(batches).toHaveLength(1) expect(batches[0]).toHaveLength(2) expect(batches[0][0].event).toBe('event_1') expect(batches[0][1].event).toBe('event_2') }) }) describe('custom debounce interval', () => { let posthog: PostHog let mockWaitUntil: vi.Mock beforeEach(() => { mockWaitUntil = vi.fn() posthog = new PostHog('TEST_API_KEY', { host: 'http://example.com', flushAt: 100, flushInterval: 60000, fetchRetryCount: 0, disableCompression: true, waitUntil: mockWaitUntil, waitUntilDebounceMs: 200, }) mockedFetch.mockResolvedValue(v1Response()) }) afterEach(async () => { await posthog.shutdown() }) it('does not flush before custom debounce interval elapses', async () => { posthog.capture({ distinctId: 'user-1', event: 'test_event' }) await vi.advanceTimersByTimeAsync(50) expect(mockedFetch).not.toHaveBeenCalled() }) it('flushes at custom debounce interval', async () => { posthog.capture({ distinctId: 'user-1', event: 'test_event' }) await vi.advanceTimersByTimeAsync(200) expect(getFlushedBatches().length).toBe(1) }) }) describe('input validation', () => { it('clamps negative waitUntilDebounceMs to 0', async () => { const posthog = new PostHog('TEST_API_KEY', { host: 'http://example.com', waitUntilDebounceMs: -100, waitUntil: vi.fn(), }) expect(posthog.options.waitUntilDebounceMs).toBe(0) await posthog.shutdown() }) it('clamps negative waitUntilMaxWaitMs to 0', async () => { const posthog = new PostHog('TEST_API_KEY', { host: 'http://example.com', waitUntilMaxWaitMs: -200, waitUntil: vi.fn(), }) expect(posthog.options.waitUntilMaxWaitMs).toBe(0) await posthog.shutdown() }) }) })