: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 { DateTime } from 'luxon'
import { ClickHouseTimestamp, ProjectId, RawKafkaEvent } from '~/types'
import { normalizeEvent, parseRawClickHouseEvent } from './event'
describe('normalizeEvent()', () => {
describe('distinctId', () => {
test.each([
{ distinctId: 'abc', expected: 'abc' },
{ distinctId: 123, expected: '123' },
{ distinctId: true, expected: 'true' },
])('$distinctId', ({ distinctId, expected }) => {
const event = { distinct_id: distinctId }
expect(normalizeEvent(event as any).distinct_id).toBe(expected)
})
})
it('adds missing properties', () => {
const event = { distinct_id: 'something' }
expect(normalizeEvent(event as any).properties).toEqual({})
const event2 = { distinct_id: 'something', properties: { a: 1 }, sent_at: '2020-02-23T02:15:00.000Z' }
expect(normalizeEvent(event2 as any).properties).toEqual({ a: 1, $sent_at: '2020-02-23T02:15:00.000Z' })
})
describe('$session_id normalization', () => {
test.each([
{
name: 'lowercases uppercase UUID session_id',
sessionId: 'A1B2C3D4-E5F6-7890-ABCD-EF1234567890',
expected: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
},
{
name: 'lowercases mixed-case UUID session_id',
sessionId: 'a1B2c3D4-e5F6-7890-AbCd-Ef1234567890',
expected: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
},
{
name: 'leaves already-lowercase UUID unchanged',
sessionId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
expected: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
},
{
name: 'leaves non-UUID session_id unchanged',
sessionId: 'NOT-A-UUID',
expected: 'NOT-A-UUID',
},
{
name: 'leaves numeric session_id unchanged',
sessionId: 12345,
expected: 12345,
},
])('$name', ({ sessionId, expected }) => {
const event = { distinct_id: 'user1', properties: { $session_id: sessionId } }
expect(normalizeEvent(event as any).properties!['$session_id']).toBe(expected)
})
it('handles missing $session_id', () => {
const event = { distinct_id: 'user1', properties: {} }
expect(normalizeEvent(event as any).properties!['$session_id']).toBeUndefined()
})
})
describe('$os_name alias', () => {
test.each([
{
name: 'fills a missing $os',
event: 'some_event',
properties: { $os_name: 'Windows' },
expected: 'Windows',
},
{
name: 'leaves an existing $os alone',
event: 'some_event',
properties: { $os: 'Mac OS X', $os_name: 'Windows' },
expected: 'Mac OS X',
},
{
name: 'carries a null $os_name through to $os',
event: 'some_event',
properties: { $os_name: null },
expected: null,
},
{
name: 'skips a $snapshot event, which skips person property lifting too',
event: '$snapshot',
properties: { $os_name: 'Windows' },
expected: undefined,
},
{
name: 'skips a $performance_event, which skips person property lifting too',
event: '$performance_event',
properties: { $os_name: 'Windows' },
expected: undefined,
},
])('$name', ({ event, properties, expected }) => {
const normalized = normalizeEvent({ event, distinct_id: 'user1', properties } as any)
expect(normalized.properties!['$os']).toBe(expected)
})
it('gives the person $os and drops the $os_name alias', () => {
const normalized = normalizeEvent({
event: 'some_event',
distinct_id: 'user1',
properties: { $os_name: 'iOS' },
} as any)
expect(normalized.properties!['$set']).toEqual({ $os: 'iOS' })
expect(normalized.properties!['$set_once']).toEqual({ $initial_os: 'iOS' })
})
it('keeps a server host OS out of $os and $initial_os', () => {
const normalized = normalizeEvent({
event: 'some_event',
distinct_id: 'user1',
properties: { $is_server: true, $os_name: 'Linux' },
} as any)
expect(normalized.properties!['$os']).toBeUndefined()
// The host OS still reaches the person under the $os_name keys: personInitialAndUTMProperties
// skips only $os and $os_version for a server event, and $set_once makes $initial_os_name sticky.
expect(normalized.properties!['$set']).toEqual({ $os_name: 'Linux' })
expect(normalized.properties!['$set_once']).toEqual({ $initial_os_name: 'Linux' })
})
})
it('combines .properties $set and $set_once with top-level $set and $set_once', () => {
const event = {
event: 'some_event',
$set: { key1: 'value1', key2: 'value2' },
$set_once: { key1_once: 'value1', key2_once: 'value2' },
properties: {
distinct_id: 'distinct_id1',
$set: { key2: 'value3', key3: 'value4' },
$set_once: { key2_once: 'value3', key3_once: 'value4' },
},
}
const sanitized = normalizeEvent(event as any)
expect(sanitized.properties!['$set']).toEqual({ key1: 'value1', key2: 'value2', key3: 'value4' })
expect(sanitized.properties!['$set_once']).toEqual({
key1_once: 'value1',
key2_once: 'value2',
key3_once: 'value4',
})
})
})
describe('parseRawClickHouseEvent()', () => {
it('parses a random event', () => {
// @ts-expect-error TODO: Add missing `person_mode` field
const kafkaEvent: RawKafkaEvent = {
event: '$pageview',
properties: JSON.stringify({
$ip: '127.0.0.1',
}),
uuid: 'uuid1',
elements_chain: '',
timestamp: '2020-02-23 02:15:00.00' as ClickHouseTimestamp,
team_id: 2,
project_id: 1 as ProjectId,
distinct_id: 'my_id',
created_at: '2020-02-23 02:15:00.00' as ClickHouseTimestamp,
person_created_at: '2020-02-23 02:10:00.00' as ClickHouseTimestamp,
person_properties: JSON.stringify({ person_prop: 1 }),
group0_properties: '',
group1_properties: JSON.stringify({ a: 1, b: 2 }),
}
expect(parseRawClickHouseEvent(kafkaEvent)).toEqual({
event: '$pageview',
properties: {
$ip: '127.0.0.1',
},
uuid: 'uuid1',
timestamp: DateTime.fromISO('2020-02-23T02:15:00.000Z').toUTC(),
team_id: 2,
project_id: 1,
distinct_id: 'my_id',
created_at: DateTime.fromISO('2020-02-23T02:15:00.000Z').toUTC(),
elements_chain: null,
group0_properties: {},
group1_properties: { a: 1, b: 2 },
group2_properties: {},
group3_properties: {},
group4_properties: {},
person_created_at: DateTime.fromISO('2020-02-23T02:10:00.000Z').toUTC(),
person_properties: { person_prop: 1 },
group0_created_at: null,
group1_created_at: null,
group2_created_at: null,
group3_created_at: null,
group4_created_at: null,
})
})
})