: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 { FixtureHogFlowBuilder } from '~/cdp/_tests/builders/hogflow.builder'
import { HOG_FILTERS_EXAMPLES } from '~/cdp/_tests/examples'
import { createExampleHogFlowInvocation } from '~/cdp/_tests/fixtures-hogflows'
import { HogFlow, HogFlowAction } from '~/cdp/schema/hogflow'
import { CohortMembershipRepository, StoredCohortMembership } from '~/cdp/services/cohorts/cohort-membership-repository'
import { CyclotronJobInvocationHogFlow } from '~/cdp/types'
import { createInvocationResult } from '~/cdp/utils/invocation-utils'
import { findActionById, findActionByType } from '../hogflow-utils'
import {
ConditionalBranchHandler,
checkConditions,
counterHogflowRekeyWake,
counterHogflowWaitAdvancedAtMaxWait,
counterHogflowWaitPersonRefreshFailed,
} from './conditional_branch'
const lateAdvanceCount = async (): Promise<number> =>
(await counterHogflowWaitAdvancedAtMaxWait.get()).values[0]?.value ?? 0
const lateAdvanceLabels = async (): Promise<Record<string, string | number> | undefined> =>
(await counterHogflowWaitAdvancedAtMaxWait.get()).values[0]?.labels
const personRefreshFailedCount = async (): Promise<number> =>
(await counterHogflowWaitPersonRefreshFailed.get()).values[0]?.value ?? 0
const rekeyWakeCount = async (outcome: 'advanced' | 'reparked'): Promise<number> =>
(await counterHogflowRekeyWake.get()).values.find((v) => v.labels.outcome === outcome)?.value ?? 0
describe('action.conditional_branch', () => {
let invocation: CyclotronJobInvocationHogFlow
let action: Extract<HogFlowAction, { type: 'conditional_branch' }>
let hogFlow: HogFlow
beforeEach(() => {
const fixedTime = DateTime.fromObject({ year: 2025, month: 1, day: 1 }, { zone: 'UTC' })
jest.spyOn(Date, 'now').mockReturnValue(fixedTime.toMillis())
hogFlow = new FixtureHogFlowBuilder()
.withWorkflow({
actions: {
conditional_branch: {
type: 'conditional_branch',
config: {
conditions: [
{
filters: HOG_FILTERS_EXAMPLES.pageview_or_autocapture_filter.filters, // Match for pageviews
},
], // Filled by tests
},
},
condition_1: {
type: 'delay',
config: {
delay_duration: '2h',
},
},
condition_2: {
type: 'delay',
config: {
delay_duration: '2h',
},
},
},
edges: [
{
from: 'conditional_branch',
to: 'condition_2',
type: 'branch',
index: 1,
},
{
from: 'conditional_branch',
to: 'condition_1',
type: 'branch',
index: 0,
},
],
})
.build()
action = findActionByType(hogFlow, 'conditional_branch')!
invocation = createExampleHogFlowInvocation(hogFlow)
invocation.state.currentAction = {
id: action.id,
startedAtTimestamp: DateTime.utc().toMillis(),
}
})
describe('no matching events', () => {
it('should return finished if no matches', async () => {
invocation.state.event!.event = 'no-match'
const result = await checkConditions(invocation, action)
expect(result).toEqual({})
})
// A wait arrives here already normalised into a conditional_branch, so its ceiling comes in
// as `repark` rather than off the action. A branch without one never parks.
describe('wait logic', () => {
const repark = (maxWaitDuration: string) => ({ maxWaitDuration })
it('should park for the whole ceiling', async () => {
const result = await checkConditions(invocation, action, undefined, repark('2h'))
expect(result).toEqual({ scheduledAt: DateTime.utc().plus({ hours: 2 }) })
})
it('should park a short ceiling for its own duration', async () => {
const result = await checkConditions(invocation, action, undefined, repark('5m'))
expect(result).toEqual({ scheduledAt: DateTime.utc().plus({ minutes: 5 }) })
})
it('should not schedule at all without a ceiling', async () => {
const result = await checkConditions(invocation, action)
expect(result).toEqual({})
})
it('should throw error if action started at timestamp is invalid', async () => {
invocation.state.currentAction = undefined
await expect(async () =>
checkConditions(invocation, action, undefined, repark('300s'))
).rejects.toThrow("'startedAtTimestamp' is not set or is invalid")
})
})
})
describe('matching events', () => {
beforeEach(() => {
invocation = createExampleHogFlowInvocation(hogFlow, {
// These values match the pageview_or_autocapture_filter
event: {
event: '$pageview',
properties: {
$current_url: 'https://posthog.com',
},
} as any,
})
})
it('should match condition and go to action', async () => {
const result = await checkConditions(invocation, action)
expect(result).toEqual({
nextAction: findActionById(invocation.hogFlow, 'condition_1'),
})
})
it('should ignore conditions that do not match', async () => {
action.config.conditions = [
{
filters: HOG_FILTERS_EXAMPLES.elements_text_filter.filters, // No match
},
{
filters: HOG_FILTERS_EXAMPLES.pageview_or_autocapture_filter.filters, // No match
},
]
const result = await checkConditions(invocation, action)
expect(result).toEqual({
nextAction: findActionById(invocation.hogFlow, 'condition_2'),
})
})
it('should execute the first matching branch when multiple conditions match', async () => {
action.config.conditions = [
{
filters: HOG_FILTERS_EXAMPLES.pageview_or_autocapture_filter.filters, // Match
},
{
filters: HOG_FILTERS_EXAMPLES.no_filters.filters, // Also matches (always true)
},
]
const result = await checkConditions(invocation, action)
expect(result).toEqual({
nextAction: findActionById(invocation.hogFlow, 'condition_1'),
})
})
})
describe('cohort membership conditions', () => {
const COHORT_ID = 42
class FakeCohortMembershipRepository implements CohortMembershipRepository {
public calls: { teamId: number; personUuid: string }[] = []
constructor(
private memberCohortIds: number[],
private error?: Error
) {}
getMemberCohortIds(teamId: number, personUuid: string): Promise<number[]> {
this.calls.push({ teamId, personUuid })
if (this.error) {
return Promise.reject(this.error)
}
return Promise.resolve(this.memberCohortIds)
}
getCohortMembership(): Promise<StoredCohortMembership | null> {
return Promise.reject(new Error('not used by branches'))
}
}
// Same shape the Python serializer emits: the authored properties plus compiled bytecode.
// Keeping the properties key matters: filters holding ONLY bytecode short-circuit to an
// unconditional match in filterFunctionInstrumented and never execute the VM.
const cohortConditionFilters = (fn: 'inCohort' | 'notInCohort'): Record<string, any> => ({
bytecode: ['_H', 1, 33, COHORT_ID, 32, 'cohort_ids', 1, 1, 2, fn, 2],
properties: [{ key: 'id', type: 'cohort', value: COHORT_ID }],
})
const executeWithRepository = async (
repository: CohortMembershipRepository,
fn: 'inCohort' | 'notInCohort'
): Promise<HogFlowAction | undefined> => {
action.config.conditions = [
{ filters: cohortConditionFilters(fn) },
{ filters: HOG_FILTERS_EXAMPLES.no_filters.filters }, // always-true fallthrough
]
const handler = new ConditionalBranchHandler(repository)
const result = await handler.execute({
invocation,
action,
result: createInvocationResult(invocation),
})
return result.nextAction
}
it.each([
['inCohort', true, 'condition_1'],
['inCohort', false, 'condition_2'],
['notInCohort', false, 'condition_1'],
['notInCohort', true, 'condition_2'],
] as const)('routes %s with membership=%s to %s', async (fn, isMember, expectedActionId) => {
const repository = new FakeCohortMembershipRepository(isMember ? [7, COHORT_ID] : [7])
const nextAction = await executeWithRepository(repository, fn)
expect(nextAction).toEqual(findActionById(invocation.hogFlow, expectedActionId))
expect(repository.calls).toEqual([
{ teamId: invocation.hogFlow.team_id, personUuid: invocation.person!.id },
])
})
it('does not query membership when an earlier non-cohort condition matches', async () => {
// The lookup is lazy: a run that never reaches the cohort condition must not depend on
// the behavioral cohorts DB, even when that DB is down.
const repository = new FakeCohortMembershipRepository([], new Error('cohorts DB down'))
action.config.conditions = [
{ filters: HOG_FILTERS_EXAMPLES.no_filters.filters }, // matches first
{ filters: cohortConditionFilters('inCohort') },
]
const handler = new ConditionalBranchHandler(repository)
const result = await handler.execute({
invocation,
action,
result: createInvocationResult(invocation),
})
expect(result.nextAction).toEqual(findActionById(invocation.hogFlow, 'condition_1'))
expect(repository.calls).toEqual([])
})
it('does not query membership for a condition that merely mentions "inCohort" as a string', async () => {
const repository = new FakeCohortMembershipRepository([COHORT_ID])
action.config.conditions = [
{
// properties.foo == 'inCohort' — the name appears as a string constant, not a call
filters: {
bytecode: ['_H', 1, 32, 'inCohort', 32, 'foo', 32, 'properties', 1, 2, 11],
properties: [{ key: 'foo', type: 'event', value: 'inCohort', operator: 'exact' }],
},
},
{ filters: HOG_FILTERS_EXAMPLES.no_filters.filters },
]
const handler = new ConditionalBranchHandler(repository)
const result = await handler.execute({
invocation,
action,
result: createInvocationResult(invocation),
})
expect(result.nextAction).toEqual(findActionById(invocation.hogFlow, 'condition_2'))
expect(repository.calls).toEqual([])
})
it('treats a person-less invocation as a non-member without querying', async () => {
const repository = new FakeCohortMembershipRepository([COHORT_ID])
invocation.person = undefined
invocation.state.personId = undefined
const nextAction = await executeWithRepository(repository, 'inCohort')
expect(nextAction).toEqual(findActionById(invocation.hogFlow, 'condition_2'))
expect(repository.calls).toEqual([])
})
it.each([
[0, 10],
[1, 60],
])('retries a failed lookup after %s earlier failures in %ss instead of routing', async (earlier, delay) => {
const repository = new FakeCohortMembershipRepository([], new Error('lookup timed out'))
invocation.state.currentAction!.cohortLookupAttempts = earlier || undefined
action.config.conditions = [{ filters: cohortConditionFilters('inCohort') }]
const result = await new ConditionalBranchHandler(repository).execute({
invocation,
action,
result: createInvocationResult(invocation),
})
expect(result.nextAction).toBeUndefined()
expect(result.scheduledAt).toEqual(DateTime.now().plus({ seconds: delay }))
expect(invocation.state.currentAction!.cohortLookupAttempts).toBe(earlier + 1)
expect(invocation.state.currentAction!.cohortLookupFailed).toBeUndefined()
})
it('marks the step failed and throws once every lookup attempt failed', async () => {
const repository = new FakeCohortMembershipRepository([], new Error('lookup timed out'))
invocation.state.currentAction!.cohortLookupAttempts = 2
await expect(executeWithRepository(repository, 'inCohort')).rejects.toThrow('lookup timed out')
expect(invocation.state.currentAction!.cohortLookupFailed).toBe(true)
})
})
describe('wait_until_condition eventMatched short-circuit', () => {
let waitInvocation: CyclotronJobInvocationHogFlow
let waitAction: Extract<HogFlowAction, { type: 'wait_until_condition' }>
let handler: ConditionalBranchHandler
beforeEach(() => {
const waitFlow = new FixtureHogFlowBuilder()
.withWorkflow({
actions: {
wait_until_condition: {
type: 'wait_until_condition',
config: {
condition: {
filters: HOG_FILTERS_EXAMPLES.elements_text_filter.filters, // no match
},
max_wait_duration: '10m',
},
},
matched_target: {
type: 'delay',
config: { delay_duration: '2h' },
},
},
edges: [
{
from: 'wait_until_condition',
to: 'matched_target',
type: 'branch',
index: 0,
},
// The timeout edge, so a wait that reaches its ceiling unmatched has somewhere to go.
{
from: 'wait_until_condition',
to: 'matched_target',
type: 'continue',
},
],
})
.build()
waitAction = findActionByType(waitFlow, 'wait_until_condition')!
waitInvocation = createExampleHogFlowInvocation(waitFlow)
waitInvocation.state.currentAction = {
id: waitAction.id,
startedAtTimestamp: DateTime.utc().toMillis(),
}
const stubCohortMembershipRepository: CohortMembershipRepository = {
getMemberCohortIds: () => Promise.resolve([]),
getCohortMembership: () => Promise.resolve(null),
}
handler = new ConditionalBranchHandler(stubCohortMembershipRepository)
counterHogflowWaitAdvancedAtMaxWait.reset()
counterHogflowRekeyWake.reset()
counterHogflowWaitPersonRefreshFailed.reset()
})
it('evaluates a first wait against the refreshed person, on the invocation and the result alike', async () => {
// The result carries a shallow clone, so both have to land on the fresh person: whichever
// one a later reader picks up must not still hold the person the dequeue cached.
const freshPerson = { id: 'p1', properties: { email: '[email protected]' } }
waitInvocation.refreshPerson = jest.fn().mockResolvedValue({
person: freshPerson,
filterGlobals: { ...waitInvocation.filterGlobals, person: freshPerson },
})
const result = createInvocationResult<CyclotronJobInvocationHogFlow>(waitInvocation)
await handler.execute({ invocation: waitInvocation, action: waitAction, result })
expect(waitInvocation.refreshPerson).toHaveBeenCalledTimes(1)
expect(waitInvocation.filterGlobals.person?.properties).toEqual(freshPerson.properties)
expect(result.invocation.filterGlobals.person?.properties).toEqual(freshPerson.properties)
expect(result.invocation.person).toEqual(freshPerson)
})
it('keeps the person it already had when the refresh comes back empty', async () => {
// The refresh adds freshness; it must not drop a person because one lookup found nothing.
const before = waitInvocation.person
waitInvocation.refreshPerson = jest
.fn()
.mockResolvedValue({ person: undefined, filterGlobals: { person: null } as any })
const result = createInvocationResult<CyclotronJobInvocationHogFlow>(waitInvocation)
await handler.execute({ invocation: waitInvocation, action: waitAction, result })
expect(waitInvocation.person).toEqual(before)
expect(waitInvocation.filterGlobals.person).not.toBeNull()
})
it('keeps the person it already had when the refresh fails, and stays parked', async () => {
// A failed read must not reach the executor's error handling: that follows the continue
// edge, which for a wait is the timeout edge, so the run would leave the wait early.
const before = waitInvocation.person
waitInvocation.refreshPerson = jest.fn().mockRejectedValue(new Error('person read failed'))
const result = createInvocationResult<CyclotronJobInvocationHogFlow>(waitInvocation)
const handlerResult = await handler.execute({
invocation: waitInvocation,
action: waitAction,
result,
})
expect(handlerResult.scheduledAt).toEqual(DateTime.utc().plus({ minutes: 10 }))
expect(handlerResult.nextAction).toBeUndefined()
expect(waitInvocation.person).toEqual(before)
expect(await personRefreshFailedCount()).toBe(1)
})
it('advances to the matched branch and clears eventMatched', async () => {
waitInvocation.state.currentAction!.eventMatched = true
waitInvocation.state.currentAction!.eventMatchedEvent = 'subscription created'
waitInvocation.state.currentAction!.eventMatchedEventUuid = 'evt-uuid'
const result = await handler.execute({
invocation: waitInvocation,
action: waitAction,
result: createInvocationResult(waitInvocation),
})
expect(result.nextAction).toEqual(findActionById(waitInvocation.hogFlow, 'matched_target'))
expect(result.result).toEqual({ eventMatched: true })
// All wake markers are cleared so a later timeout fire isn't misread as an event wake.
expect(waitInvocation.state.currentAction!.eventMatched).toBe(false)
expect(waitInvocation.state.currentAction!.eventMatchedEvent).toBeUndefined()
expect(waitInvocation.state.currentAction!.eventMatchedEventUuid).toBeUndefined()
})
it('falls through to condition evaluation when eventMatched is not set', async () => {
const result = await handler.execute({
invocation: waitInvocation,
action: waitAction,
result: createInvocationResult(waitInvocation),
})
// Condition does not match, so the step reschedules itself rather than advancing.
expect(result.scheduledAt).toBeDefined()
expect(result.nextAction).toBeUndefined()
})
it('does not fire immediately when the condition has no properties (always-true bytecode)', async () => {
// An empty property condition compiles to always-true bytecode. It must not match on
// entry and advance the wait; the step should park until an event wakes it or it times out.
waitAction.config.condition = { filters: HOG_FILTERS_EXAMPLES.no_filters.filters }
const result = await handler.execute({
invocation: waitInvocation,
action: waitAction,
result: createInvocationResult(waitInvocation),
})
expect(result.scheduledAt).toBeDefined()
expect(result.nextAction).toBeUndefined()
})
it('parks a wait for its whole max_wait_duration, with no periodic re-check', async () => {
// The matcher is the only thing that wakes a wait, so it parks once rather than on a timer.
waitAction.config.max_wait_duration = '4h'
const result = await handler.execute({
invocation: waitInvocation,
action: waitAction,
result: createInvocationResult(waitInvocation),
})
expect(result.scheduledAt).toEqual(DateTime.utc().plus({ hours: 4 }))
})
it('parks a short wait for its own duration too', async () => {
waitAction.config.max_wait_duration = '30m'
const result = await handler.execute({
invocation: waitInvocation,
action: waitAction,
result: createInvocationResult(waitInvocation),
})
expect(result.scheduledAt).toEqual(DateTime.utc().plus({ minutes: 30 }))
})
it('counts a wait whose condition only matched once max_wait_duration elapsed', async () => {
// Nothing re-checks a wait any more, so a match at the ceiling means the condition became
// true earlier and no stream woke the run. That is the signal that replaces the poll.
waitAction.config.condition = {
filters: {
bytecode: ['_H', 1, 32, 'test', 32, 'event', 1, 1, 11],
events: [{ id: 'test', name: 'test', type: 'events', order: 0 }],
},
}
waitInvocation.state.currentAction!.startedAtTimestamp = DateTime.utc().minus({ hours: 5 }).toMillis()
waitInvocation.state.currentAction!.parkedMaxWaitDuration = '4h'
waitAction.config.max_wait_duration = '4h'
const result = await handler.execute({
invocation: waitInvocation,
action: waitAction,
result: createInvocationResult(waitInvocation),
})
expect(result.nextAction).toEqual(findActionById(waitInvocation.hogFlow, 'matched_target'))
expect(await lateAdvanceCount()).toBe(1)
// Must name the flow, not the run: attributing the residual is the counter's whole job.
expect(await lateAdvanceLabels()).toEqual({
team_id: waitInvocation.hogFlow.team_id,
hog_flow_id: waitInvocation.hogFlow.id,
})
})
it('does not count a wait that matched before its ceiling', async () => {
// The ordinary case: a stream woke the run, or it matched on entry, well inside max_wait.
waitAction.config.condition = {
filters: {
bytecode: ['_H', 1, 32, 'test', 32, 'event', 1, 1, 11],
events: [{ id: 'test', name: 'test', type: 'events', order: 0 }],
},
}
waitInvocation.state.currentAction!.startedAtTimestamp = DateTime.utc().minus({ minutes: 5 }).toMillis()
waitAction.config.max_wait_duration = '4h'
const result = await handler.execute({
invocation: waitInvocation,
action: waitAction,
result: createInvocationResult(waitInvocation),
})
expect(result.nextAction).toEqual(findActionById(waitInvocation.hogFlow, 'matched_target'))
expect(await lateAdvanceCount()).toBe(0)
})
it('does not count a match woken by a sweep after the ceiling was shortened', async () => {
// The timing sweep moves `scheduled` with a bulk UPDATE and stamps no marker, so a run
// parked against a ceiling the author later cut wakes past the new one. That is an edit
// landing, not a wake the streams missed.
waitAction.config.condition = {
filters: {
bytecode: ['_H', 1, 32, 'test', 32, 'event', 1, 1, 11],
events: [{ id: 'test', name: 'test', type: 'events', order: 0 }],
},
}
waitInvocation.state.currentAction!.startedAtTimestamp = DateTime.utc().minus({ hours: 5 }).toMillis()
waitInvocation.state.currentAction!.parkedMaxWaitDuration = '7d'
waitAction.config.max_wait_duration = '4h'
const result = await handler.execute({
invocation: waitInvocation,
action: waitAction,
result: createInvocationResult(waitInvocation),
})
expect(result.nextAction).toEqual(findActionById(waitInvocation.hogFlow, 'matched_target'))
expect(await lateAdvanceCount()).toBe(0)
})
it('does not count a timeout, which takes the continue edge rather than matching', async () => {
// The default condition never matches, so reaching the ceiling is an ordinary timeout.
waitInvocation.state.currentAction!.startedAtTimestamp = DateTime.utc().minus({ hours: 5 }).toMillis()
waitAction.config.max_wait_duration = '4h'
await handler.execute({
invocation: waitInvocation,
action: waitAction,
result: createInvocationResult(waitInvocation),
})
expect(await lateAdvanceCount()).toBe(0)
})
it('records a rekey wake as advanced and consumes the one-shot flag when the merge makes the condition match', async () => {
// A merge re-keyed this parked wait onto the survivor and woke it (rekeyWake). The re-check
// now finds the condition true. Consuming the flag is what keeps the next re-check from
// re-emitting the outcome — without it a re-parked wake would inflate the churn metric.
waitAction.config.condition = {
filters: {
bytecode: ['_H', 1, 32, 'test', 32, 'event', 1, 1, 11],
events: [{ id: 'test', name: 'test', type: 'events', order: 0 }],
},
}
waitInvocation.state.currentAction!.rekeyWake = true
const result = await handler.execute({
invocation: waitInvocation,
action: waitAction,
result: createInvocationResult(waitInvocation),
})
expect(result.nextAction).toEqual(findActionById(waitInvocation.hogFlow, 'matched_target'))
expect(await rekeyWakeCount('advanced')).toBe(1)
expect(await rekeyWakeCount('reparked')).toBe(0)
expect(waitInvocation.state.currentAction!.rekeyWake).toBe(false)
})
it('records a rekey wake as reparked and consumes the one-shot flag when the merge does not satisfy the wait', async () => {
// The default condition still does not match after the re-key, so waking was wasted churn.
waitInvocation.state.currentAction!.rekeyWake = true
const result = await handler.execute({
invocation: waitInvocation,
action: waitAction,
result: createInvocationResult(waitInvocation),
})
expect(result.scheduledAt).toBeDefined()
expect(await rekeyWakeCount('reparked')).toBe(1)
expect(await rekeyWakeCount('advanced')).toBe(0)
expect(waitInvocation.state.currentAction!.rekeyWake).toBe(false)
})
})
})