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.

9.6 KB
Raw Blame
import { beforeAll, describe, expect, it } from 'vitest'

import {
    TEST_ORG_ID,
    TEST_PROJECT_ID,
    createTestClient,
    createTestContext,
    parseToolResponse,
    setActiveProjectAndOrg,
    validateEnvironmentVariables,
} from '@/shared/test-utils'
import { GENERATED_TOOLS } from '@/tools/generated/persons'
import type { Context } from '@/tools/types'

describe('Persons', { concurrent: false }, () => {
    let context: Context

    beforeAll(async () => {
        validateEnvironmentVariables()
        const client = createTestClient()
        context = createTestContext(client)
        await setActiveProjectAndOrg(context, TEST_PROJECT_ID!, TEST_ORG_ID!)
    })

    describe('persons-list tool', () => {
        const listTool = GENERATED_TOOLS['persons-list']!()

        it('should list persons with paginated results', async () => {
            const result = await listTool.handler(context, {})
            const response = parseToolResponse(result)

            expect(response.results).toBeTruthy()
            expect(Array.isArray(response.results)).toBe(true)
            expect(response._posthogUrl).toContain('/persons')

            if (response.results.length > 0) {
                const person = response.results[0]
                expect(Object.keys(person).sort()).toEqual(
                    ['created_at', 'distinct_ids', 'id', 'last_seen_at', 'name', 'properties', 'uuid'].sort()
                )
            }
        })

        it('should support pagination with limit and offset', async () => {
            const result = await listTool.handler(context, { limit: 2, offset: 0 })
            const response = parseToolResponse(result)

            expect(Array.isArray(response.results)).toBe(true)
            expect(response.results.length).toBeLessThanOrEqual(2)
        })

        it('should support search by email', async () => {
            // Find a person with an email property to use as a search term
            const allResult = await listTool.handler(context, { limit: 100 })
            const allResponse = parseToolResponse(allResult)
            const personWithEmail = allResponse.results.find((p: any) => p.properties?.email || p.properties?.$email)

            if (!personWithEmail) {
                console.warn('No persons with email found in project, skipping search by email test')
                return
            }

            const email = personWithEmail.properties.email ?? personWithEmail.properties.$email
            const result = await listTool.handler(context, { search: email })
            const response = parseToolResponse(result)

            expect(Array.isArray(response.results)).toBe(true)
            expect(response.results.length).toBeGreaterThan(0)

            // Verify only the dot-notation picked properties are present (no full properties blob leaked)
            const allowedProps = new Set(['email', '$email', '$geoip_country_code'])
            const person = response.results[0]
            for (const key of Object.keys(person.properties)) {
                expect(allowedProps).toContain(key)
            }
        })
    })

    describe('persons-retrieve tool', () => {
        const listTool = GENERATED_TOOLS['persons-list']!()
        const retrieveTool = GENERATED_TOOLS['persons-retrieve']!()

        it('should retrieve a person by ID', async () => {
            const listResult = await listTool.handler(context, { limit: 1 })
            const listResponse = parseToolResponse(listResult)

            if (listResponse.results.length === 0) {
                console.warn('No persons found in project, skipping retrieve test')
                return
            }

            const person = listResponse.results[0]
            const result = await retrieveTool.handler(context, { id: person.id })
            const retrieved = parseToolResponse(result)

            expect(retrieved.uuid).toBe(person.uuid)
            expect(retrieved.distinct_ids).toBeTruthy()
            expect(retrieved.properties).toBeTruthy()
            expect(retrieved._posthogUrl).toMatch(new RegExp(`/persons/${person.uuid}$`))
        })
    })

    describe('persons-values-retrieve tool', () => {
        const valuesTool = GENERATED_TOOLS['persons-values-retrieve']!()

        it('should return values for a person property key', async () => {
            const result = await valuesTool.handler(context, { key: 'email' })
            const response = parseToolResponse(result)

            expect(response.results).toBeTruthy()
            expect(Array.isArray(response.results)).toBe(true)
        })

        it('should filter values by search string', async () => {
            const result = await valuesTool.handler(context, { key: 'email', value: 'test' })
            const response = parseToolResponse(result)

            expect(response.results).toBeTruthy()
            expect(Array.isArray(response.results)).toBe(true)
        })
    })

    describe('persons-cohorts-retrieve tool', () => {
        const listTool = GENERATED_TOOLS['persons-list']!()
        const cohortsTool = GENERATED_TOOLS['persons-cohorts-retrieve']!()

        it('should return cohorts for a person', async () => {
            const listResult = await listTool.handler(context, { limit: 1 })
            const listResponse = parseToolResponse(listResult)

            if (listResponse.results.length === 0) {
                console.warn('No persons found in project, skipping cohorts test')
                return
            }

            const person = listResponse.results[0]
            const result = await cohortsTool.handler(context, { person_id: String(person.uuid) })
            const response = parseToolResponse(result)
            expect(response.results).toBeTruthy()
            expect(Array.isArray(response.results)).toBe(true)
        })
    })

    describe('persons-property-set tool', () => {
        const listTool = GENERATED_TOOLS['persons-list']!()
        const updatePropertyTool = GENERATED_TOOLS['persons-property-set']!()

        it('should set a property on a person', async () => {
            const listResult = await listTool.handler(context, { limit: 1 })
            const listResponse = parseToolResponse(listResult)

            if (listResponse.results.length === 0) {
                console.warn('No persons found in project, skipping update property test')
                return
            }

            const person = listResponse.results[0]
            const testKey = `mcp_test_prop_${Date.now()}`

            // The endpoint returns 202 Accepted with no body
            const result = await updatePropertyTool.handler(context, {
                id: person.id,
                key: testKey,
                value: 'test_value',
            })
            expect(result).toBeTruthy()
        })
    })

    describe('persons-property-delete tool', () => {
        const listTool = GENERATED_TOOLS['persons-list']!()
        const deletePropertyTool = GENERATED_TOOLS['persons-property-delete']!()

        it('should delete a property from a person', async () => {
            const listResult = await listTool.handler(context, { limit: 1 })
            const listResponse = parseToolResponse(listResult)

            if (listResponse.results.length === 0) {
                console.warn('No persons found in project, skipping delete property test')
                return
            }

            const person = listResponse.results[0]

            // The endpoint uses capture_internal to send an event, which may fail
            // in dev/CI environments where the ingestion pipeline isn't running
            try {
                const result = await deletePropertyTool.handler(context, {
                    id: person.id,
                    unset: 'mcp_test_prop_nonexistent',
                })
                expect(result).toBeTruthy()
            } catch (error: any) {
                expect(error.message).toMatch(/Unable to delete property|500/)
            }
        })
    })

    describe('persons workflow', () => {
        it('should support list, retrieve, get values, and get cohorts', async () => {
            const listTool = GENERATED_TOOLS['persons-list']!()
            const retrieveTool = GENERATED_TOOLS['persons-retrieve']!()
            const valuesTool = GENERATED_TOOLS['persons-values-retrieve']!()
            const cohortsTool = GENERATED_TOOLS['persons-cohorts-retrieve']!()

            // List persons
            const listResult = await listTool.handler(context, { limit: 5 })
            const listResponse = parseToolResponse(listResult)
            expect(Array.isArray(listResponse.results)).toBe(true)

            if (listResponse.results.length === 0) {
                console.warn('No persons found in project, skipping workflow test')
                return
            }

            // Retrieve a specific person
            const person = listResponse.results[0]
            const retrieveResult = await retrieveTool.handler(context, { id: person.id })
            const retrieved = parseToolResponse(retrieveResult)
            expect(retrieved.uuid).toBe(person.uuid)
            expect(retrieved.distinct_ids).toBeTruthy()

            // Get property values
            const valuesResult = await valuesTool.handler(context, { key: 'email' })
            const valuesResponse = parseToolResponse(valuesResult)
            expect(Array.isArray(valuesResponse.results)).toBe(true)

            // Get cohorts for the person
            const cohortsResult = await cohortsTool.handler(context, { person_id: String(person.uuid) })
            const cohortsResponse = parseToolResponse(cohortsResult)
            expect(cohortsResponse.results).toBeTruthy()
            expect(Array.isArray(cohortsResponse.results)).toBe(true)
        })
    })
})