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.

15.5 KB
Raw Blame
import {
    autoCaptureEventToDescription,
    distinctPrimaryPropertiesForEvents,
    eventToDescription,
    getEventsWithPrimaryProperty,
    getPrimaryPropertyForEvent,
    hasTaxonomyPrimaryProperty,
} from 'lib/utils/events'

import { ElementType, EventType } from '~/types'

describe('events utils', () => {
    describe('eventToName()', () => {
        const baseEvent = {
            elements: [],
            event: '',
            properties: {},
            person: {},
        } as any as EventType

        it('handles page events as expected', () => {
            expect(
                eventToDescription({ ...baseEvent, event: '$pageview', properties: { $pathname: '/hello' } })
            ).toEqual('/hello')
            expect(
                eventToDescription({ ...baseEvent, event: '$pageleave', properties: { $pathname: '/bye' } })
            ).toEqual('/bye')
        })

        it('handles screen events using $screen_name', () => {
            expect(
                eventToDescription({ ...baseEvent, event: '$screen', properties: { $screen_name: 'CartScreen' } })
            ).toEqual('CartScreen')
        })

        it('falls back to event name when the primary property is missing', () => {
            // Old behaviour fell back to $current_url for $pageview without $pathname; the new
            // single-property contract returns the event name instead so the change is explicit
            // and consistent with $screen / $feature_flag_called.
            expect(
                eventToDescription({
                    ...baseEvent,
                    event: '$pageview',
                    properties: { $current_url: 'https://example.com/' },
                })
            ).toEqual('$pageview')
        })

        it('handles no text autocapture as expected', () => {
            expect(
                eventToDescription({
                    ...baseEvent,
                    event: '$autocapture',
                    properties: { $event_type: 'click' },
                })
            ).toEqual('clicked element')
        })

        it('handles long form autocapture as expected', () => {
            expect(
                eventToDescription({
                    ...baseEvent,
                    event: '$autocapture',
                    properties: { $event_type: 'click' },
                    elements: [{ tag_name: 'button', text: 'hello' } as ElementType],
                })
            ).toEqual('clicked button with text "hello"')
        })

        it('handles short form autocapture as expected', () => {
            expect(
                eventToDescription(
                    {
                        ...baseEvent,
                        event: '$autocapture',
                        properties: { $event_type: 'click' },
                        elements: [{ tag_name: 'button', text: 'hello' } as ElementType],
                    },
                    true
                )
            ).toEqual('clicked "hello"')
        })

        it.each([
            ['with a flag key', { $feature_flag: 'my-flag-key' }, 'my-flag-key'],
            ['without the flag key property', {}, '$feature_flag_called'],
        ])('handles feature flag called events %s', (_, properties, expected) => {
            expect(
                eventToDescription({
                    ...baseEvent,
                    event: '$feature_flag_called',
                    properties,
                })
            ).toEqual(expected)
        })

        it('handles unknown event/action', () => {
            expect(
                eventToDescription({
                    ...baseEvent,
                    event: 'custom event/action',
                })
            ).toEqual('custom event/action')
        })
    })

    describe('autoCaptureEventToDescription()', () => {
        const baseEvent = {
            elements: [],
            event: '$autocapture',
            properties: { $event_type: 'click' },
            person: {},
        } as any as EventType

        it('handles regular text by adding quotes', () => {
            expect(
                autoCaptureEventToDescription({
                    ...baseEvent,
                    properties: {
                        ...baseEvent.properties,
                        $el_text: 'Analyzing Characters with',
                    },
                })
            ).toEqual('clicked element with text "Analyzing Characters with"')
        })

        it('prioritizes $el_text from properties over text in elements array', () => {
            expect(
                autoCaptureEventToDescription({
                    ...baseEvent,
                    properties: {
                        ...baseEvent.properties,
                        $el_text: 'Text from properties',
                    },
                    elements: [{ tag_name: 'button', text: 'Text from elements' } as ElementType],
                })
            ).toEqual('clicked button with text "Text from properties"')
        })

        it('handles text with double quotes without adding additional quotes', () => {
            expect(
                autoCaptureEventToDescription({
                    ...baseEvent,
                    properties: {
                        ...baseEvent.properties,
                        $el_text: 'Unit Skills Assessment 1: "',
                    },
                })
            ).toEqual('clicked element with text "Unit Skills Assessment 1: ""')
        })

        it('handles text with single quotes without adding additional quotes', () => {
            expect(
                autoCaptureEventToDescription({
                    ...baseEvent,
                    properties: {
                        ...baseEvent.properties,
                        $el_text: "Reading Lesson: '",
                    },
                })
            ).toEqual('clicked element with text "Reading Lesson: \'"')
        })

        it('handles longer text with single quotes without adding additional quotes', () => {
            expect(
                autoCaptureEventToDescription({
                    ...baseEvent,
                    properties: {
                        ...baseEvent.properties,
                        $el_text: "A Sense of Wonder: An Introduction to Science Fiction'",
                    },
                })
            ).toEqual('clicked element with text "A Sense of Wonder: An Introduction to Science Fiction\'"')
        })

        it('handles text in elements array', () => {
            expect(
                autoCaptureEventToDescription({
                    ...baseEvent,
                    elements: [{ tag_name: 'button', text: 'hello world' } as ElementType],
                })
            ).toEqual('clicked button with text "hello world"')
        })

        it('handles text with quotes in elements array', () => {
            expect(
                autoCaptureEventToDescription({
                    ...baseEvent,
                    elements: [{ tag_name: 'button', text: 'hello "world"' } as ElementType],
                })
            ).toEqual('clicked button with text "hello "world""')
        })

        it('handles aria-label attributes', () => {
            expect(
                autoCaptureEventToDescription({
                    ...baseEvent,
                    elements: [
                        {
                            tag_name: 'button',
                            attributes: { 'attr__aria-label': 'Close dialog' },
                        } as ElementType,
                    ],
                })
            ).toEqual('clicked button with aria label "Close dialog"')
        })

        it('handles aria-label attributes with quotes', () => {
            expect(
                autoCaptureEventToDescription({
                    ...baseEvent,
                    elements: [
                        {
                            tag_name: 'button',
                            attributes: { 'attr__aria-label': 'Close "main" dialog' },
                        } as ElementType,
                    ],
                })
            ).toEqual('clicked button with aria label "Close "main" dialog"')
        })

        it.each([
            [
                'SVG using link text',
                [{ tag_name: 'svg' } as ElementType, { tag_name: 'a', text: 'View documentation' } as ElementType],
                'clicked link with text "View documentation"',
            ],
            [
                'SVG using button aria-label',
                [
                    { tag_name: 'svg' } as ElementType,
                    {
                        tag_name: 'button',
                        attributes: { 'attr__aria-label': 'Play video' },
                    } as ElementType,
                ],
                'clicked button with aria label "Play video"',
            ],
            [
                'labeled SVG inside an unlabeled link',
                [
                    {
                        tag_name: 'svg',
                        attributes: { 'attr__aria-label': 'Documentation' },
                    } as ElementType,
                    { tag_name: 'a' } as ElementType,
                ],
                'clicked link with aria label "Documentation"',
            ],
            [
                'labeled image inside an unlabeled button',
                [
                    {
                        tag_name: 'img',
                        attributes: { 'attr__aria-label': 'Delete' },
                    } as ElementType,
                    { tag_name: 'button' } as ElementType,
                ],
                'clicked image with aria label "Delete"',
            ],
        ])('describes a clicked %s', (_, elements, expected) => {
            expect(
                autoCaptureEventToDescription({
                    ...baseEvent,
                    elements,
                })
            ).toEqual(expected)
        })
    })

    describe('getPrimaryPropertyForEvent', () => {
        it.each([
            ['$pageview', '$pathname'],
            ['$pageleave', '$pathname'],
            ['$screen', '$screen_name'],
            ['$feature_flag_called', '$feature_flag'],
            ['$exception', '$exception_types'],
            ['$ai_generation', '$ai_model'],
            ['$ai_trace', '$ai_span_name'],
            ['$ai_span', '$ai_span_name'],
            ['$ai_metric', '$ai_metric_name'],
            ['$ai_evaluation', '$ai_evaluation_name'],
            ['$csp_violation', '$csp_violated_directive'],
            ['$mcp_tool_call', '$mcp_tool_name'],
            ['$mcp_resource_read', '$mcp_resource_name'],
            ['$mcp_prompt_get', '$mcp_resource_name'],
            ['Deep link opened', 'url'],
        ])('returns the core taxonomy default for %s', (eventName, expected) => {
            expect(getPrimaryPropertyForEvent(eventName)).toBe(expected)
        })

        it('returns null for events with no taxonomy default and no override', () => {
            expect(getPrimaryPropertyForEvent('$autocapture')).toBeNull()
            expect(getPrimaryPropertyForEvent('some_custom_event')).toBeNull()
        })

        it('returns null for missing event names', () => {
            expect(getPrimaryPropertyForEvent(null)).toBeNull()
            expect(getPrimaryPropertyForEvent(undefined)).toBeNull()
            expect(getPrimaryPropertyForEvent('')).toBeNull()
        })

        it('ignores team-configured overrides for events that have a taxonomy default', () => {
            // Taxonomy is immutable — users can only set primary properties for events
            // without a fixed taxonomy entry.
            expect(getPrimaryPropertyForEvent('$pageview', { $pageview: '$current_url' })).toBe('$pathname')
            expect(getPrimaryPropertyForEvent('$screen', { $screen: 'my_custom_prop' })).toBe('$screen_name')
        })

        it('uses the team-configured override for custom events with no taxonomy default', () => {
            expect(getPrimaryPropertyForEvent('order_placed', { order_placed: 'order_id' })).toBe('order_id')
        })

        it('returns null when no override and no taxonomy default', () => {
            expect(getPrimaryPropertyForEvent('order_placed', { other_event: 'x' })).toBeNull()
        })
    })

    describe('getEventsWithPrimaryProperty', () => {
        it('returns events that have a taxonomy default', () => {
            const events = [
                { event: '$pageview', id: 1 },
                { event: '$autocapture', id: 2 },
                { event: '$screen', id: 3 },
            ]
            expect(getEventsWithPrimaryProperty(events)).toEqual([
                { event: '$pageview', id: 1 },
                { event: '$screen', id: 3 },
            ])
        })

        it('returns events that have a team override (no taxonomy default)', () => {
            const events = [
                { event: 'order_placed', id: 1 },
                { event: 'just_viewed', id: 2 },
            ]
            expect(getEventsWithPrimaryProperty(events, { order_placed: 'order_id' })).toEqual([
                { event: 'order_placed', id: 1 },
            ])
        })

        it('does not include events whose only override is on a taxonomy-fixed event', () => {
            // Taxonomy wins, so an attempted override on $pageview is moot — but the event is still
            // included because the taxonomy default already counts as a primary property.
            const events = [{ event: '$pageview', id: 1 }]
            expect(getEventsWithPrimaryProperty(events, { $pageview: '$current_url' })).toEqual(events)
        })

        it('returns an empty list when nothing has a primary property', () => {
            const events = [
                { event: '$autocapture', id: 1 },
                { event: 'arbitrary_custom', id: 2 },
            ]
            expect(getEventsWithPrimaryProperty(events)).toEqual([])
        })
    })

    describe('distinctPrimaryPropertiesForEvents', () => {
        it('returns the distinct taxonomy defaults for a list of events', () => {
            expect(distinctPrimaryPropertiesForEvents(['$pageview', '$pageleave', '$screen'])).toEqual([
                '$pathname',
                '$screen_name',
            ])
        })

        it('includes team overrides for events with no taxonomy default', () => {
            expect(
                distinctPrimaryPropertiesForEvents(['$pageview', 'order_placed'], { order_placed: 'order_id' })
            ).toEqual(['$pathname', 'order_id'])
        })

        it('returns an empty list for no event names', () => {
            expect(distinctPrimaryPropertiesForEvents([])).toEqual([])
        })

        it('returns an empty list when nothing has a primary property', () => {
            expect(distinctPrimaryPropertiesForEvents(['$autocapture', 'arbitrary_custom'])).toEqual([])
        })
    })

    describe('hasTaxonomyPrimaryProperty', () => {
        it('is true for built-in events that have a primary property', () => {
            expect(hasTaxonomyPrimaryProperty('$pageview')).toBe(true)
            expect(hasTaxonomyPrimaryProperty('$pageleave')).toBe(true)
            expect(hasTaxonomyPrimaryProperty('$screen')).toBe(true)
            expect(hasTaxonomyPrimaryProperty('$feature_flag_called')).toBe(true)
        })

        it('is false for events with no taxonomy primary property', () => {
            expect(hasTaxonomyPrimaryProperty('$autocapture')).toBe(false)
            expect(hasTaxonomyPrimaryProperty('order_placed')).toBe(false)
            expect(hasTaxonomyPrimaryProperty(null)).toBe(false)
            expect(hasTaxonomyPrimaryProperty(undefined)).toBe(false)
            expect(hasTaxonomyPrimaryProperty('')).toBe(false)
        })
    })
})