: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 { dayjs } from 'lib/dayjs'
import {
AnyPropertyFilter,
FeatureFlagGroupType,
FeatureFlagType,
PropertyFilterType,
PropertyOperator,
RecurrenceInterval,
ScheduledChangeOperationType,
ScheduledChangePayload,
ScheduledChangeRequestState,
ScheduledChangeType,
} from '~/types'
import { makeScheduledChange, resetScheduledChangeIds } from './makeScheduledChange'
import {
OCCURRENCE_CAP,
expandScheduleOccurrences,
maxUntargetedRolloutPercentage,
sharedAggregationTarget,
} from './scheduleOccurrences'
const NOW = dayjs('2026-01-01T00:00:00Z')
function change(overrides: Partial<ScheduledChangeType> & { payload: ScheduledChangePayload }): ScheduledChangeType {
return makeScheduledChange({ scheduled_at: NOW.add(1, 'day').toISOString(), ...overrides })
}
const PERSON_FILTER: AnyPropertyFilter = {
key: 'email',
value: 'a',
type: PropertyFilterType.Person,
operator: PropertyOperator.Exact,
}
function conditionPayload(
rolloutPercentage: number,
properties: AnyPropertyFilter[] = [],
aggregationGroupTypeIndex?: number | null
): ScheduledChangePayload {
return {
operation: ScheduledChangeOperationType.AddReleaseCondition,
value: {
groups: [
{
properties,
rollout_percentage: rolloutPercentage,
variant: null,
aggregation_group_type_index: aggregationGroupTypeIndex,
},
],
},
}
}
const STATUS_ON: ScheduledChangePayload = { operation: ScheduledChangeOperationType.UpdateStatus, value: true }
function flag(
overrides: Partial<Pick<FeatureFlagType, 'active' | 'filters'>> = {}
): Pick<FeatureFlagType, 'active' | 'filters'> {
return {
active: true,
filters: {
groups: [{ properties: [], rollout_percentage: 10, variant: null }],
multivariate: null,
},
...overrides,
}
}
describe('expandScheduleOccurrences', () => {
beforeEach(() => {
resetScheduledChangeIds()
})
it('projects a rollout ramp cumulatively and in chronological order', () => {
// Deliberately out of order: expansion must sort by time, not input order.
const schedules = [
change({ payload: conditionPayload(75), scheduled_at: NOW.add(3, 'day').toISOString() }),
change({ payload: conditionPayload(25), scheduled_at: NOW.add(1, 'day').toISOString() }),
change({ payload: conditionPayload(100), scheduled_at: NOW.add(4, 'day').toISOString() }),
change({ payload: conditionPayload(50), scheduled_at: NOW.add(2, 'day').toISOString() }),
]
const occurrences = expandScheduleOccurrences(schedules, flag(), NOW)
expect(occurrences.map((o) => o.projected.rolloutPercentage)).toEqual([25, 50, 75, 100])
expect(occurrences.map((o) => o.addedRolloutPercentage)).toEqual([25, 50, 75, 100])
expect(occurrences.map((o) => o.rolloutUnchanged)).toEqual([false, false, false, false])
expect(occurrences.map((o) => o.timestamp)).toEqual([
NOW.add(1, 'day').toISOString(),
NOW.add(2, 'day').toISOString(),
NOW.add(3, 'day').toISOString(),
NOW.add(4, 'day').toISOString(),
])
})
it.each([
{
name: 'a flag that already serves everyone',
current: 100,
adds: [25, 50, 100],
expected: [true, true, true],
},
{ name: 'a ramp that overtakes the current level', current: 30, adds: [25, 50], expected: [true, false] },
{ name: 'an add that matches the current level', current: 25, adds: [25], expected: [true] },
{
name: 'an add covered by an earlier scheduled add',
current: 10,
adds: [50, 30],
expected: [false, true],
},
])('marks a covered condition add as no change: $name', ({ current, adds, expected }) => {
const schedules = adds.map((rollout, index) =>
change({ payload: conditionPayload(rollout), scheduled_at: NOW.add(index + 1, 'day').toISOString() })
)
const occurrences = expandScheduleOccurrences(
schedules,
flag({ filters: { groups: [{ properties: [], rollout_percentage: current, variant: null }] } }),
NOW
)
expect(occurrences.map((o) => o.rolloutUnchanged)).toEqual(expected)
})
it('ignores property-narrowed condition sets in the projected reach and the no-change flag', () => {
const schedules = [
change({ payload: conditionPayload(100, [PERSON_FILTER]), scheduled_at: NOW.add(1, 'day').toISOString() }),
change({ payload: conditionPayload(50), scheduled_at: NOW.add(2, 'day').toISOString() }),
// A narrowed add is still judged on its raw percentage, because it buckets on the same
// hash as the untargeted set that already covers it.
change({ payload: conditionPayload(25, [PERSON_FILTER]), scheduled_at: NOW.add(3, 'day').toISOString() }),
]
const occurrences = expandScheduleOccurrences(
schedules,
flag({
filters: {
groups: [
{ properties: [PERSON_FILTER], rollout_percentage: 100, variant: null },
{ properties: [], rollout_percentage: 10, variant: null },
],
multivariate: null,
},
}),
NOW
)
expect(occurrences.map((o) => o.rolloutUnchanged)).toEqual([false, false, true])
expect(occurrences.map((o) => o.projected.rolloutPercentage)).toEqual([10, 50, 50])
})
const aggregationCases: {
name: string
flagAggregation: number | null | undefined
coveringAggregation: number | null | undefined
addedAggregation?: number | null
extraGroups?: FeatureFlagGroupType[]
expected: boolean
expectedRollout: number | null
}[] = [
{
name: 'a covering set on another aggregation target',
flagAggregation: undefined,
coveringAggregation: 0,
expected: false,
expectedRollout: 25,
},
{
name: 'a covering set that shares the flag-level group target',
flagAggregation: 0,
coveringAggregation: undefined,
expected: true,
expectedRollout: 100,
},
{
name: 'an added set on another aggregation target',
flagAggregation: undefined,
coveringAggregation: undefined,
addedAggregation: 0,
expected: false,
expectedRollout: 100,
},
{
name: 'a covering set on a target the line does not plot',
flagAggregation: null,
coveringAggregation: 0,
addedAggregation: 0,
extraGroups: [
{ properties: [], rollout_percentage: 10, variant: null, aggregation_group_type_index: null },
],
expected: false,
expectedRollout: 10,
},
]
it.each(aggregationCases)(
'judges an added condition against $name: no change=$expected',
({ flagAggregation, coveringAggregation, addedAggregation, extraGroups = [], expected, expectedRollout }) => {
const schedules = [change({ payload: conditionPayload(25, [], addedAggregation) })]
const occurrences = expandScheduleOccurrences(
schedules,
flag({
filters: {
groups: [
{
properties: [],
rollout_percentage: 100,
variant: null,
aggregation_group_type_index: coveringAggregation,
},
...extraGroups,
],
aggregation_group_type_index: flagAggregation,
multivariate: null,
},
}),
NOW
)
expect(occurrences[0].rolloutUnchanged).toBe(expected)
expect(occurrences[0].projected.rolloutPercentage).toBe(expectedRollout)
}
)
it('carries status, rollout, and variant projections through a mixed plan', () => {
const schedules = [
change({
payload: { operation: ScheduledChangeOperationType.UpdateStatus, value: false },
scheduled_at: NOW.add(1, 'day').toISOString(),
}),
change({ payload: conditionPayload(5), scheduled_at: NOW.add(2, 'day').toISOString() }),
change({
payload: {
operation: ScheduledChangeOperationType.UpdateVariants,
value: {
variants: [
{ key: 'a', rollout_percentage: 50 },
{ key: 'b', rollout_percentage: 50 },
],
},
},
scheduled_at: NOW.add(3, 'day').toISOString(),
}),
]
const occurrences = expandScheduleOccurrences(schedules, flag(), NOW)
expect(occurrences.map((o) => o.projected)).toEqual([
{ active: false, rolloutPercentage: 10, variantCount: null },
// A 5% condition does not lower the flag's existing 10% max rollout.
{ active: false, rolloutPercentage: 10, variantCount: null },
{ active: false, rolloutPercentage: 10, variantCount: 2 },
])
expect(occurrences.map((o) => o.rolloutUnchanged)).toEqual([false, true, false])
})
it.each([
{
name: 'a condition set with no rollout percentage as 100%',
groups: [{ properties: [], rollout_percentage: null, variant: null }],
expected: 100,
},
{ name: 'no condition sets as unknown', groups: [], expected: null },
])('reads $name', ({ groups, expected }) => {
// Null means the set matches all of its targets. Coercing it to 0 would floor the step
// line and describe a scheduled condition as a 0% rollout.
const schedules = [
change({
payload: { operation: ScheduledChangeOperationType.AddReleaseCondition, value: { groups } },
}),
]
const occurrences = expandScheduleOccurrences(schedules, flag({ filters: { groups, multivariate: null } }), NOW)
expect(occurrences[0].addedRolloutPercentage).toEqual(expected)
expect(occurrences[0].projected.rolloutPercentage).toEqual(expected)
})
it('expands a fixed-interval recurring schedule up to its end date', () => {
const schedules = [
change({
payload: STATUS_ON,
is_recurring: true,
recurrence_interval: RecurrenceInterval.Daily,
scheduled_at: NOW.add(1, 'day').toISOString(),
end_date: NOW.add(3, 'day').add(12, 'hour').toISOString(),
}),
]
const occurrences = expandScheduleOccurrences(schedules, flag(), NOW)
expect(occurrences.map((o) => o.timestamp)).toEqual([
NOW.add(1, 'day').toISOString(),
NOW.add(2, 'day').toISOString(),
NOW.add(3, 'day').toISOString(),
])
})
it('stops recurring expansion at the horizon', () => {
const schedules = [
change({
payload: STATUS_ON,
is_recurring: true,
recurrence_interval: RecurrenceInterval.Monthly,
scheduled_at: NOW.add(10, 'day').toISOString(),
}),
]
// Jan 11, Feb 11, and Mar 11 fall inside the 90-day horizon; Apr 11 does not.
expect(expandScheduleOccurrences(schedules, flag(), NOW)).toHaveLength(3)
})
it('clamps month-end recurring dates iteratively, matching the backend', () => {
// A monthly schedule starting Jan 31 must not restore the 31st after a short month: the
// backend advances from the previous run (Jan 31 -> Feb 28 -> Mar 28), so the projection must too.
const schedules = [
change({
payload: STATUS_ON,
is_recurring: true,
recurrence_interval: RecurrenceInterval.Monthly,
scheduled_at: dayjs('2026-01-31T09:00:00Z').toISOString(),
}),
]
const occurrences = expandScheduleOccurrences(schedules, flag(), NOW)
expect(occurrences.map((o) => o.timestamp)).toEqual([
'2026-01-31T09:00:00.000Z',
'2026-02-28T09:00:00.000Z',
'2026-03-28T09:00:00.000Z',
])
})
it('gives a denied recurring cron schedule no occurrences', () => {
// The next cron run after the denied one is not computed client-side.
const schedules = [
change({
payload: STATUS_ON,
is_recurring: true,
cron_expression: '0 9 * * 1-5',
change_request: { id: 'cr-5', state: ScheduledChangeRequestState.Expired },
}),
]
expect(expandScheduleOccurrences(schedules, flag(), NOW)).toEqual([])
})
it('caps the total number of occurrences', () => {
const schedules = [
change({
payload: STATUS_ON,
is_recurring: true,
recurrence_interval: RecurrenceInterval.Daily,
scheduled_at: NOW.add(1, 'day').toISOString(),
}),
]
expect(expandScheduleOccurrences(schedules, flag(), NOW)).toHaveLength(OCCURRENCE_CAP)
})
it('gives a cron schedule exactly one occurrence, at its next run', () => {
const scheduledAt = NOW.add(1, 'day').toISOString()
const schedules = [
change({
payload: STATUS_ON,
is_recurring: true,
cron_expression: '0 9 * * 1-5',
scheduled_at: scheduledAt,
}),
]
const occurrences = expandScheduleOccurrences(schedules, flag(), NOW)
expect(occurrences).toHaveLength(1)
expect(occurrences[0].timestamp).toEqual(scheduledAt)
})
it.each([
{ state: ScheduledChangeRequestState.Pending, expected: true },
{ state: ScheduledChangeRequestState.Approved, expected: false },
])('marks occurrences with a $state approval request as needsApproval=$expected', ({ state, expected }) => {
const schedules = [change({ payload: STATUS_ON, change_request: { id: 'cr-1', state } })]
expect(expandScheduleOccurrences(schedules, flag(), NOW)[0].needsApproval).toBe(expected)
})
it.each([
{ state: ScheduledChangeRequestState.Approved, firstNeedsApproval: false },
{ state: ScheduledChangeRequestState.Pending, firstNeedsApproval: true },
])(
're-gates every occurrence after the first of a $state gated recurring schedule',
({ state, firstNeedsApproval }) => {
// The bound request covers one fire. The backend binds a fresh pending request to each
// later occurrence, so an approved request must not project the whole ramp as certain.
const schedules = [
change({
payload: STATUS_ON,
is_recurring: true,
recurrence_interval: RecurrenceInterval.Daily,
scheduled_at: NOW.add(1, 'day').toISOString(),
change_request: { id: 'cr-1', state },
}),
]
const occurrences = expandScheduleOccurrences(schedules, flag(), NOW)
expect(occurrences[0].needsApproval).toBe(firstNeedsApproval)
expect(occurrences.slice(1).map((o) => o.needsApproval)).toEqual(occurrences.slice(1).map(() => true))
}
)
it('leaves an ungated recurring schedule unmarked throughout', () => {
const schedules = [
change({
payload: STATUS_ON,
is_recurring: true,
recurrence_interval: RecurrenceInterval.Daily,
scheduled_at: NOW.add(1, 'day').toISOString(),
}),
]
const occurrences = expandScheduleOccurrences(schedules, flag(), NOW)
expect(occurrences.every((o) => !o.needsApproval)).toBe(true)
})
it.each([{ state: ScheduledChangeRequestState.Rejected }, { state: ScheduledChangeRequestState.Expired }])(
'drops a $state recurring occurrence but keeps expanding the rest',
({ state }) => {
const schedules = [
change({
payload: STATUS_ON,
is_recurring: true,
recurrence_interval: RecurrenceInterval.Daily,
scheduled_at: NOW.add(1, 'day').toISOString(),
change_request: { id: 'cr-denied', state },
}),
]
const occurrences = expandScheduleOccurrences(schedules, flag(), NOW)
// The backend skips this occurrence and re-gates the next, so the timeline must not
// project the denied change as applied; expansion resumes at the following day.
expect(occurrences.map((o) => o.timestamp)).not.toContain(NOW.add(1, 'day').toISOString())
expect(occurrences[0].timestamp).toEqual(NOW.add(2, 'day').toISOString())
}
)
it.each([
{
name: 'paused recurring',
overrides: { is_recurring: false, recurrence_interval: RecurrenceInterval.Daily },
},
{ name: 'executed', overrides: { executed_at: NOW.subtract(1, 'day').toISOString() } },
{
name: 'rejected one-time',
overrides: { change_request: { id: 'cr-2', state: ScheduledChangeRequestState.Rejected } },
},
{
name: 'expired one-time',
overrides: { change_request: { id: 'cr-3', state: ScheduledChangeRequestState.Expired } },
},
{ name: 'unparseable scheduled_at', overrides: { scheduled_at: 'not-a-date' } },
{
// A recoverable failure leaves executed_at null with a now-past scheduled_at
// (process_scheduled_changes: "leave executed_at=NULL to allow retries").
name: 'past-due one-time',
overrides: { scheduled_at: NOW.subtract(2, 'day').toISOString() },
},
{
name: 'past-due cron',
overrides: {
scheduled_at: NOW.subtract(2, 'day').toISOString(),
is_recurring: true,
cron_expression: '0 9 * * 1-5',
},
},
{
name: 'recurring past its end date',
overrides: {
scheduled_at: NOW.subtract(10, 'day').toISOString(),
is_recurring: true,
recurrence_interval: RecurrenceInterval.Daily,
end_date: NOW.subtract(5, 'day').toISOString(),
},
},
{
// The sweep advances scheduled_at without reading end_date, so a closed window can
// hold a future date until the sweep reaches it and stamps executed_at.
name: 'recurring past its end date with a future scheduled_at',
overrides: {
scheduled_at: NOW.add(1, 'day').toISOString(),
is_recurring: true,
recurrence_interval: RecurrenceInterval.Daily,
end_date: NOW.subtract(1, 'day').toISOString(),
},
},
])('excludes $name schedules', ({ overrides }) => {
const schedules = [change({ payload: STATUS_ON, ...overrides })]
expect(expandScheduleOccurrences(schedules, flag(), NOW)).toEqual([])
})
it('catches a stalled recurring schedule up to its next fire, and re-gates it', () => {
// The sweep leaves scheduled_at in the past when it defers on a conflicting approval, then
// skips the missed fires. An approved request covered the fire that never happened, so the
// caught-up occurrence must still read as needing approval.
const schedules = [
change({
payload: STATUS_ON,
is_recurring: true,
recurrence_interval: RecurrenceInterval.Daily,
scheduled_at: NOW.subtract(3, 'day').add(9, 'hour').toISOString(),
change_request: { id: 'cr-1', state: ScheduledChangeRequestState.Approved },
}),
]
const occurrences = expandScheduleOccurrences(schedules, flag(), NOW)
expect(occurrences[0].timestamp).toEqual(NOW.add(9, 'hour').toISOString())
expect(occurrences[0].needsApproval).toBe(true)
})
it('clamps a stalled monthly schedule along the path the sweep took', () => {
// Oct 31 monthly gives Nov 30, then Dec 30, then Jan 30. Adding three months to the origin
// would restore the 31st and paint a date the flag never fires on.
const schedules = [
change({
payload: STATUS_ON,
is_recurring: true,
recurrence_interval: RecurrenceInterval.Monthly,
scheduled_at: dayjs('2025-10-31T09:00:00Z').toISOString(),
}),
]
const occurrences = expandScheduleOccurrences(schedules, flag(), NOW)
expect(occurrences[0].timestamp).toEqual('2026-01-30T09:00:00.000Z')
})
})
describe('maxUntargetedRolloutPercentage', () => {
const cases: {
name: string
groups: FeatureFlagGroupType[]
flagAggregation?: number | null
target: number | null | undefined
expected: number | null
}[] = [
{
name: 'ignores a condition set a property filter narrows',
groups: [
{ properties: [PERSON_FILTER], rollout_percentage: 100, variant: null },
{ properties: [], rollout_percentage: 20, variant: null },
],
target: null,
expected: 20,
},
{
name: 'reads a missing rollout as everyone',
groups: [{ properties: [], rollout_percentage: null, variant: null }],
target: null,
expected: 100,
},
{
name: 'returns null when every set is narrowed',
groups: [{ properties: [PERSON_FILTER], rollout_percentage: 100, variant: null }],
target: null,
expected: null,
},
{
name: 'ignores a condition set that targets a group type',
groups: [
{ properties: [], rollout_percentage: 100, variant: null, aggregation_group_type_index: 0 },
{ properties: [], rollout_percentage: 20, variant: null },
],
target: null,
expected: 20,
},
{
name: 'measures a condition set that inherits the flag-level group target',
groups: [{ properties: [], rollout_percentage: 60, variant: null }],
flagAggregation: 0,
target: 0,
expected: 60,
},
{
name: 'returns null when the target is unknown',
groups: [{ properties: [], rollout_percentage: 60, variant: null }],
target: undefined,
expected: null,
},
]
it.each(cases)('$name', ({ groups, flagAggregation, target, expected }) => {
expect(maxUntargetedRolloutPercentage(groups, flagAggregation, target)).toEqual(expected)
})
})
describe('sharedAggregationTarget', () => {
const cases: {
name: string
groups: FeatureFlagGroupType[]
flagAggregation?: number | null
expected: number | null | undefined
}[] = [
{
name: 'reads the flag-level target when every set inherits it',
groups: [
{ properties: [], rollout_percentage: 100, variant: null },
{ properties: [], rollout_percentage: 50, variant: null },
],
flagAggregation: 0,
expected: 0,
},
{
name: 'returns undefined when the sets target different identifiers',
groups: [
{ properties: [], rollout_percentage: 100, variant: null, aggregation_group_type_index: 0 },
{ properties: [], rollout_percentage: 50, variant: null, aggregation_group_type_index: null },
],
expected: undefined,
},
{ name: 'returns undefined when there are no sets', groups: [], expected: undefined },
]
it.each(cases)('$name', ({ groups, flagAggregation, expected }) => {
expect(sharedAggregationTarget(groups, flagAggregation)).toEqual(expected)
})
})