Skip to content

: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.

7.7 KB
Raw Blame
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,
        })
    })
})