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.

26.9 KB
Raw Blame
import { DateTime } from 'luxon'
import { Message } from 'node-rdkafka'
import { v5 as uuidv5 } from 'uuid'

import { EVENTS_OUTPUT } from '~/common/outputs'
import { castTimestampOrNow } from '~/common/utils/utils'
import { isOkResult } from '~/ingestion/framework/results'
import { createTestEventHeaders } from '~/tests/helpers/event-headers'
import { createTestMessage } from '~/tests/helpers/kafka-message'
import { createTestTeam } from '~/tests/helpers/team'
import { Person, PersonMode, PreIngestionEvent, ProjectId, Team, TimestampFormat } from '~/types'

import { CreateEventStepInput, createCreateEventStep } from './create-event-step'

describe('create-event-step', () => {
    let mockPerson: Person
    let mockPreparedEvent: PreIngestionEvent
    let mockMessage: Message
    let mockTeam: Team

    beforeEach(() => {
        mockMessage = createTestMessage()
        mockTeam = createTestTeam({ id: 1 })
        mockPerson = {
            team_id: 1,
            properties: { email: '[email protected]', name: 'Test User' },
            uuid: 'person-uuid-123',
            created_at: DateTime.fromISO('2023-01-01T00:00:00.000Z'),
            force_upgrade: false,
        }

        mockPreparedEvent = {
            eventUuid: 'event-uuid-456',
            event: '$pageview',
            teamId: 1,
            projectId: 1 as ProjectId,
            distinctId: 'distinct-id-789',
            properties: { $current_url: 'https://example.com' },
            timestamp: castTimestampOrNow('2023-01-01T00:00:00.000Z', TimestampFormat.ISO),
        }
    })

    describe('createCreateEventStep', () => {
        it('should create event with processPerson=true', async () => {
            const step = createCreateEventStep(EVENTS_OUTPUT)
            const input = {
                team: mockTeam,
                person: mockPerson,
                preparedEvent: mockPreparedEvent,
                processPerson: true,
                historicalMigration: false,
                headers: createTestEventHeaders(),
                message: mockMessage,
                lastStep: 'prepareEventStep',
            }

            const result = await step(input)

            expect(isOkResult(result)).toBe(true)
            if (isOkResult(result)) {
                const value = result.value
                expect(value.eventsToEmit).toHaveLength(1)
                const event = value.eventsToEmit[0].event
                expect(value.eventsToEmit[0].output).toBe(EVENTS_OUTPUT)
                expect(event.uuid).toBe('event-uuid-456')
                expect(event.event).toBe('$pageview')
                expect(event.team_id).toBe(1)
                expect(event.distinct_id).toBe('distinct-id-789')
                expect(event.person_id).toBe('person-uuid-123')
                expect(event.person_mode).toBe('full')
                expect(event.person_properties).toEqual({
                    email: '[email protected]',
                    name: 'Test User',
                })
                expect(value.teamId).toBe(1)
            }
            expect(result.sideEffects).toHaveLength(0)
        })

        it('should create event with processPerson=false', async () => {
            const step = createCreateEventStep(EVENTS_OUTPUT)
            const input = {
                team: mockTeam,
                person: mockPerson,
                preparedEvent: mockPreparedEvent,
                processPerson: false,
                historicalMigration: false,
                headers: createTestEventHeaders(),
                message: mockMessage,
                lastStep: 'prepareEventStep',
            }

            const result = await step(input)

            expect(isOkResult(result)).toBe(true)
            if (isOkResult(result)) {
                const value = result.value
                expect(value.eventsToEmit).toHaveLength(1)
                const event = value.eventsToEmit[0].event
                expect(event.person_mode).toBe('propertyless')
                expect(event.person_properties).toEqual({})
            }
            expect(result.sideEffects).toHaveLength(0)
        })

        it('should handle person with force_upgrade=true', async () => {
            const personWithForceUpgrade: Person = {
                ...mockPerson,
                force_upgrade: true,
            }

            const step = createCreateEventStep(EVENTS_OUTPUT)
            const input = {
                team: mockTeam,
                person: personWithForceUpgrade,
                preparedEvent: mockPreparedEvent,
                processPerson: true,
                historicalMigration: false,
                headers: createTestEventHeaders(),
                message: mockMessage,
                lastStep: 'prepareEventStep',
            }

            const result = await step(input)

            expect(isOkResult(result)).toBe(true)
            if (isOkResult(result)) {
                const event = result.value.eventsToEmit[0].event
                expect(event.person_mode).toBe('force_upgrade')
            }
        })

        it('should include $set properties in person_properties when processPerson=true', async () => {
            const eventWithSetProperties: PreIngestionEvent = {
                ...mockPreparedEvent,
                properties: {
                    ...mockPreparedEvent.properties,
                    $set: { new_property: 'new_value' },
                },
            }

            const step = createCreateEventStep(EVENTS_OUTPUT)
            const input = {
                team: mockTeam,
                person: mockPerson,
                preparedEvent: eventWithSetProperties,
                processPerson: true,
                historicalMigration: false,
                headers: createTestEventHeaders(),
                message: mockMessage,
                lastStep: 'prepareEventStep',
            }

            const result = await step(input)

            expect(isOkResult(result)).toBe(true)
            if (isOkResult(result)) {
                const event = result.value.eventsToEmit[0].event
                expect(event.person_properties).toEqual({
                    email: '[email protected]',
                    name: 'Test User',
                    new_property: 'new_value',
                })
            }
        })

        it('should preserve event properties as native object', async () => {
            const step = createCreateEventStep(EVENTS_OUTPUT)
            const input = {
                team: mockTeam,
                person: mockPerson,
                preparedEvent: mockPreparedEvent,
                processPerson: true,
                historicalMigration: false,
                headers: createTestEventHeaders(),
                message: mockMessage,
                lastStep: 'prepareEventStep',
            }

            const result = await step(input)

            expect(isOkResult(result)).toBe(true)
            if (isOkResult(result)) {
                const event = result.value.eventsToEmit[0].event
                expect(typeof event.properties).toBe('object')
                expect(event.properties).toEqual({
                    $current_url: 'https://example.com',
                })
            }
        })

        it('should handle events with elements_chain', async () => {
            const eventWithElements: PreIngestionEvent = {
                ...mockPreparedEvent,
                properties: {
                    ...mockPreparedEvent.properties,
                    $elements_chain: 'button:0;div:1;body:2',
                },
            }

            const step = createCreateEventStep(EVENTS_OUTPUT)
            const input = {
                team: mockTeam,
                person: mockPerson,
                preparedEvent: eventWithElements,
                processPerson: true,
                historicalMigration: false,
                headers: createTestEventHeaders(),
                message: mockMessage,
                lastStep: 'prepareEventStep',
            }

            const result = await step(input)

            expect(isOkResult(result)).toBe(true)
            if (isOkResult(result)) {
                const event = result.value.eventsToEmit[0].event
                expect(event.elements_chain).toBe('button:0;div:1;body:2')
            }
        })

        it('should work with generic input types that have required properties', async () => {
            interface CustomInput extends CreateEventStepInput {
                customProperty: string
                lastStep: string
            }

            const step = createCreateEventStep<typeof EVENTS_OUTPUT, CustomInput>(EVENTS_OUTPUT)
            const input: CustomInput = {
                team: mockTeam,
                person: mockPerson,
                preparedEvent: mockPreparedEvent,
                processPerson: true,
                historicalMigration: false,
                headers: createTestEventHeaders(),
                message: mockMessage,
                customProperty: 'test',
                lastStep: 'prepareEventStep',
            }

            const result = await step(input)

            expect(isOkResult(result)).toBe(true)
            if (isOkResult(result)) {
                expect(result.value.eventsToEmit).toHaveLength(1)
            }
        })

        it('should set correct timestamps', async () => {
            const step = createCreateEventStep(EVENTS_OUTPUT)
            const input = {
                team: mockTeam,
                person: mockPerson,
                preparedEvent: mockPreparedEvent,
                processPerson: true,
                historicalMigration: false,
                headers: createTestEventHeaders(),
                message: mockMessage,
                lastStep: 'prepareEventStep',
            }

            const result = await step(input)

            expect(isOkResult(result)).toBe(true)
            if (isOkResult(result)) {
                const event = result.value.eventsToEmit[0].event
                expect(event.timestamp).toBeTruthy()
                expect(event.created_at).toBeTruthy()
                expect(event.person_created_at).toBeTruthy()
            }
        })

        it('should handle different event types', async () => {
            const events = ['$pageview', '$identify', '$set', 'custom_event']

            for (const eventName of events) {
                const eventWithType: PreIngestionEvent = {
                    ...mockPreparedEvent,
                    event: eventName,
                }

                const step = createCreateEventStep(EVENTS_OUTPUT)
                const input = {
                    team: mockTeam,
                    person: mockPerson,
                    preparedEvent: eventWithType,
                    processPerson: true,
                    historicalMigration: false,
                    headers: createTestEventHeaders(),
                    message: mockMessage,
                    lastStep: 'prepareEventStep',
                }

                const result = await step(input)

                expect(isOkResult(result)).toBe(true)
                if (isOkResult(result)) {
                    const event = result.value.eventsToEmit[0].event
                    expect(event.event).toBe(eventName)
                }
            }
        })

        describe('$experiment_exposure duplication', () => {
            it('duplicates multivariate $feature_flag_called events for allowlisted teams with a deterministic uuid', async () => {
                const step = createCreateEventStep(EVENTS_OUTPUT, '2')
                const input = {
                    team: mockTeam,
                    person: mockPerson,
                    preparedEvent: {
                        ...mockPreparedEvent,
                        teamId: 2,
                        projectId: 2 as ProjectId,
                        event: '$feature_flag_called',
                        properties: {
                            $feature_flag: 'checkout-experiment',
                            $feature_flag_response: 'test',
                            unchanged: 'value',
                        },
                    },
                    processPerson: true,
                    historicalMigration: false,
                    headers: createTestEventHeaders(),
                    message: mockMessage,
                }
                const result = await step(input)
                const rerun = await step(input)

                expect(isOkResult(result)).toBe(true)
                expect(isOkResult(rerun)).toBe(true)
                if (isOkResult(result) && isOkResult(rerun)) {
                    expect(result.value.eventsToEmit).toHaveLength(2)
                    const [flagCalled, exposure] = result.value.eventsToEmit
                    expect(exposure.output).toBe(EVENTS_OUTPUT)
                    expect(exposure.event.uuid).not.toBe(flagCalled.event.uuid)
                    expect(exposure.event).toEqual({
                        ...flagCalled.event,
                        event: '$experiment_exposure',
                        uuid: exposure.event.uuid,
                    })
                    // A redelivered message must reproduce the same exposure row for
                    // ClickHouse's ReplacingMergeTree to collapse it.
                    expect(rerun.value.eventsToEmit[1].event.uuid).toBe(exposure.event.uuid)
                }
            })

            it.each([
                ['a team outside the allowlist', 1, '$feature_flag_called', 'test'],
                ['a boolean response', 2, '$feature_flag_called', true],
                ['a stringified boolean response', 2, '$feature_flag_called', 'true'],
                ['an empty response', 2, '$feature_flag_called', ''],
                ['a missing response', 2, '$feature_flag_called', undefined],
                ['a different event', 2, '$pageview', 'test'],
                ['a direct $experiment_exposure', 2, '$experiment_exposure', 'test'],
            ])('does not duplicate %s', async (_, teamId, event, response) => {
                const step = createCreateEventStep(EVENTS_OUTPUT, '2')
                const result = await step({
                    team: mockTeam,
                    person: mockPerson,
                    preparedEvent: {
                        ...mockPreparedEvent,
                        teamId,
                        projectId: teamId as ProjectId,
                        event,
                        properties: { $feature_flag_response: response },
                    },
                    processPerson: true,
                    historicalMigration: false,
                    headers: createTestEventHeaders(),
                    message: mockMessage,
                })

                expect(isOkResult(result)).toBe(true)
                if (isOkResult(result)) {
                    expect(result.value.eventsToEmit).toHaveLength(1)
                }
            })

            it.each([
                ['the number 2', 2],
                ['the string "2"', '2'],
            ])(
                'passes a $feature_flag_called through unchanged when $feature_flag_config_version is %s',
                async (_, configVersion) => {
                    const properties = {
                        $feature_flag: 'checkout-experiment',
                        $feature_flag_response: 'test',
                        $feature_flag_config_version: configVersion,
                    }
                    const step = createCreateEventStep(EVENTS_OUTPUT, '*')
                    const result = await step({
                        team: mockTeam,
                        person: mockPerson,
                        preparedEvent: {
                            ...mockPreparedEvent,
                            teamId: 2,
                            projectId: 2 as ProjectId,
                            event: '$feature_flag_called',
                            properties,
                        },
                        processPerson: true,
                        historicalMigration: false,
                        headers: createTestEventHeaders(),
                        message: mockMessage,
                    })

                    expect(isOkResult(result)).toBe(true)
                    if (isOkResult(result)) {
                        expect(result.value.eventsToEmit).toHaveLength(1)
                        const [flagCalled] = result.value.eventsToEmit
                        expect(flagCalled.output).toBe(EVENTS_OUTPUT)
                        expect(flagCalled.event.event).toBe('$feature_flag_called')
                        expect(flagCalled.event.uuid).toBe('event-uuid-456')
                        expect(flagCalled.event.properties).toEqual(properties)
                    }
                }
            )

            it.each([
                ['1', 1],
                ['missing', undefined],
                ['the string "1"', '1'],
            ])('duplicates as before when $feature_flag_config_version is %s', async (_, configVersion) => {
                const step = createCreateEventStep(EVENTS_OUTPUT, '2')
                const result = await step({
                    team: mockTeam,
                    person: mockPerson,
                    preparedEvent: {
                        ...mockPreparedEvent,
                        teamId: 2,
                        projectId: 2 as ProjectId,
                        event: '$feature_flag_called',
                        properties: { $feature_flag_response: 'test', $feature_flag_config_version: configVersion },
                    },
                    processPerson: true,
                    historicalMigration: false,
                    headers: createTestEventHeaders(),
                    message: mockMessage,
                })

                expect(isOkResult(result)).toBe(true)
                if (isOkResult(result)) {
                    expect(result.value.eventsToEmit).toHaveLength(2)
                    const exposure = result.value.eventsToEmit[1].event
                    expect(exposure.event).toBe('$experiment_exposure')
                    // Pins the derived uuid so a redelivered message keeps collapsing in ClickHouse.
                    expect(exposure.uuid).toBe(uuidv5('event-uuid-456', '1b7c9119-5953-4668-97b7-ab0ef8a6bb48'))
                }
            })

            it('does not duplicate when no teams are configured', async () => {
                const step = createCreateEventStep(EVENTS_OUTPUT)
                const result = await step({
                    team: mockTeam,
                    person: mockPerson,
                    preparedEvent: {
                        ...mockPreparedEvent,
                        teamId: 2,
                        projectId: 2 as ProjectId,
                        event: '$feature_flag_called',
                        properties: { $feature_flag_response: 'test' },
                    },
                    processPerson: true,
                    historicalMigration: false,
                    headers: createTestEventHeaders(),
                    message: mockMessage,
                })

                expect(isOkResult(result)).toBe(true)
                if (isOkResult(result)) {
                    expect(result.value.eventsToEmit).toHaveLength(1)
                }
            })
        })

        describe('historicalMigration flag', () => {
            it('should include historical_migration in event when historicalMigration=true', async () => {
                const step = createCreateEventStep(EVENTS_OUTPUT)
                const input = {
                    team: mockTeam,
                    person: mockPerson,
                    preparedEvent: mockPreparedEvent,
                    processPerson: true,
                    historicalMigration: true,
                    headers: createTestEventHeaders(),
                    message: mockMessage,
                    lastStep: 'prepareEventStep',
                }

                const result = await step(input)

                expect(isOkResult(result)).toBe(true)
                if (isOkResult(result)) {
                    const event = result.value.eventsToEmit[0].event
                    expect(event.historical_migration).toBe(true)
                }
            })

            it('should not include historical_migration in event when historicalMigration=false', async () => {
                const step = createCreateEventStep(EVENTS_OUTPUT)
                const input = {
                    team: mockTeam,
                    person: mockPerson,
                    preparedEvent: mockPreparedEvent,
                    processPerson: true,
                    historicalMigration: false,
                    headers: createTestEventHeaders(),
                    message: mockMessage,
                    lastStep: 'prepareEventStep',
                }

                const result = await step(input)

                expect(isOkResult(result)).toBe(true)
                if (isOkResult(result)) {
                    const event = result.value.eventsToEmit[0].event
                    expect(event.historical_migration).toBeUndefined()
                }
            })
        })

        describe('person modes', () => {
            it.each([
                ['full', { processPerson: true, force_upgrade: false }, 'full' as PersonMode],
                ['propertyless', { processPerson: false, force_upgrade: false }, 'propertyless' as PersonMode],
                ['force_upgrade', { processPerson: true, force_upgrade: true }, 'force_upgrade' as PersonMode],
            ])('should set person_mode=%s when processPerson=%p and force_upgrade=%p', async (_, config, expected) => {
                const person: Person = {
                    ...mockPerson,
                    force_upgrade: config.force_upgrade,
                }

                const step = createCreateEventStep(EVENTS_OUTPUT)
                const input = {
                    team: mockTeam,
                    person,
                    preparedEvent: mockPreparedEvent,
                    processPerson: config.processPerson,
                    historicalMigration: false,
                    headers: createTestEventHeaders(),
                    message: mockMessage,
                    lastStep: 'prepareEventStep',
                }

                const result = await step(input)

                expect(isOkResult(result)).toBe(true)
                if (isOkResult(result)) {
                    const event = result.value.eventsToEmit[0].event
                    expect(event.person_mode).toBe(expected)
                }
            })
        })

        describe('optional person (undefined)', () => {
            it('should generate deterministic person_id from distinct_id when person is undefined', async () => {
                const step = createCreateEventStep(EVENTS_OUTPUT)
                const input = {
                    team: mockTeam,
                    person: undefined,
                    preparedEvent: mockPreparedEvent,
                    processPerson: true,
                    historicalMigration: false,
                    headers: createTestEventHeaders(),
                    message: mockMessage,
                    lastStep: 'prepareEventStep',
                }

                const result = await step(input)

                expect(isOkResult(result)).toBe(true)
                if (isOkResult(result)) {
                    const event = result.value.eventsToEmit[0].event
                    expect(event.person_id).toBeDefined()
                    expect(event.person_id).toMatch(/^[0-9a-f-]{36}$/)
                }
            })

            it('should return empty person_properties when person is undefined', async () => {
                const step = createCreateEventStep(EVENTS_OUTPUT)
                const input = {
                    team: mockTeam,
                    person: undefined,
                    preparedEvent: mockPreparedEvent,
                    processPerson: true,
                    historicalMigration: false,
                    headers: createTestEventHeaders(),
                    message: mockMessage,
                    lastStep: 'prepareEventStep',
                }

                const result = await step(input)

                expect(isOkResult(result)).toBe(true)
                if (isOkResult(result)) {
                    const event = result.value.eventsToEmit[0].event
                    expect(event.person_properties).toEqual({})
                }
            })

            it('should set person_created_at to null when person is undefined', async () => {
                const step = createCreateEventStep(EVENTS_OUTPUT)
                const input = {
                    team: mockTeam,
                    person: undefined,
                    preparedEvent: mockPreparedEvent,
                    processPerson: true,
                    historicalMigration: false,
                    headers: createTestEventHeaders(),
                    message: mockMessage,
                    lastStep: 'prepareEventStep',
                }

                const result = await step(input)

                expect(isOkResult(result)).toBe(true)
                if (isOkResult(result)) {
                    const event = result.value.eventsToEmit[0].event
                    expect(event.person_created_at).toBeNull()
                }
            })

            it('should set person_mode to full when person is undefined and processPerson=true', async () => {
                const step = createCreateEventStep(EVENTS_OUTPUT)
                const input = {
                    team: mockTeam,
                    person: undefined,
                    preparedEvent: mockPreparedEvent,
                    processPerson: true,
                    historicalMigration: false,
                    headers: createTestEventHeaders(),
                    message: mockMessage,
                    lastStep: 'prepareEventStep',
                }

                const result = await step(input)

                expect(isOkResult(result)).toBe(true)
                if (isOkResult(result)) {
                    const event = result.value.eventsToEmit[0].event
                    expect(event.person_mode).toBe('full')
                }
            })

            it('should set person_mode to propertyless when person is undefined and processPerson=false', async () => {
                const step = createCreateEventStep(EVENTS_OUTPUT)
                const input = {
                    team: mockTeam,
                    person: undefined,
                    preparedEvent: mockPreparedEvent,
                    processPerson: false,
                    historicalMigration: false,
                    headers: createTestEventHeaders(),
                    message: mockMessage,
                    lastStep: 'prepareEventStep',
                }

                const result = await step(input)

                expect(isOkResult(result)).toBe(true)
                if (isOkResult(result)) {
                    const event = result.value.eventsToEmit[0].event
                    expect(event.person_mode).toBe('propertyless')
                }
            })
        })
    })
})