: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 } from 'vitest'
import {
inferVisualizationType,
isFunnelResult,
isHogQLResult,
isLifecycleResult,
isPathsResult,
isRetentionResult,
isTrendsResult,
} from '@/ui-apps/components/infer-visualization'
import {
buildProportionBarSeries,
formatDate,
formatDuration,
formatNumber,
formatPercent,
getDisplayType,
getSeriesLabel,
insightQueryProperties,
normalizeFunnelSteps,
toTableResult,
} from '@/ui-apps/components/utils'
import { insightResults, queryPayload } from '../fixtures/insight-fixtures'
describe('insight visualizations', () => {
describe('inferVisualizationType', () => {
describe('inference from result shape (captured API fixtures)', () => {
it.each([
['trends line', insightResults.trendsLine, 'trends'],
['trends line with breakdown', insightResults.trendsLineBreakdown, 'trends'],
['bold-number trends (aggregated_value)', insightResults.trendsNumber, 'trends'],
['pie-display trends', insightResults.trendsPie, 'trends'],
['world-map trends', insightResults.trendsWorldMap, 'trends'],
['stickiness (duck-types as trends)', insightResults.stickiness, 'trends'],
['lifecycle', insightResults.lifecycle, 'lifecycle'],
['flat funnel', insightResults.funnelTopToBottom, 'funnel'],
['breakdown funnel (nested arrays)', insightResults.funnelTopToBottomBreakdown, 'funnel'],
['retention', insightResults.retention, 'retention'],
['paths', insightResults.userPaths, 'paths'],
['hogql table', insightResults.hogqlTable, 'table'],
] as const)('classifies %s results', (_label, results, expected) => {
expect(inferVisualizationType(queryPayload(results))).toBe(expected)
})
it('classifies lifecycle before trends even though rows also match the trends shape', () => {
expect(isTrendsResult(insightResults.lifecycle)).toBe(true)
expect(inferVisualizationType(queryPayload(insightResults.lifecycle))).toBe('lifecycle')
})
it('classifies retention before trends', () => {
expect(inferVisualizationType(queryPayload(insightResults.retention, 'TrendsQuery'))).toBe('retention')
})
it('accepts a brand-new retention cohort with an empty values array', () => {
const results = [{ date: '2025-06-01T00:00:00Z', label: 'Day 0', values: [] }]
expect(inferVisualizationType(queryPayload(results))).toBe('retention')
})
it('classifies trends-mode funnel results (data/days arrays) as trends', () => {
// Funnels in trends visualization mode return time-series rows; the shape check
// intentionally wins over the FunnelsQuery kind so they render as a line chart.
expect(
inferVisualizationType(queryPayload(insightResults.funnelHistoricalTrends, 'FunnelsQuery'))
).toBe('trends')
})
})
describe('fallback to query kind', () => {
it.each([
['TrendsQuery', 'trends'],
['StickinessQuery', 'stickiness'],
['FunnelsQuery', 'funnel'],
['LifecycleQuery', 'lifecycle'],
['RetentionQuery', 'retention'],
['PathsQuery', 'paths'],
['HogQLQuery', 'table'],
['WebStatsTableQuery', 'table'],
['WebOverviewQuery', 'table'],
['WebVitalsPathBreakdownQuery', 'table'],
] as const)('falls back to %s when results are empty', (kind, expected) => {
expect(inferVisualizationType(queryPayload([], kind))).toBe(expected)
})
it('falls back to the query kind when results is a formatted string', () => {
// If a formatted summary (a string) ever reaches the UI app as `results`, the
// structural guards can't match and only the kind fallback can classify it.
const data = queryPayload('Date | $pageview\n2025-06-01 | 10', 'TrendsQuery')
expect(inferVisualizationType(data)).toBe('trends')
})
it.each([
['DataVisualizationNode wrapping HogQLQuery', 'DataVisualizationNode', 'HogQLQuery', 'table'],
['InsightVizNode wrapping TrendsQuery', 'InsightVizNode', 'TrendsQuery', 'trends'],
['InsightVizNode wrapping StickinessQuery', 'InsightVizNode', 'StickinessQuery', 'stickiness'],
['InsightVizNode wrapping RetentionQuery', 'InsightVizNode', 'RetentionQuery', 'retention'],
] as const)('unwraps %s to its inner kind', (_label, wrapperKind, sourceKind, expected) => {
// Wrapper nodes carry the real query kind on `source.kind`; the fallback must
// unwrap so a formatted-string payload still resolves to the right visualization.
const data = { query: { kind: wrapperKind, source: { kind: sourceKind } }, results: 'col\n1' }
expect(inferVisualizationType(data)).toBe(expected)
})
it('returns null for a wrapper node with no source kind', () => {
const data = { query: { kind: 'DataVisualizationNode' }, results: 'col\n1' }
expect(inferVisualizationType(data)).toBeNull()
})
it('classifies stickiness results as stickiness, not trends, via the query kind', () => {
// Stickiness rows duck-type as trends, so the kind check must win — otherwise the
// chart renders raw counts instead of the percentage-of-users distribution.
expect(inferVisualizationType(queryPayload(insightResults.stickiness, 'StickinessQuery'))).toBe(
'stickiness'
)
})
it('falls back to FunnelsQuery for time-to-convert results (bins object)', () => {
expect(inferVisualizationType(queryPayload(insightResults.funnelTimeToConvert, 'FunnelsQuery'))).toBe(
'funnel'
)
})
})
describe('unclassifiable input', () => {
it.each([
['null', null],
['undefined', undefined],
['a string payload', 'plain text'],
['a number', 42],
['an empty object', {}],
['unknown query kind with empty results', queryPayload([], 'MysteryQuery')],
['rows matching no known shape', queryPayload([{ foo: 'bar' }])],
] as const)('returns null for %s', (_label, data) => {
expect(inferVisualizationType(data)).toBeNull()
})
})
describe('type guards', () => {
it.each([
['isTrendsResult', isTrendsResult, insightResults.trendsLine],
['isLifecycleResult', isLifecycleResult, insightResults.lifecycle],
['isFunnelResult', isFunnelResult, insightResults.funnelTopToBottom],
['isRetentionResult', isRetentionResult, insightResults.retention],
['isPathsResult', isPathsResult, insightResults.userPaths],
['isHogQLResult', isHogQLResult, insightResults.hogqlTable],
] as const)('%s accepts its own shape and rejects empties and non-arrays', (_label, guard, fixture) => {
expect(guard(fixture)).toBe(true)
expect(guard([])).toBe(false)
expect(guard(null)).toBe(false)
expect(guard('text')).toBe(false)
})
it('isFunnelResult accepts the nested breakdown format', () => {
expect(isFunnelResult(insightResults.funnelTopToBottomBreakdown)).toBe(true)
})
it('isFunnelResult rejects a nested format whose first breakdown is empty', () => {
expect(isFunnelResult([[]])).toBe(false)
})
it('isLifecycleResult rejects trends rows without a lifecycle status', () => {
expect(isLifecycleResult(insightResults.trendsLine)).toBe(false)
})
it('isHogQLResult requires both columns and results to be arrays', () => {
expect(isHogQLResult({ columns: ['a'], results: 'nope' })).toBe(false)
expect(isHogQLResult({ columns: ['a'] })).toBe(false)
})
})
})
describe('visualizer utils', () => {
describe('formatNumber', () => {
it.each([
[0, '0'],
[999, '999'],
[1000, '1.0K'],
[1500, '1.5K'],
[999_999, '1000.0K'],
[1_000_000, '1.0M'],
[2_345_678, '2.3M'],
])('formats %d as %s', (value, expected) => {
expect(formatNumber(value)).toBe(expected)
})
})
describe('formatPercent', () => {
it.each([
[0, '0.0%'],
[0.123, '12.3%'],
[0.1234, '12.3%'],
[1, '100.0%'],
])('formats %d as %s', (value, expected) => {
expect(formatPercent(value)).toBe(expected)
})
})
describe('formatDuration', () => {
it.each([
[0, '0s'],
[-5000, '0s'],
[Number.NaN, '0s'],
[Number.POSITIVE_INFINITY, '0s'],
[34_000, '34s'],
[94_000, '1m 34s'],
[3_600_000, '1h'],
[3_660_000, '1h 1m'],
// Only the two most-significant units are kept: 1d 1h 1m 1s → "1d 1h".
[90_061_000, '1d 1h'],
])('formats %dms as %s', (ms, expected) => {
expect(formatDuration(ms)).toBe(expected)
})
})
describe('formatDate', () => {
it('formats ISO date strings as a short month + day', () => {
// Noon, no timezone suffix — parses as local time so the day is stable in any test TZ.
expect(formatDate('2025-06-01T12:00:00')).toBe('Jun 1')
})
it.each([['Day 1'], ['1 day'], ['Week 3'], ['']])(
'passes through pre-formatted label %j unchanged',
(label) => {
expect(formatDate(label)).toBe(label)
}
)
it('passes through strings with an ISO prefix that fail to parse', () => {
expect(formatDate('2025-99-99')).toBe('2025-99-99')
})
})
describe('getSeriesLabel', () => {
it('prefers label, then a positional fallback', () => {
expect(getSeriesLabel({ label: 'Pageviews' }, 0)).toBe('Pageviews')
expect(getSeriesLabel({}, 2)).toBe('Series 3')
})
})
describe('toTableResult', () => {
it('flattens web stats tuples and hides UI-only columns', () => {
const columns = [
'context.columns.breakdown_value',
'context.columns.visitors',
'context.columns.bounce_rate',
'context.columns.ui_fill_fraction',
'context.columns.cross_sell',
]
const rows = [
['/pricing', [1200, 1100], [0.42, 0.5], 1, ''],
[['US', 'Chicago'], [300, null], [0.1, null], 0.25, ''],
]
expect(toTableResult({ kind: 'WebStatsTableQuery', breakdownBy: 'Page' }, rows, columns)).toEqual({
columns: ['Page', 'Visitors', 'Bounce rate'],
results: [
['/pricing', 1200, '42.0%'],
['US, Chicago', 300, '10.0%'],
],
})
})
it('maps web overview items to metric rows', () => {
const items = [
{ key: 'visitors', kind: 'unit', value: 1500, changeFromPreviousPct: 12 },
{ key: 'session duration', kind: 'duration_s', value: 95, changeFromPreviousPct: -3 },
{ key: 'bounce rate', kind: 'percentage', value: 41.25, changeFromPreviousPct: null },
]
expect(toTableResult({ kind: 'WebOverviewQuery' }, items, undefined)).toEqual({
columns: ['Metric', 'Value', 'Change'],
results: [
['Visitors', '1.5K', '+12%'],
['Session duration', '1m 35s', '-3%'],
['Bounce rate', '41.3%', null],
],
})
})
it.each([
['LCP', 'p90', 2873.4, '2873 ms'],
['CLS', 'p75', 0.314, '0.31'],
])('maps %s web vitals bands to path rows, worst first', (metric, percentile, poorValue, poorCell) => {
const results = [
{
good: [{ path: '/', value: 0.01 }],
needs_improvements: [],
poor: [{ path: '/pricing', value: poorValue }],
},
]
expect(
toTableResult({ kind: 'WebVitalsPathBreakdownQuery', metric, percentile }, results, undefined)
).toEqual({
columns: ['Path', `${metric} (${percentile})`, 'Rating'],
results: [
['/pricing', poorCell, 'Poor'],
['/', metric === 'CLS' ? '0.01' : '0 ms', 'Good'],
],
})
})
})
describe('buildProportionBarSeries', () => {
it.each([
[
'one part per row',
[
{ label: 'Chrome', aggregated_value: 3 },
{ label: 'Safari', aggregated_value: 5 },
],
[
{ label: 'Chrome', data: [3] },
{ label: 'Safari', data: [5] },
],
],
[
'no part for the previous period of a compare',
[
{ label: 'Chrome', aggregated_value: 3, compare_label: 'current' },
{ label: 'Chrome', aggregated_value: 2, compare_label: 'previous' },
{ label: 'Safari', aggregated_value: 5, compare_label: 'current' },
],
[
{ label: 'Chrome', data: [3] },
{ label: 'Safari', data: [5] },
],
],
])('draws %s', (_name, results, expected) => {
expect(
buildProportionBarSeries(results, () => 'red').map(({ label, data }) => ({ label, data }))
).toEqual(expected)
})
})
describe('getDisplayType', () => {
it('defaults to ActionsLineGraph when the query or filter is missing', () => {
expect(getDisplayType(undefined)).toBe('ActionsLineGraph')
expect(getDisplayType({ kind: 'TrendsQuery' })).toBe('ActionsLineGraph')
})
it('reads the display type from trendsFilter', () => {
expect(getDisplayType({ kind: 'TrendsQuery', trendsFilter: { display: 'BoldNumber' } })).toBe(
'BoldNumber'
)
})
})
describe('insightQueryProperties', () => {
it.each([
['bare trends without a display', { kind: 'TrendsQuery' }, { queryKind: 'TrendsQuery' }],
[
'trends wrapped in InsightVizNode',
{
kind: 'InsightVizNode',
source: { kind: 'TrendsQuery', trendsFilter: { display: 'BoldNumber' } },
},
{
queryKind: 'InsightVizNode',
querySourceKind: 'TrendsQuery',
display: 'BoldNumber',
},
],
[
'SQL insight with its display on the wrapper node',
{ kind: 'DataVisualizationNode', display: 'ActionsBar', source: { kind: 'HogQLQuery' } },
{
queryKind: 'DataVisualizationNode',
querySourceKind: 'HogQLQuery',
display: 'ActionsBar',
},
],
])('%s', (_, query, expected) => {
expect(insightQueryProperties(query)).toEqual(expected)
})
})
describe('normalizeFunnelSteps', () => {
const steps = [
{ name: '$pageview', order: 0, count: 100 },
{ name: 'sign_up', custom_name: 'Signed up', order: 1, count: 42 },
]
it('returns an empty array for empty results', () => {
expect(normalizeFunnelSteps([])).toEqual([])
})
it('normalizes a flat steps array, preferring custom_name', () => {
expect(normalizeFunnelSteps(steps)).toEqual([
{ name: '$pageview', count: 100, order: 0 },
{ name: 'Signed up', count: 42, order: 1 },
])
})
it('fills missing name, count, and order with defaults', () => {
expect(normalizeFunnelSteps([{}, { count: 7 }])).toEqual([
{ name: 'Step 1', count: 0, order: 0 },
{ name: 'Step 2', count: 7, order: 1 },
])
})
it('uses only the first series of a breakdown funnel', () => {
// Known limitation: remaining breakdown series are dropped rather than
// aggregated, so the chart shows a single breakdown's counts.
const breakdown = [
[
{ name: '$pageview', order: 0, count: 60, breakdown_value: 'Chrome' },
{ name: 'sign_up', order: 1, count: 25, breakdown_value: 'Chrome' },
],
[
{ name: '$pageview', order: 0, count: 40, breakdown_value: 'Firefox' },
{ name: 'sign_up', order: 1, count: 17, breakdown_value: 'Firefox' },
],
]
expect(normalizeFunnelSteps(breakdown)).toEqual([
{ name: '$pageview', count: 60, order: 0 },
{ name: 'sign_up', count: 25, order: 1 },
])
})
})
})
})