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.

13.4 KB
Raw Blame
import { DiagnosisVerdict, diagnoseReplayCapture, hasReplayDiagnosticSignals } from './replayCaptureDiagnostics'

type Case = {
    name: string
    properties: Record<string, any>
    expected: DiagnosisVerdict
}

describe('diagnoseReplayCapture', () => {
    const verdictCases: Case[] = [
        {
            name: '$has_recording=true short-circuits to captured',
            properties: { $has_recording: true, $recording_status: 'disabled' },
            expected: 'captured',
        },
        {
            name: '$has_recording=false does not short-circuit — falls through to other rules',
            properties: { $has_recording: false, $recording_status: 'disabled' },
            expected: 'disabled',
        },
        {
            name: 'ad blocker prevented script load',
            properties: { $sdk_debug_recording_script_not_loaded: true },
            expected: 'ad_blocked',
        },
        {
            name: 'recording explicitly disabled',
            properties: { $recording_status: 'disabled' },
            expected: 'disabled',
        },
        {
            name: 'URL trigger is pending and nothing matched',
            properties: {
                $recording_status: 'buffering',
                $sdk_debug_replay_url_trigger_status: 'trigger_pending',
                $sdk_debug_replay_event_trigger_status: 'trigger_disabled',
                $sdk_debug_replay_linked_flag_trigger_status: 'trigger_disabled',
            },
            expected: 'trigger_pending',
        },
        {
            name: 'event trigger pending takes precedence over buffering-empty',
            properties: {
                $recording_status: 'buffering',
                $sdk_debug_replay_url_trigger_status: 'trigger_disabled',
                $sdk_debug_replay_event_trigger_status: 'trigger_pending',
                $sdk_debug_replay_linked_flag_trigger_status: 'trigger_disabled',
                $sdk_debug_replay_internal_buffer_length: 0,
            },
            expected: 'trigger_pending',
        },
        {
            name: 'linked flag pending but URL matched → not trigger_pending',
            properties: {
                $recording_status: 'active',
                $sdk_debug_replay_url_trigger_status: 'trigger_matched',
                $sdk_debug_replay_linked_flag_trigger_status: 'trigger_pending',
                $sdk_debug_replay_flushed_size: 1024,
            },
            expected: 'captured',
        },
        {
            name: 'sampled status means sampled in — not sampled out',
            properties: { $recording_status: 'sampled' },
            expected: 'unknown',
        },
        {
            name: 'sampled out via start reason',
            properties: { $session_recording_start_reason: 'sampled_out' },
            expected: 'sampled_out',
        },
        {
            name: 'buffering with empty buffer and no flushed data',
            properties: {
                $recording_status: 'buffering',
                $sdk_debug_replay_internal_buffer_length: 0,
                $sdk_debug_replay_flushed_size: 0,
            },
            expected: 'buffering_empty',
        },
        {
            name: 'active with flushed bytes → captured',
            properties: {
                $recording_status: 'active',
                $sdk_debug_replay_flushed_size: 2048,
                $session_recording_start_reason: 'recording_initialized',
            },
            expected: 'captured',
        },
        {
            name: 'reported rrweb error → recorder_error',
            properties: {
                $recording_status: 'buffering',
                $sdk_debug_replay_rrweb_error: 'TypeError: boom',
            },
            expected: 'recorder_error',
        },
        {
            name: 'rrweb error outranks a pending trigger',
            properties: {
                $recording_status: 'buffering',
                $sdk_debug_replay_event_trigger_status: 'trigger_pending',
                $sdk_debug_replay_rrweb_error: 'boom',
            },
            expected: 'recorder_error',
        },
        {
            // rrweb is started during buffering, so an unattached recorder with no reported error
            // is a normal sampled-out / torn-down session, not a failure.
            name: 'unattached recorder without an error is not mislabelled as recorder_error',
            properties: {
                $recording_status: 'buffering',
                $sdk_debug_rrweb_start_attempted: true,
                $sdk_debug_rrweb_attached: false,
                $session_recording_start_reason: 'sampled_out',
            },
            expected: 'sampled_out',
        },
        {
            name: 'string-valued flushed size is coerced to a number',
            properties: {
                $recording_status: 'active',
                $sdk_debug_replay_flushed_size: '2048',
            },
            expected: 'captured',
        },
        {
            name: 'empty properties object → unknown',
            properties: {},
            expected: 'unknown',
        },
        {
            name: 'null properties → unknown',
            properties: null as any,
            expected: 'unknown',
        },
        {
            name: 'undefined properties → unknown',
            properties: undefined as any,
            expected: 'unknown',
        },
        {
            name: 'ad_blocked takes priority over disabled when both present',
            properties: {
                $sdk_debug_recording_script_not_loaded: true,
                $recording_status: 'disabled',
            },
            expected: 'ad_blocked',
        },
        {
            name: 'disabled takes priority over sampled when both present',
            properties: {
                $recording_status: 'disabled',
                $session_recording_start_reason: 'sampled_out',
            },
            expected: 'disabled',
        },
        {
            name: 'multiple triggers pending lists all in reasons',
            properties: {
                $sdk_debug_replay_url_trigger_status: 'trigger_pending',
                $sdk_debug_replay_event_trigger_status: 'trigger_pending',
                $sdk_debug_replay_linked_flag_trigger_status: 'trigger_disabled',
            },
            expected: 'trigger_pending',
        },
        {
            name: 'all three triggers pending',
            properties: {
                $sdk_debug_replay_url_trigger_status: 'trigger_pending',
                $sdk_debug_replay_event_trigger_status: 'trigger_pending',
                $sdk_debug_replay_linked_flag_trigger_status: 'trigger_pending',
            },
            expected: 'trigger_pending',
        },
        {
            name: 'buffering with non-zero buffer length does not match buffering_empty',
            properties: {
                $recording_status: 'buffering',
                $sdk_debug_replay_internal_buffer_length: 5,
                $sdk_debug_replay_flushed_size: 0,
            },
            expected: 'unknown',
        },
        {
            name: 'buffering with null buffer length and null flushed size → unknown (not buffering_empty)',
            properties: {
                $recording_status: 'buffering',
            },
            expected: 'unknown',
        },
        {
            name: 'active with zero flushed size → unknown (not captured)',
            properties: {
                $recording_status: 'active',
                $sdk_debug_replay_flushed_size: 0,
            },
            expected: 'unknown',
        },
        {
            name: 'active with no flushed size property → unknown',
            properties: {
                $recording_status: 'active',
            },
            expected: 'unknown',
        },
        {
            name: 'paused recording status → unknown',
            properties: {
                $recording_status: 'paused',
            },
            expected: 'unknown',
        },
        {
            name: 'string-valued buffer length "0" is coerced for buffering_empty',
            properties: {
                $recording_status: 'buffering',
                $sdk_debug_replay_internal_buffer_length: '0',
                $sdk_debug_replay_flushed_size: '0',
            },
            expected: 'buffering_empty',
        },
        {
            name: 'empty string flushed size is not coerced to a number',
            properties: {
                $recording_status: 'active',
                $sdk_debug_replay_flushed_size: '',
            },
            expected: 'unknown',
        },
    ]

    it.each(verdictCases)('$name → $expected', ({ properties, expected }) => {
        const result = diagnoseReplayCapture(properties)
        expect(result.verdict).toBe(expected)
        expect(result.headline).toBeTruthy()
        expect(result.reasons.length).toBeGreaterThan(0)
    })

    it('includes relevant raw signals in the result', () => {
        const result = diagnoseReplayCapture({
            $recording_status: 'active',
            $sdk_debug_replay_flushed_size: 500,
            $unrelated_property: 'should not appear',
        })
        expect(result.rawSignals).toEqual({
            $recording_status: 'active',
            $sdk_debug_replay_flushed_size: 500,
        })
    })

    it('includes settings action for disabled verdict', () => {
        const result = diagnoseReplayCapture({ $recording_status: 'disabled' })
        const labels = result.suggestedActions.map((a) => a.label)
        expect(labels).toContain('Open replay settings')
        expect(labels).toContain('Read troubleshooting docs')
    })

    it('does not include settings action for captured verdict', () => {
        const result = diagnoseReplayCapture({ $has_recording: true })
        const labels = result.suggestedActions.map((a) => a.label)
        expect(labels).not.toContain('Open replay settings')
        expect(labels).toContain('Read troubleshooting docs')
    })

    it('trigger_pending reason mentions all pending trigger names', () => {
        const result = diagnoseReplayCapture({
            $sdk_debug_replay_url_trigger_status: 'trigger_pending',
            $sdk_debug_replay_event_trigger_status: 'trigger_pending',
            $sdk_debug_replay_linked_flag_trigger_status: 'trigger_disabled',
        })
        expect(result.reasons[0]).toContain('URL trigger')
        expect(result.reasons[0]).toContain('event trigger')
        expect(result.reasons[0]).not.toContain('linked flag trigger')
    })

    it('recorder_error surfaces the rrweb error message when present', () => {
        const result = diagnoseReplayCapture({
            $recording_status: 'buffering',
            $sdk_debug_replay_rrweb_error: 'boom',
        })
        expect(result.verdict).toBe('recorder_error')
        expect(result.reasons.some((r) => r.includes('boom'))).toBe(true)
    })

    it('preserves newly added replay debug keys in rawSignals', () => {
        const result = diagnoseReplayCapture({
            $replay_override_sampling: true,
            $sdk_debug_rrweb_attached: false,
            $sdk_debug_replay_trigger_groups_count: 3,
            $session_recording_event_trigger_activated_session: 'abc',
            $not_a_signal: 'ignored',
        })
        expect(result.rawSignals).toHaveProperty('$replay_override_sampling')
        expect(result.rawSignals).toHaveProperty('$sdk_debug_rrweb_attached')
        expect(result.rawSignals).toHaveProperty('$sdk_debug_replay_trigger_groups_count')
        expect(result.rawSignals).toHaveProperty('$session_recording_event_trigger_activated_session')
        expect(result.rawSignals).not.toHaveProperty('$not_a_signal')
    })

    it('preserves all known diagnostic keys in rawSignals', () => {
        const properties = {
            $has_recording: false,
            $recording_status: 'active',
            $session_recording_start_reason: 'recording_initialized',
            $replay_sample_rate: 0.5,
            $replay_minimum_duration: 3000,
            $sdk_debug_session_start: '2024-01-01T00:00:00Z',
            $some_other_prop: 'ignored',
        }
        const result = diagnoseReplayCapture(properties)
        expect(result.rawSignals).toHaveProperty('$has_recording')
        expect(result.rawSignals).toHaveProperty('$recording_status')
        expect(result.rawSignals).toHaveProperty('$session_recording_start_reason')
        expect(result.rawSignals).toHaveProperty('$replay_sample_rate')
        expect(result.rawSignals).toHaveProperty('$replay_minimum_duration')
        expect(result.rawSignals).toHaveProperty('$sdk_debug_session_start')
        expect(result.rawSignals).not.toHaveProperty('$some_other_prop')
    })
})

describe('hasReplayDiagnosticSignals', () => {
    it('returns false for nullish or empty properties', () => {
        expect(hasReplayDiagnosticSignals(undefined)).toBe(false)
        expect(hasReplayDiagnosticSignals(null)).toBe(false)
        expect(hasReplayDiagnosticSignals({})).toBe(false)
    })

    it('returns false when no recording diagnostic signals are present', () => {
        expect(hasReplayDiagnosticSignals({ $browser: 'Chrome', some_custom_prop: 1 })).toBe(false)
    })

    it('returns true when at least one recording diagnostic signal is present', () => {
        expect(hasReplayDiagnosticSignals({ $recording_status: 'buffering' })).toBe(true)
        expect(hasReplayDiagnosticSignals({ $sdk_debug_replay_event_trigger_status: 'trigger_pending' })).toBe(true)
        expect(hasReplayDiagnosticSignals({ $has_recording: false })).toBe(true)
    })
})