:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import { HttpResponse } from 'msw'
import posthog from 'posthog-js'
import api, { ApiError } from 'lib/api'
import { NetworkError } from 'lib/api-error'
import { useMocks } from '~/mocks/jest'
import { performQuery, pollForResults, queryExportContext, waitForPageVisible } from '~/queries/query'
import { setLatestVersionsOnQuery } from '~/queries/schema/query-versions'
import { EventsQuery, HogQLQuery, NodeKind, RefreshType, WebStatsBreakdown } from '~/queries/schema/schema-general'
import { initKeaTests } from '~/test/init'
import { PropertyFilterType, PropertyOperator } from '~/types'
describe('query', () => {
beforeEach(() => {
useMocks({
post: {
'/api/environments/:team_id/query/:kind': async ({ request }) => {
const data = (await request.json()) as any
if (data.query?.kind === 'HogQLQuery') {
return [
200,
{ results: [], clickhouse: 'clickhouse string', hogql: 'hogql string', is_cached: false },
]
}
if (data.query?.kind === 'WebStatsTableQuery') {
return [
200,
{
results: [],
is_cached: false,
preComputeStrategy: 'lazy_precompute',
preComputeStale: true,
},
]
}
if (data.query?.kind === 'EventsQuery' && data.query.select[0] === 'error') {
return [500, { detail: 'error' }]
}
return [200, {}]
},
},
})
initKeaTests()
})
it('can generate events table export context', () => {
const q: EventsQuery = {
kind: NodeKind.EventsQuery,
select: [
'*',
'event',
'person',
'coalesce(properties.$current_url, properties.$screen_name) -- Url / Screen',
'properties.$lib',
'timestamp',
],
properties: [
{
type: PropertyFilterType.Event,
key: '$browser',
operator: PropertyOperator.Exact,
value: 'Chrome',
},
],
limit: 100,
}
const actual = queryExportContext(q, {}, false)
expect(actual).toEqual({
source: {
kind: 'EventsQuery',
limit: 100,
properties: [
{
key: '$browser',
operator: 'exact',
type: 'event',
value: 'Chrome',
},
],
select: [
'*',
'event',
'person',
'coalesce(properties.$current_url, properties.$screen_name) -- Url / Screen',
'properties.$lib',
'timestamp',
],
},
})
})
it('emits an event when a query is run', async () => {
const captureSpy = jest.spyOn(posthog, 'capture')
const querySpy = jest.spyOn(api, 'query')
const q: EventsQuery = setLatestVersionsOnQuery({
kind: NodeKind.EventsQuery,
select: ['timestamp'],
limit: 100,
})
captureSpy.mockClear()
const onRequestTiming = jest.fn()
await performQuery(q, { onRequestTiming })
const queryCompletedCalls = captureSpy.mock.calls.filter((call) => call[0] === 'query completed')
expect(queryCompletedCalls).toHaveLength(1)
expect(queryCompletedCalls[0][1]).toMatchObject({
query: q,
duration: expect.any(Number),
client_query_id: querySpy.mock.calls.at(-1)?.[1]?.clientQueryId,
submit_attempts: 1,
retry_wait_ms: expect.any(Number),
retry_status: null,
retry_recovered: false,
submit_request_timings: [
expect.objectContaining({
request_total_ms: expect.any(Number),
time_to_headers_ms: expect.any(Number),
body_read_ms: expect.any(Number),
json_parse_ms: expect.any(Number),
http_status: 200,
}),
],
time_to_headers_ms: expect.any(Number),
body_read_ms: expect.any(Number),
json_parse_ms: expect.any(Number),
resource_timing_status: 'missing_request_id',
})
expect(onRequestTiming).toHaveBeenCalledTimes(1)
expect(onRequestTiming).toHaveBeenCalledWith(queryCompletedCalls[0][1]?.submit_request_timings?.[0])
expect(queryCompletedCalls[0][1]).not.toHaveProperty('result_poll_timing')
})
it('emits a specific event on a HogQLQuery', async () => {
const captureSpy = jest.spyOn(posthog, 'capture')
const q: HogQLQuery = setLatestVersionsOnQuery({
kind: NodeKind.HogQLQuery,
query: 'select * from events',
})
captureSpy.mockClear()
await performQuery(q)
const queryCompletedCalls = captureSpy.mock.calls.filter((call) => call[0] === 'query completed')
expect(queryCompletedCalls).toHaveLength(1)
expect(queryCompletedCalls[0][1]).toMatchObject({
query: q,
duration: expect.any(Number),
clickhouse_sql: expect.any(String),
is_cached: false,
})
})
it('keeps each retry timing on the existing completion event and flattens the final attempt', async () => {
const requestIds = ['11111111-1111-4111-8111-111111111111', '22222222-2222-4222-8222-222222222222']
let attempts = 0
useMocks({
post: {
'/api/environments/:team_id/query/:kind': () => {
const headers = { 'X-Request-ID': requestIds[attempts] }
return ++attempts === 1
? HttpResponse.json({ detail: 'temporarily unavailable' }, { status: 502, headers })
: HttpResponse.json({ results: [] }, { headers })
},
},
})
const captureSpy = jest.spyOn(posthog, 'capture').mockClear()
const query: HogQLQuery = { kind: NodeKind.HogQLQuery, query: 'select 1' }
await expect(performQuery(query)).resolves.toMatchObject({ results: [] })
const completed = captureSpy.mock.calls.filter(([event]) => event === 'query completed')
expect(completed).toHaveLength(1)
expect(completed[0][1]).toMatchObject({
submit_attempts: 2,
submit_request_timings: [
expect.objectContaining({ http_status: 502, http_request_id: requestIds[0] }),
expect.objectContaining({ http_status: 200, http_request_id: requestIds[1] }),
],
http_request_id: requestIds[1],
body_read_ms: expect.any(Number),
})
})
it('records only the poll that returns the completed async result', async () => {
const pollRequestIds = ['33333333-3333-4333-8333-333333333333', '44444444-4444-4444-8444-444444444444']
let polls = 0
useMocks({
post: {
'/api/environments/:team_id/query/:kind': () => [
200,
{ query_status: { id: 'async-query', complete: false } },
],
},
get: {
'/api/environments/:team_id/query/:id': () => {
const complete = polls === 1
const headers = { 'X-Request-ID': pollRequestIds[polls++] }
return HttpResponse.json(
{ query_status: { id: 'async-query', complete, results: complete ? { results: [] } : null } },
{ headers }
)
},
},
})
jest.useFakeTimers()
const captureSpy = jest.spyOn(posthog, 'capture').mockClear()
const query: HogQLQuery = { kind: NodeKind.HogQLQuery, query: 'select 1' }
try {
const promise = performQuery(query, undefined, 'async')
await jest.advanceTimersByTimeAsync(1000)
await expect(promise).resolves.toEqual({ results: [] })
} finally {
jest.useRealTimers()
}
expect(polls).toBe(2)
const completed = captureSpy.mock.calls.filter(([event]) => event === 'query completed')
expect(completed).toHaveLength(1)
expect(completed[0][1]).toMatchObject({
result_poll_timing: expect.objectContaining({
http_status: 200,
http_request_id: pollRequestIds[1],
body_read_ms: expect.any(Number),
json_parse_ms: expect.any(Number),
}),
result_poll_http_request_id: pollRequestIds[1],
result_poll_body_read_ms: expect.any(Number),
result_poll_json_parse_ms: expect.any(Number),
})
expect(completed[0][1]?.submit_request_timings).toHaveLength(1)
})
it.each([
[true, 1],
[undefined, 0],
])('when uses_history_table is %s, sends %i history queried events', async (usesHistoryTable, expectedEvents) => {
useMocks({
post: {
'/api/environments/:team_id/query/:kind': () => [
200,
{
results: [],
is_cached: false,
used_data_warehouse_sources: [
{
id: 'src-1',
source_type: 'Postgres',
table_name: 'orders_cdc',
uses_history_table: usesHistoryTable,
},
],
},
],
},
})
const captureSpy = jest.spyOn(posthog, 'capture')
const q: HogQLQuery = setLatestVersionsOnQuery({ kind: NodeKind.HogQLQuery, query: 'select * from orders_cdc' })
captureSpy.mockClear()
await performQuery(q)
const historyCalls = captureSpy.mock.calls.filter((call) => call[0] === 'data warehouse history table queried')
expect(historyCalls).toHaveLength(expectedEvents)
if (expectedEvents) {
expect(historyCalls[0][1]).toMatchObject({
query_kind: NodeKind.HogQLQuery,
data_warehouse_source_ids: ['src-1'],
data_warehouse_source_types: ['Postgres'],
})
}
})
it('captures precompute strategy and staleness from web analytics responses', async () => {
const captureSpy = jest.spyOn(posthog, 'capture')
const q = setLatestVersionsOnQuery({
kind: NodeKind.WebStatsTableQuery,
breakdownBy: WebStatsBreakdown.Page,
properties: [],
}) as any
captureSpy.mockClear()
await performQuery(q)
const queryCompletedCalls = captureSpy.mock.calls.filter((call) => call[0] === 'query completed')
expect(queryCompletedCalls).toHaveLength(1)
expect(queryCompletedCalls[0][1]).toMatchObject({
precompute_strategy: 'lazy_precompute',
precompute_stale: true,
})
})
it.each([undefined, 'client-query-id'])('emits an event when a query errors with query ID %s', async (queryId) => {
const captureSpy = jest.spyOn(posthog, 'capture')
const q: EventsQuery = setLatestVersionsOnQuery({
kind: NodeKind.EventsQuery,
select: ['error'],
limit: 100,
})
captureSpy.mockClear()
await expect(async () => {
await performQuery(q, undefined, undefined, queryId)
}).rejects.toThrow(ApiError)
const queryFailedCalls = captureSpy.mock.calls.filter((call) => call[0] === 'query failed')
expect(queryFailedCalls).toHaveLength(1)
expect(queryFailedCalls[0][1]).toMatchObject({
query: q,
queryId,
duration: expect.any(Number),
error_status: 500,
error_code: null,
submit_request_timings: [
expect.objectContaining({ request_total_ms: expect.any(Number), http_status: 500 }),
],
time_to_headers_ms: expect.any(Number),
resource_timing_status: 'missing_request_id',
})
// Raw error text must stay out of telemetry
expect(queryFailedCalls[0][1]).not.toHaveProperty('error_message')
})
it('does not emit a query failed event when the request is aborted', async () => {
const captureSpy = jest.spyOn(posthog, 'capture')
const q: HogQLQuery = setLatestVersionsOnQuery({
kind: NodeKind.HogQLQuery,
query: 'select * from events',
})
captureSpy.mockClear()
const controller = new AbortController()
controller.abort()
await expect(performQuery(q, { signal: controller.signal })).rejects.toThrow()
const queryFailedCalls = captureSpy.mock.calls.filter((call) => call[0] === 'query failed')
expect(queryFailedCalls).toHaveLength(0)
})
describe('waitForPageVisible', () => {
const originalVisibilityState = document.visibilityState
afterEach(() => {
Object.defineProperty(document, 'visibilityState', { value: originalVisibilityState, configurable: true })
})
it('resolves immediately when page is visible', async () => {
Object.defineProperty(document, 'visibilityState', { value: 'visible', configurable: true })
await expect(waitForPageVisible()).resolves.toBeUndefined()
})
it('suspends when page is hidden and resolves when it becomes visible', async () => {
Object.defineProperty(document, 'visibilityState', {
value: 'hidden',
writable: true,
configurable: true,
})
let resolved = false
const promise = waitForPageVisible().then(() => {
resolved = true
})
await Promise.resolve()
expect(resolved).toBe(false)
Object.defineProperty(document, 'visibilityState', { value: 'visible', configurable: true })
document.dispatchEvent(new Event('visibilitychange'))
await promise
expect(resolved).toBe(true)
})
it('rejects with AbortError when signal is already aborted', async () => {
Object.defineProperty(document, 'visibilityState', { value: 'hidden', configurable: true })
const controller = new AbortController()
controller.abort()
await expect(waitForPageVisible(controller.signal)).rejects.toThrow('Aborted')
})
it('rejects with AbortError when signal aborts while waiting', async () => {
Object.defineProperty(document, 'visibilityState', {
value: 'hidden',
writable: true,
configurable: true,
})
const controller = new AbortController()
const promise = waitForPageVisible(controller.signal)
await Promise.resolve()
controller.abort()
await expect(promise).rejects.toThrow('Aborted')
})
it('resolves immediately when document is undefined (SSR)', async () => {
const originalDocument = globalThis.document
// @ts-expect-error -- simulating SSR by removing document
delete globalThis.document
try {
await expect(waitForPageVisible()).resolves.toBeUndefined()
} finally {
globalThis.document = originalDocument
}
})
})
describe('pollForResults and backgrounded tabs', () => {
const originalVisibilityState = document.visibilityState
afterEach(() => {
Object.defineProperty(document, 'visibilityState', { value: originalVisibilityState, configurable: true })
jest.restoreAllMocks()
})
it('does not count time spent hidden against the poll deadline', async () => {
Object.defineProperty(document, 'visibilityState', { value: 'visible', configurable: true })
let now = 0
jest.spyOn(performance, 'now').mockImplementation(() => now)
jest.spyOn(api.queryStatus, 'get')
.mockResolvedValueOnce({ query_status: { complete: false } } as any)
.mockResolvedValueOnce({ query_status: { complete: true, results: ['ok'] } } as any)
const promise = pollForResults('test-query-id', undefined, () => {
// Fires right after the first (incomplete) poll, before the loop rechecks its
// deadline for the next one. Simulate the tab backgrounding for longer than the
// whole poll deadline (10m6s) right here: a wall-clock deadline would time out on
// the very next check, even though no polling actually happened during that time.
Object.defineProperty(document, 'visibilityState', { value: 'hidden', configurable: true })
now += 11 * 60 * 1000
setTimeout(() => {
Object.defineProperty(document, 'visibilityState', { value: 'visible', configurable: true })
document.dispatchEvent(new Event('visibilitychange'))
}, 0)
})
await expect(promise).resolves.toMatchObject({ complete: true, results: ['ok'] })
})
})
describe('pollForResults while offline', () => {
const originalVisibilityState = document.visibilityState
beforeEach(() => {
jest.useFakeTimers()
jest.spyOn(navigator, 'onLine', 'get').mockReturnValue(true)
})
afterEach(() => {
Object.defineProperty(document, 'visibilityState', { value: originalVisibilityState, configurable: true })
jest.restoreAllMocks()
jest.useRealTimers()
})
it.each(['before polling', 'during the poll delay', 'while hidden'])(
'waits for reconnect %s without using the deadline',
async (when) => {
const online = jest.spyOn(navigator, 'onLine', 'get')
online.mockReturnValue(when === 'during the poll delay')
const status = { complete: true, results: ['ok'] }
const statusSpy = jest.spyOn(api.queryStatus, 'get').mockResolvedValue({ query_status: status } as any)
const promise = pollForResults('test-query-id')
if (when === 'during the poll delay') {
await jest.advanceTimersByTimeAsync(100)
online.mockReturnValue(false)
}
await jest.advanceTimersByTimeAsync(11 * 60 * 1000)
expect(statusSpy).not.toHaveBeenCalled()
if (when === 'while hidden') {
Object.defineProperty(document, 'visibilityState', { value: 'hidden', configurable: true })
}
online.mockReturnValue(true)
window.dispatchEvent(new Event('online'))
if (when === 'while hidden') {
await jest.advanceTimersByTimeAsync(1000)
expect(statusSpy).not.toHaveBeenCalled()
Object.defineProperty(document, 'visibilityState', { value: 'visible', configurable: true })
document.dispatchEvent(new Event('visibilitychange'))
}
await jest.advanceTimersByTimeAsync(300)
await expect(promise).resolves.toEqual(status)
}
)
it.each([false, true])('recovers an offline poll when already reconnected is %s', async (reconnected) => {
const online = jest.spyOn(navigator, 'onLine', 'get')
const querySpy = jest
.spyOn(api, 'query')
.mockResolvedValue({ query_status: { id: 'test-query-id', complete: false } } as any)
const statusSpy = jest
.spyOn(api.queryStatus, 'get')
.mockImplementationOnce(async () => {
online.mockReturnValue(reconnected)
throw new NetworkError('offline')
})
.mockResolvedValueOnce({ query_status: { complete: true, results: ['ok'] } } as any)
const capture = jest.spyOn(posthog, 'capture').mockClear()
const promise = performQuery({ kind: NodeKind.EventsQuery, select: ['*'] }, undefined, 'async')
await jest.advanceTimersByTimeAsync(300)
if (!reconnected) {
await jest.advanceTimersByTimeAsync(11 * 60 * 1000)
expect(statusSpy).toHaveBeenCalledTimes(1)
online.mockReturnValue(true)
window.dispatchEvent(new Event('online'))
}
await jest.advanceTimersByTimeAsync(375)
await expect(promise).resolves.toEqual(['ok'])
expect(querySpy).toHaveBeenCalledTimes(1)
expect(statusSpy.mock.calls.map(([id]) => id)).toEqual(['test-query-id', 'test-query-id'])
expect(capture.mock.calls.filter(([event]) => event === 'query failed')).toHaveLength(0)
expect(capture.mock.calls.filter(([event]) => event === 'query completed')).toHaveLength(1)
})
it.each(['before polling', 'while waiting'])('cancels offline polling %s', async (when) => {
jest.spyOn(navigator, 'onLine', 'get').mockReturnValue(false)
const statusSpy = jest.spyOn(api.queryStatus, 'get')
const controller = new AbortController()
if (when === 'before polling') {
controller.abort()
}
const promise = pollForResults('test-query-id', { signal: controller.signal })
// oxlint-disable-next-line jest/valid-expect -- awaited after the abort below; awaiting here hangs the test
const rejected = expect(promise).rejects.toMatchObject({ name: 'AbortError' })
await jest.advanceTimersByTimeAsync(0)
controller.abort()
await rejected
jest.spyOn(navigator, 'onLine', 'get').mockReturnValue(true)
window.dispatchEvent(new Event('online'))
await jest.advanceTimersByTimeAsync(1000)
expect(statusSpy).not.toHaveBeenCalled()
})
})
describe('polling a query the server has forgotten', () => {
const query = { kind: NodeKind.EventsQuery, select: ['*'] } as EventsQuery
const submitted = (id: string): any => ({ query_status: { id, complete: false } })
const forgotten = (): ApiError => new ApiError('Query not found', 404, undefined, { detail: 'Query not found' })
afterEach(() => {
jest.restoreAllMocks()
delete (window as any).POSTHOG_EXPORTED_DATA
})
it('runs the query again when its status has expired', async () => {
const captureSpy = jest.spyOn(posthog, 'capture').mockClear()
const querySpy = jest
.spyOn(api, 'query')
.mockResolvedValueOnce(submitted('gone'))
.mockResolvedValueOnce({ results: ['from the cache'], is_cached: true } as any)
jest.spyOn(api.queryStatus, 'get').mockRejectedValueOnce(forgotten())
await expect(performQuery(query, undefined, 'async')).resolves.toMatchObject({
results: ['from the cache'],
})
expect(querySpy).toHaveBeenCalledTimes(2)
// Same ID, so anything holding it still points at the run the user is waiting for.
expect(querySpy.mock.calls[1][1]?.clientQueryId).toBe('gone')
expect(captureSpy.mock.calls.find(([event]) => event === 'query completed')?.[1]).toMatchObject({
client_query_id: 'gone',
submit_attempts: 2,
retry_status: 404,
retry_recovered: true,
})
})
it('reads the cache on the retry rather than forcing the same work twice', async () => {
const querySpy = jest
.spyOn(api, 'query')
.mockResolvedValueOnce(submitted('gone'))
.mockResolvedValueOnce({ results: ['from the cache'], is_cached: true } as any)
jest.spyOn(api.queryStatus, 'get').mockRejectedValueOnce(forgotten())
await performQuery(query, undefined, 'force_async')
// force_async disregards the cache, and the first run already cached what it computed.
expect(querySpy.mock.calls[0][1]?.refresh).toBe('force_async')
expect(querySpy.mock.calls[1][1]?.refresh).toBe('async')
})
it.each([
{ name: 'a failed rerun', results: undefined, error: true, recovered: false },
{ name: 'an empty result', results: [], error: false, recovered: true },
])('records recovery accurately for $name after expiry', async ({ results, error, recovered }) => {
const capture = jest.spyOn(posthog, 'capture').mockImplementation()
jest.spyOn(api, 'query').mockResolvedValueOnce(submitted('gone')).mockResolvedValueOnce(submitted('rerun'))
jest.spyOn(api.queryStatus, 'get')
.mockRejectedValueOnce(forgotten())
.mockResolvedValueOnce({ query_status: { id: 'rerun', complete: true, error, results } } as any)
await expect(performQuery(query, undefined, 'async')).resolves.toEqual(results)
expect(capture.mock.calls.find(([event]) => event === 'query completed')?.[1]).toMatchObject({
submit_attempts: 2,
retry_status: 404,
retry_recovered: recovered,
})
})
it.each([
['an error that is not a 404', new ApiError('boom', 500), undefined],
['a network failure while online', new NetworkError('network'), undefined],
['a request during navigation', new NetworkError('navigating'), undefined],
['an error with a caller-supplied ID', new ApiError('boom', 500), 'client-query-id'],
[
'a warehouse whose connection is down',
new ApiError('unavailable', 404, undefined, { code: 'managed_warehouse_connection_unavailable' }),
undefined,
],
])('reports the failed poll without resubmitting on %s', async (_name, failure, clientQueryId) => {
const captureSpy = jest.spyOn(posthog, 'capture').mockClear()
const querySpy = jest.spyOn(api, 'query').mockResolvedValueOnce(submitted('gone'))
jest.spyOn(api.queryStatus, 'get').mockRejectedValueOnce(failure)
await expect(performQuery(query, undefined, 'async', clientQueryId)).rejects.toBe(failure)
expect(querySpy).toHaveBeenCalledTimes(1)
const queryFailedCalls = captureSpy.mock.calls.filter((call) => call[0] === 'query failed')
expect(queryFailedCalls).toHaveLength(1)
expect(queryFailedCalls[0][1]).toMatchObject({ queryId: 'gone', error_status: failure.status ?? null })
expect(captureSpy.mock.calls.filter((call) => call[0] === 'query completed')).toHaveLength(0)
})
it('gives up when the second attempt is forgotten too', async () => {
jest.spyOn(api, 'query').mockResolvedValue(submitted('gone'))
const statusSpy = jest.spyOn(api.queryStatus, 'get').mockRejectedValue(forgotten())
await expect(performQuery(query, undefined, 'async')).rejects.toMatchObject({ status: 404 })
expect(statusSpy).toHaveBeenCalledTimes(2)
})
it('runs the query again for a tile resuming a recompute, which polls by id but holds the query', async () => {
const querySpy = jest
.spyOn(api, 'query')
.mockResolvedValueOnce({ results: ['from the cache'], is_cached: true } as any)
jest.spyOn(api.queryStatus, 'get').mockRejectedValueOnce(forgotten())
await expect(
performQuery(query, undefined, 'async', 'resumed', undefined, undefined, undefined, true)
).resolves.toMatchObject({ results: ['from the cache'] })
expect(querySpy).toHaveBeenCalledTimes(1)
})
it('does not even try to resubmit from a shared or exported view', async () => {
const querySpy = jest.spyOn(api, 'query')
jest.spyOn(api.queryStatus, 'get').mockRejectedValueOnce(forgotten())
;(window as any).POSTHOG_EXPORTED_DATA = { type: 'embed' }
await expect(
performQuery(query, undefined, 'async', 'gone', undefined, undefined, undefined, true)
).rejects.toMatchObject({ status: 404 })
expect(querySpy).not.toHaveBeenCalled()
})
})
it('throws a readable ApiError when the query endpoint returns no content', async () => {
jest.spyOn(api, 'query').mockResolvedValueOnce(null as any)
const promise = performQuery(
{ kind: NodeKind.EventsQuery, select: ['*'] } as EventsQuery,
undefined,
'blocking'
)
await expect(promise).rejects.toBeInstanceOf(ApiError)
await expect(promise).rejects.toMatchObject({ detail: expect.stringContaining('empty response') })
jest.restoreAllMocks()
})
describe('transient query submission failures', () => {
const query = { kind: NodeKind.EventsQuery, select: ['*'] } as EventsQuery
const refused = (): ApiError => new ApiError('', 503, undefined, {})
const badGateway = (): ApiError => new ApiError('', 502, undefined, {})
const shortCapacityWait = (): ApiError => new ApiError('', 503, new Headers({ 'Retry-After': '5' }), {})
afterEach(() => {
jest.useRealTimers()
jest.restoreAllMocks()
})
it.each([
['a 502 bad gateway', badGateway, 600, ['ok'], true],
['a capacity 503 asked for a short wait', shortCapacityWait, 5000, ['ok'], true],
[
'a capacity 503 at the total retry budget',
() => new ApiError('', 503, new Headers({ 'Retry-After': '20' })),
20000,
['ok'],
true,
],
['a capacity retry returns an empty result', shortCapacityWait, 5000, [], true],
['a capacity retry returns no result', shortCapacityWait, 5000, null, false],
])(
'submits the same run again once the wait ends after %s, and returns what the retry gets',
async (_name, makeError, waitMs, results, recovered) => {
jest.useFakeTimers()
const captureSpy = jest.spyOn(posthog, 'capture').mockClear()
const error = makeError()
const querySpy = jest
.spyOn(api, 'query')
.mockRejectedValueOnce(error)
.mockResolvedValueOnce({ results } as any)
const promise = performQuery(query, undefined, 'blocking')
await jest.advanceTimersByTimeAsync(waitMs - 1)
expect(querySpy).toHaveBeenCalledTimes(1)
await jest.advanceTimersByTimeAsync(1)
await expect(promise).resolves.toMatchObject({ results })
expect(querySpy).toHaveBeenCalledTimes(2)
const firstId = querySpy.mock.calls[0][1]?.clientQueryId
expect(firstId).toBeTruthy()
expect(querySpy.mock.calls[1][1]?.clientQueryId).toBe(firstId)
const completed = captureSpy.mock.calls.filter(([event]) => event === 'query completed')
expect(completed).toHaveLength(1)
expect(completed[0][1]).toMatchObject({
client_query_id: firstId,
submit_attempts: 2,
retry_wait_ms: waitMs,
retry_status: error.status,
retry_recovered: recovered,
})
expect(captureSpy.mock.calls.filter(([event]) => event === 'query failed')).toHaveLength(0)
}
)
it('does not resubmit when the query is aborted during the capacity wait', async () => {
jest.useFakeTimers()
const captureSpy = jest.spyOn(posthog, 'capture').mockClear()
const controller = new AbortController()
const querySpy = jest
.spyOn(api, 'query')
.mockRejectedValueOnce(shortCapacityWait())
.mockResolvedValueOnce({ results: ['ok'] } as any)
const outcome = Promise.allSettled([performQuery(query, { signal: controller.signal }, 'blocking')])
await jest.advanceTimersByTimeAsync(1000)
expect(querySpy).toHaveBeenCalledTimes(1)
controller.abort()
await jest.advanceTimersByTimeAsync(5000)
await expect(outcome).resolves.toMatchObject([{ status: 'rejected', reason: { name: 'AbortError' } }])
expect(querySpy).toHaveBeenCalledTimes(1)
expect(
captureSpy.mock.calls.filter(([event]) => event === 'query completed' || event === 'query failed')
).toHaveLength(0)
})
it.each([
{ name: 'empty result', error: false, results: { results: [] }, recovered: true },
{ name: 'error stub', error: true, results: undefined, recovered: false },
{ name: 'errored result', error: true, results: { results: [] }, recovered: false },
])('records async recovery only after a usable result ($name)', async ({ error, results, recovered }) => {
jest.useFakeTimers()
const captureSpy = jest.spyOn(posthog, 'capture').mockClear()
jest.spyOn(api, 'query')
.mockRejectedValueOnce(shortCapacityWait())
.mockResolvedValueOnce({ query_status: { id: 'retry-query', complete: false } } as any)
jest.spyOn(api.queryStatus, 'get').mockResolvedValueOnce({
query_status: { id: 'retry-query', complete: true, error, results },
} as any)
const promise = performQuery(query, undefined, 'async', 'retry-query')
await jest.advanceTimersByTimeAsync(5000)
expect(captureSpy.mock.calls.filter(([event]) => event === 'query completed')).toHaveLength(0)
await jest.advanceTimersByTimeAsync(300)
await expect(promise).resolves.toEqual(results)
const completed = captureSpy.mock.calls.filter(([event]) => event === 'query completed')
expect(completed).toHaveLength(1)
expect(completed[0][1]).toMatchObject({
client_query_id: 'retry-query',
submit_attempts: 2,
retry_wait_ms: 5000,
retry_status: 503,
retry_recovered: recovered,
})
})
it.each([
['the gateway refuses every attempt', badGateway, 1800, 502],
['every attempt gets a short capacity wait', shortCapacityWait, 10000, 503],
[
'both capacity waits fit the total budget exactly',
() => new ApiError('', 503, new Headers({ 'Retry-After': '10' })),
20000,
503,
],
])('reports the failure once %s', async (_name, makeError, elapsedMs, status) => {
jest.useFakeTimers()
const captureSpy = jest.spyOn(posthog, 'capture').mockClear()
const querySpy = jest.spyOn(api, 'query').mockRejectedValue(makeError())
const outcome = Promise.allSettled([performQuery(query, undefined, 'blocking')])
await jest.advanceTimersByTimeAsync(elapsedMs - 1)
expect(querySpy).toHaveBeenCalledTimes(2)
await jest.advanceTimersByTimeAsync(1)
await expect(outcome).resolves.toMatchObject([{ status: 'rejected', reason: { status } }])
expect(querySpy).toHaveBeenCalledTimes(3)
const failed = captureSpy.mock.calls.filter(([event]) => event === 'query failed')
expect(failed).toHaveLength(1)
expect(failed[0][1]).toMatchObject({
client_query_id: querySpy.mock.calls[0][1]?.clientQueryId,
submit_attempts: 3,
retry_wait_ms: elapsedMs,
retry_status: status,
error_status: status,
})
expect(captureSpy.mock.calls.filter(([event]) => event === 'query completed')).toHaveLength(0)
})
it.each([
['the two hints exceed the budget', 15, 10, 0],
['the failed retry uses the remaining budget', 5, 10, 6000],
])('surfaces the full next cooldown when %s', async (_name, firstWait, nextWait, requestTimeMs) => {
jest.useFakeTimers()
const captureSpy = jest.spyOn(posthog, 'capture').mockClear()
let lastError: ApiError | undefined
const querySpy = jest
.spyOn(api, 'query')
.mockRejectedValueOnce(new ApiError('', 503, new Headers({ 'Retry-After': String(firstWait) })))
.mockImplementationOnce(async () => {
await new Promise((resolve) => setTimeout(resolve, requestTimeMs))
lastError = new ApiError('', 503, new Headers({ 'Retry-After': String(nextWait) }))
throw lastError
})
.mockResolvedValue({ results: ['ok'] } as any)
let receivedError: unknown
const outcome = performQuery(query, undefined, 'blocking').catch((error) => {
receivedError = error
})
await jest.advanceTimersByTimeAsync(firstWait * 1000 + requestTimeMs + 1)
expect(receivedError).toBeInstanceOf(ApiError)
expect(receivedError).toBe(lastError)
expect(lastError?.retryAfterSeconds).toBe(nextWait)
await jest.advanceTimersByTimeAsync(60_000)
await outcome
expect(querySpy).toHaveBeenCalledTimes(2)
expect(captureSpy.mock.calls.find(([event]) => event === 'query failed')?.[1]).toMatchObject({
submit_attempts: 2,
retry_wait_ms: firstWait * 1000,
retry_status: 503,
})
})
it.each([
{ waitSeconds: 20, resumedAt: 20_050, retries: true },
{ waitSeconds: 20, resumedAt: 21_000, retries: false },
{ waitSeconds: 5, resumedAt: 21_000, retries: false },
])(
'bounds timer lateness after a $waitSeconds second hint (resumed at $resumedAt ms)',
async ({ waitSeconds, resumedAt, retries }) => {
jest.useFakeTimers()
const captureSpy = jest.spyOn(posthog, 'capture').mockClear()
const clock = jest.spyOn(performance, 'now').mockReturnValue(0)
const error = new ApiError('', 503, new Headers({ 'Retry-After': String(waitSeconds) }))
const querySpy = jest
.spyOn(api, 'query')
.mockRejectedValueOnce(error)
.mockResolvedValue({ results: ['ok'] } as any)
const outcome = Promise.allSettled([performQuery(query, undefined, 'blocking')])
await jest.advanceTimersByTimeAsync(0)
await jest.advanceTimersByTimeAsync(waitSeconds * 1000 - 1)
expect(querySpy).toHaveBeenCalledTimes(1)
clock.mockReturnValue(resumedAt)
await jest.advanceTimersByTimeAsync(1)
await expect(outcome).resolves.toEqual([
retries
? { status: 'fulfilled', value: { results: ['ok'] } }
: { status: 'rejected', reason: error },
])
expect(querySpy).toHaveBeenCalledTimes(retries ? 2 : 1)
const eventName = retries ? 'query completed' : 'query failed'
expect(captureSpy.mock.calls.find(([event]) => event === eventName)?.[1]).toMatchObject({
submit_attempts: retries ? 2 : 1,
retry_wait_ms: resumedAt,
retry_status: retries ? 503 : null,
})
}
)
it.each(
(['force_blocking', 'force_async'] as RefreshType[]).flatMap((refresh) =>
[502, 503].map((status) => ({ refresh, status }))
)
)(
'retries $refresh only with a capacity hint, not an ambiguous gateway failure (status=$status)',
async ({ refresh, status }) => {
jest.useFakeTimers()
const error = status === 502 ? badGateway() : shortCapacityWait()
const querySpy = jest
.spyOn(api, 'query')
.mockRejectedValueOnce(error)
.mockResolvedValue({ results: ['ok'] } as any)
const outcome = Promise.allSettled([performQuery(query, undefined, refresh)])
await jest.advanceTimersByTimeAsync(4999)
expect(querySpy).toHaveBeenCalledTimes(1)
await jest.advanceTimersByTimeAsync(1)
await expect(outcome).resolves.toEqual([
status === 502
? { status: 'rejected', reason: error }
: { status: 'fulfilled', value: { results: ['ok'] } },
])
expect(querySpy).toHaveBeenCalledTimes(status === 502 ? 1 : 2)
}
)
it.each([
['a 503 without Retry-After', refused()],
['a 503 above the total retry budget', new ApiError('', 503, new Headers({ 'Retry-After': '21' }), {})],
['a 503 with an invalid Retry-After', new ApiError('', 503, new Headers({ 'Retry-After': '1.5' }), {})],
[
'a 503 with a date-form Retry-After',
new ApiError('', 503, new Headers({ 'Retry-After': 'Mon, 05 Oct 2026 12:00:05 GMT' }), {}),
],
['a capacity 503 with Retry-After', new ApiError('', 503, new Headers({ 'Retry-After': '45' }), {})],
['a 504, where the backend can still be running the query', new ApiError('', 504, undefined, {})],
])('does not submit again after %s', async (_name, error) => {
jest.useFakeTimers()
const querySpy = jest.spyOn(api, 'query').mockRejectedValue(error)
const outcome = Promise.allSettled([performQuery(query, undefined, 'blocking')])
await jest.advanceTimersByTimeAsync(60_000)
await expect(outcome).resolves.toEqual([{ status: 'rejected', reason: error }])
expect(querySpy).toHaveBeenCalledTimes(1)
})
})
describe('pollForResults error message parsing', () => {
it('prefers the structured error_code from the query status over one parsed from the message', async () => {
jest.spyOn(api.queryStatus, 'get').mockRejectedValueOnce({
data: {
query_status: {
error_message: 'This query ran out of memory before it could finish',
error_code: 'clickhouse_memory_limit_exceeded',
},
},
})
await expect(pollForResults('test-query-id')).rejects.toMatchObject({
detail: 'This query ran out of memory before it could finish',
code: 'clickhouse_memory_limit_exceeded',
})
})
it('parses ErrorDetail list format and extracts message and code', async () => {
jest.spyOn(api.queryStatus, 'get').mockRejectedValueOnce({
data: {
query_status: {
error_message:
"[ErrorDetail(string='Query exceeded memory limit', code='memory_limit_exceeded')]",
},
},
})
await expect(pollForResults('test-query-id')).rejects.toMatchObject({
detail: 'Query exceeded memory limit',
code: 'memory_limit_exceeded',
})
})
it('parses ErrorDetail single format and extracts message and code', async () => {
jest.spyOn(api.queryStatus, 'get').mockRejectedValueOnce({
data: {
query_status: {
error_message: "ErrorDetail(string='Database connection failed', code='db_error')",
},
},
})
await expect(pollForResults('test-query-id')).rejects.toMatchObject({
detail: 'Database connection failed',
code: 'db_error',
})
})
it('preserves original message when not in ErrorDetail format', async () => {
jest.spyOn(api.queryStatus, 'get').mockRejectedValueOnce({
data: {
query_status: {
error_message: 'Simple error message',
},
},
})
await expect(pollForResults('test-query-id')).rejects.toMatchObject({
detail: 'Simple error message',
})
})
it('preserves a detail-only API error', async () => {
jest.spyOn(api.queryStatus, 'get').mockRejectedValueOnce({
data: {
detail: 'This managed warehouse connection is no longer available. Select a source and run the query again.',
code: 'managed_warehouse_connection_unavailable',
},
})
await expect(pollForResults('test-query-id')).rejects.toMatchObject({
detail: 'This managed warehouse connection is no longer available. Select a source and run the query again.',
code: 'managed_warehouse_connection_unavailable',
})
})
it('handles undefined error message', async () => {
jest.spyOn(api.queryStatus, 'get').mockRejectedValueOnce({
data: {
query_status: {},
},
})
await expect(pollForResults('test-query-id')).rejects.toMatchObject({
detail: '',
})
})
it('handles non-string error message', async () => {
jest.spyOn(api.queryStatus, 'get').mockRejectedValueOnce({
data: {
query_status: {
error_message: { nested: 'object' },
},
},
})
await expect(pollForResults('test-query-id')).rejects.toMatchObject({
detail: { nested: 'object' },
})
})
})
})