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.

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