: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 { describe, expect, it, vi } from 'vitest'
import { queryHandler } from '@/tools/insights/query'
import { type Context, POSTHOG_FORMATTED_RESULTS_OVERRIDE_KEY } from '@/tools/types'
const filtersOverrideObject = { date_from: '-7d' }
const variablesOverrideObject = {
'019d4838-1da4-0000-33c7-2561bf01f1c9': {
code_name: 'eventname',
variableId: '019d4838-1da4-0000-33c7-2561bf01f1c9',
value: 'signed_up',
},
}
interface InsightsCallArgs {
insightId: string
variables_override?: string
filters_override?: string
}
interface MockHandles {
context: Context
insightsGet: ReturnType<typeof vi.fn>
insightsQuery: ReturnType<typeof vi.fn>
}
interface QueryResult {
query: unknown
results: unknown
insight: { url: string }
_posthogUrl: string
[POSTHOG_FORMATTED_RESULTS_OVERRIDE_KEY]?: string
}
function createContext(overrides?: { getData?: unknown; queryData?: unknown }): MockHandles {
const insightsGet = vi.fn().mockResolvedValue({
success: true,
data: overrides?.getData ?? {
id: 42,
short_id: 'abc12345',
query: { kind: 'HogQLQuery', query: 'select 1' },
},
})
const insightsQuery = vi.fn().mockResolvedValue({
success: true,
data: overrides?.queryData ?? { columns: ['c'], results: [[1]] },
})
const context = {
api: {
insights: vi.fn().mockReturnValue({
get: insightsGet,
query: insightsQuery,
}),
request: vi.fn(),
getProjectBaseUrl: vi.fn().mockReturnValue('https://us.posthog.com/project/1'),
},
stateManager: {
getProjectId: vi.fn().mockResolvedValue('1'),
getOrgID: vi.fn(),
getRegion: vi.fn().mockResolvedValue('us'),
},
env: { POSTHOG_BASE_URL: 'https://us.posthog.com' },
sessionManager: {},
cache: {},
getDistinctId: async () => 'test',
} as unknown as Context
return { context, insightsGet, insightsQuery }
}
describe('queryHandler — overrides forwarding', () => {
it('forwards a string variables_override unchanged', async () => {
const { context, insightsGet } = createContext()
const variables_override = JSON.stringify(variablesOverrideObject)
await queryHandler(context, { insightId: '42', output_format: 'json', variables_override })
const call = insightsGet.mock.calls[0]![0] as InsightsCallArgs
expect(call.variables_override).toBe(variables_override)
expect(call.filters_override).toBeUndefined()
})
it('JSON.stringify-s an object variables_override before forwarding', async () => {
const { context, insightsGet } = createContext()
await queryHandler(context, {
insightId: '42',
output_format: 'json',
// Cast through unknown — at runtime this is what an LLM sends; the
// tool schema accepts it, but the inner client typing is string-only.
variables_override: variablesOverrideObject as unknown as string,
})
const call = insightsGet.mock.calls[0]![0] as InsightsCallArgs
expect(call.variables_override).toBe(JSON.stringify(variablesOverrideObject))
})
it('JSON.stringify-s an object filters_override before forwarding', async () => {
const { context, insightsGet } = createContext()
await queryHandler(context, {
insightId: '42',
output_format: 'json',
filters_override: filtersOverrideObject as unknown as string,
})
const call = insightsGet.mock.calls[0]![0] as InsightsCallArgs
expect(call.filters_override).toBe(JSON.stringify(filtersOverrideObject))
})
it('handles undefined overrides without coercing them to "undefined"', async () => {
const { context, insightsGet } = createContext()
await queryHandler(context, { insightId: '42', output_format: 'json' })
const call = insightsGet.mock.calls[0]![0] as InsightsCallArgs
expect(call.variables_override).toBeUndefined()
expect(call.filters_override).toBeUndefined()
})
it('forwards mixed string + object overrides correctly', async () => {
const { context, insightsGet } = createContext()
const filters_override = JSON.stringify(filtersOverrideObject)
await queryHandler(context, {
insightId: '42',
output_format: 'json',
variables_override: variablesOverrideObject as unknown as string,
filters_override,
})
const call = insightsGet.mock.calls[0]![0] as InsightsCallArgs
expect(call.variables_override).toBe(JSON.stringify(variablesOverrideObject))
expect(call.filters_override).toBe(filters_override)
})
})
describe('queryHandler — link reflects overrides', () => {
it('links to the bare saved insight when no overrides are passed', async () => {
const { context } = createContext()
const result = (await queryHandler(context, { insightId: '42', output_format: 'json' })) as QueryResult
expect(result._posthogUrl).toBe('https://us.posthog.com/project/1/insights/abc12345')
expect(result.insight.url).toBe('https://us.posthog.com/project/1/insights/abc12345')
})
it('encodes filters_override into the link query string', async () => {
const { context } = createContext()
const result = (await queryHandler(context, {
insightId: '42',
output_format: 'json',
filters_override: filtersOverrideObject as unknown as string,
})) as QueryResult
const expected = `https://us.posthog.com/project/1/insights/abc12345?filters_override=${encodeURIComponent(
JSON.stringify(filtersOverrideObject)
)}`
expect(result._posthogUrl).toBe(expected)
expect(result.insight.url).toBe(expected)
})
it('encodes both variables_override and filters_override into the link', async () => {
const { context } = createContext()
const result = (await queryHandler(context, {
insightId: '42',
output_format: 'json',
variables_override: variablesOverrideObject as unknown as string,
filters_override: JSON.stringify(filtersOverrideObject),
})) as QueryResult
const expected = `https://us.posthog.com/project/1/insights/abc12345?variables_override=${encodeURIComponent(
JSON.stringify(variablesOverrideObject)
)}&filters_override=${encodeURIComponent(JSON.stringify(filtersOverrideObject))}`
expect(result._posthogUrl).toBe(expected)
})
})
describe('queryHandler — result shape for UI rendering', () => {
const formatted = 'c\n1'
it.each(['optimized', 'json'] as const)(
'returns event rows without a formatter in %s output',
async (output_format) => {
const query = {
kind: 'DataTableNode',
source: { kind: 'EventsQuery', select: ['event', 'timestamp'], limit: 25 },
}
const queryData = { columns: ['event', 'timestamp'], results: [['example_event', '2026-01-01T00:00:00Z']] }
const { context, insightsQuery } = createContext({
getData: { id: 42, short_id: 'abc12345', query },
queryData,
})
const result = (await queryHandler(context, { insightId: '42', output_format })) as QueryResult
expect(insightsQuery).toHaveBeenCalledWith({ query })
expect(result.results).toEqual(queryData)
expect(result[POSTHOG_FORMATTED_RESULTS_OVERRIDE_KEY]).toBeUndefined()
}
)
it('keeps structured results for a HogQL insight in optimized output', async () => {
const { context } = createContext({
queryData: { columns: ['c'], results: [[1]], formatted_results: formatted },
})
const result = (await queryHandler(context, { insightId: '42', output_format: 'optimized' })) as QueryResult
// The UI app's structuredContent must carry the structured shape its guards expect,
// not the formatted string — otherwise the table can't render.
expect(result.results).toEqual({ columns: ['c'], results: [[1]] })
expect(result[POSTHOG_FORMATTED_RESULTS_OVERRIDE_KEY]).toBe(formatted)
})
it('keeps structured results for a DataVisualizationNode-wrapped HogQL insight in optimized output', async () => {
const { context } = createContext({
getData: {
id: 42,
short_id: 'abc12345',
query: { kind: 'DataVisualizationNode', source: { kind: 'HogQLQuery', query: 'select 1' } },
},
queryData: { columns: ['org_id', 'cost'], results: [['a', 1]], formatted_results: formatted },
})
const result = (await queryHandler(context, { insightId: '42', output_format: 'optimized' })) as QueryResult
expect(result.results).toEqual({ columns: ['org_id', 'cost'], results: [['a', 1]] })
expect(result[POSTHOG_FORMATTED_RESULTS_OVERRIDE_KEY]).toBe(formatted)
})
it('does not surface the formatted override in json output', async () => {
const { context } = createContext({
queryData: { columns: ['c'], results: [[1]], formatted_results: formatted },
})
const result = (await queryHandler(context, { insightId: '42', output_format: 'json' })) as QueryResult
expect(result.results).toEqual({ columns: ['c'], results: [[1]] })
expect(result[POSTHOG_FORMATTED_RESULTS_OVERRIDE_KEY]).toBeUndefined()
})
it('passes the raw results array through for trends insights', async () => {
const trendsResults = [{ data: [1, 2], labels: ['a', 'b'] }]
const { context } = createContext({
getData: {
id: 42,
short_id: 'abc12345',
query: { kind: 'InsightVizNode', source: { kind: 'TrendsQuery' } },
},
queryData: { results: trendsResults, formatted_results: formatted },
})
const result = (await queryHandler(context, { insightId: '42', output_format: 'optimized' })) as QueryResult
expect(result.results).toBe(trendsResults)
expect(result.query).toEqual({ kind: 'TrendsQuery' })
expect(result[POSTHOG_FORMATTED_RESULTS_OVERRIDE_KEY]).toBe(formatted)
})
it.each([
['RetentionQuery', [{ date: '2024-01-01', label: 'Day 0', values: [{ count: 10 }] }]],
['LifecycleQuery', [{ status: 'new', data: [1, 2], days: ['a', 'b'] }]],
['StickinessQuery', [{ count: 5, data: [1, 2], labels: ['1 day', '2 days'] }]],
['PathsQuery', [{ source: '0_a', target: '1_b', value: 3 }]],
])('passes the raw results array through for %s insights', async (kind, chartResults) => {
const { context } = createContext({
getData: {
id: 42,
short_id: 'abc12345',
query: { kind: 'InsightVizNode', source: { kind } },
},
queryData: { results: chartResults },
})
const result = (await queryHandler(context, { insightId: '42', output_format: 'json' })) as QueryResult
// Chart visualizers read the raw array; wrapping it in { columns, results } makes the
// structural guards fall through to the table renderer and show an empty table.
expect(result.results).toBe(chartResults)
expect(result.query).toEqual({ kind })
})
})