: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 { 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')
}
})
})
})
})