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.

19.9 KB
Raw Blame
import { describe, expect, test } from 'bun:test'
import { z } from 'zod'

import { runHog, TEST_CREDENTIALS } from '@/testing'

import { pushPlanLines } from './push'

const AGENT = { ...TEST_CREDENTIALS, CLAUDECODE: '1' }
const BASE = 'https://ph.example.com/api/environments/7/'

const endpoint = (
    name: string,
    query: Record<string, unknown>,
    extra: Record<string, unknown> = {}
): Record<string, unknown> => ({
    id: `id-${name}`,
    name,
    description: '',
    query,
    is_active: true,
    is_materialized: false,
    created_at: '2026-01-01T00:00:00Z',
    updated_at: '2026-01-01T00:00:00Z',
    ui_url: `https://ph.example.com/project/7/endpoints/${name}`,
    ...extra,
})

// A trends endpoint as PostHog returns it: nulls for unset fields, variables keyed by ID, and a
// refresh interval kept after materialization was turned off.
const TRENDS = endpoint(
    'weekly',
    {
        kind: 'TrendsQuery',
        interval: 'week',
        series: [{ kind: 'EventsNode', event: 'signed_up', math: null }],
        tags: null,
    },
    { data_freshness_seconds: 86400, description: 'Weekly signups' }
)
const HOGQL = endpoint('by-type', {
    kind: 'HogQLQuery',
    query: 'SELECT count()\r\nFROM events\r\nWHERE event = {variables.event_type}',
    variables: { 'var-1': { variableId: 'var-1', code_name: 'event_type', value: '$pageview' } },
})
// PostHog allows a variable without a code name, which no endpoint can use.
const VARIABLES = [
    { id: 'var-1', name: 'event_type', code_name: 'event_type', type: 'String' },
    { id: 'var-0', name: 'Old variable', code_name: null, type: 'String' },
]

function server(endpoints: unknown[], extra: (url: string, body: unknown) => unknown = () => undefined) {
    return (url: string, body: unknown) => {
        const reply = extra(url, body)
        if (reply) {
            return reply as { status: number; body: unknown }
        }
        if (url.replace(/\?.*/, '') === `${BASE}endpoints/`) {
            return { status: 200, body: { results: endpoints } }
        }
        if (url === `${BASE}insight_variables/`) {
            return { status: 200, body: { results: VARIABLES } }
        }
        return { status: 404, body: { detail: 'Not found.' } }
    }
}

const PULLED_WEEKLY =
    'name: weekly\ndescription: Weekly signups\nquery_definition:\n  kind: TrendsQuery\n  interval: week\n  series:\n    - kind: EventsNode\n      event: signed_up\n'

const PULLED_BY_TYPE = `# by-type.yaml
name: by-type
query: |-
  SELECT count()
  FROM events
  WHERE event = {variables.event_type}
variables:
  - name: event_type
    type: String
    default: $pageview
`

describe('hog endpoints', () => {
    test.each([
        ['', BASE],
        ['under a path', 'https://ph.example.com/posthog/api/environments/7/'],
    ])('list reads one page and gives agents the next offset, for a host %s', async (_name, base) => {
        const result = await runHog(['endpoints', 'list', '--limit', '1', '--offset', '1'], {
            env: { ...AGENT, HOG_HOST: new URL('../../../', base).toString() },
            respond: (url) =>
                url === `${base}endpoints/?limit=1&offset=1`
                    ? { status: 200, body: { count: 3, results: [HOGQL], next: `${base}endpoints/?limit=1&offset=2` } }
                    : { status: 404, body: {} },
        })

        expect(result.requests).toHaveLength(1)
        expect(result.json()).toMatchObject({ endpoints: [{ name: 'by-type' }], count: 3, nextOffset: 2 })
    })

    test('list tells a person the command for the next page', async () => {
        const result = await runHog(['endpoints', 'list', '--limit', '1'], {
            stdoutIsTTY: true,
            env: TEST_CREDENTIALS,
            respond: () => ({
                status: 200,
                body: { count: 2, results: [TRENDS], next: `${BASE}endpoints/?limit=1&offset=1` },
            }),
        })

        expect(result.stdout).toContain('Endpoints 1-1 of 2 in project 7')
        expect(result.stdout).toContain('Run hog endpoints list --offset 1 --limit 1 for the next page.')
    })

    test.each([
        ['stops at the page that holds every local name', false, [`${BASE}endpoints/`]],
        [
            'looks names up one by one in a project too large to read',
            true,
            [...Array.from({ length: 20 }, () => `${BASE}endpoints/`), `${BASE}endpoints/weekly/`],
        ],
    ])('diff %s', async (_name, endless, expectedUrls) => {
        const result = await runHog(['endpoints', 'diff', 'weekly.yaml'], {
            env: AGENT,
            files: { '/work/weekly.yaml': PULLED_WEEKLY },
            respond: (url) =>
                url === `${BASE}endpoints/weekly/`
                    ? { status: 200, body: TRENDS }
                    : {
                          status: 200,
                          body: { results: endless ? [HOGQL] : [TRENDS], next: `${BASE}endpoints/?offset=1` },
                      },
        })

        expect(result.exitCode).toBe(0)
        expect(result.requests.map((request) => request.url.replace(/\?.*/, ''))).toEqual(expectedUrls)
    })

    test('pull --all fails instead of pulling part of a project too large to read', async () => {
        const result = await runHog(['endpoints', 'pull', '--all', '--yes'], {
            env: AGENT,
            respond: () => ({ status: 200, body: { results: [TRENDS], next: `${BASE}endpoints/?offset=1` } }),
        })

        expect(result.error()).toMatchObject({ code: 'list_too_long' })
        expect(result.files).toEqual({})
    })

    test('pull refuses a pagination link to another host, so the token stays on the host', async () => {
        const result = await runHog(['endpoints', 'pull', '--all', '--dry-run'], {
            env: AGENT,
            respond: () => ({
                status: 200,
                body: { results: [TRENDS], next: 'https://ph.example.com//attacker.example/endpoints/' },
            }),
        })

        expect(result.error()).toMatchObject({ code: 'unexpected_response' })
        expect(result.requests.map((request) => new URL(request.url).host)).toEqual(['ph.example.com'])
    })

    test('pull writes short files with the project variable types, and updates a file in place', async () => {
        const result = await runHog(['endpoints', 'pull', '--all', '--yes'], {
            env: AGENT,
            files: {
                '/work/posthog.json': JSON.stringify({ endpoints: { dir: 'endpoints' } }),
                '/work/endpoints/signups.yaml': 'name: weekly\nquery_definition:\n  kind: TrendsQuery\n',
            },
            respond: server([TRENDS, HOGQL]),
        })
        expect(result.exitCode).toBe(0)
        expect(result.files['/work/endpoints/by-type.yaml']).toBe(PULLED_BY_TYPE)
        expect(result.files['/work/endpoints/signups.yaml']).toBe(`# signups.yaml\n${PULLED_WEEKLY}`)
        expect(result.files['/work/endpoints/weekly.yaml']).toBeUndefined()
    })

    test('pull takes variable types from the values when the key cannot read project variables', async () => {
        const result = await runHog(['endpoints', 'pull', 'by-type', '--yes'], {
            env: AGENT,
            respond: server([HOGQL], (url) =>
                url === `${BASE}insight_variables/` ? { status: 403, body: { detail: 'Forbidden' } } : undefined
            ),
        })

        expect(result.exitCode).toBe(0)
        expect(result.files['/work/by-type.yaml']).toBe(PULLED_BY_TYPE.replace('type: String', 'type: string'))
    })

    test.each([
        ['finds a variable on a late page by paging, without a request per variable', 25, 200, 'String', false],
        ['fetches a variable past the page cap by its ID', null, 200, 'String', true],
        ['takes the type from the value when the variable was deleted', null, 404, 'string', true],
    ])('pull %s', async (_name, foundOnPage, detailStatus, type, fetchesById) => {
        const result = await runHog(['endpoints', 'pull', 'by-type', '--yes'], {
            env: AGENT,
            respond: server([HOGQL], (url) => {
                if (url === `${BASE}insight_variables/var-1/`) {
                    return {
                        status: detailStatus,
                        body: detailStatus === 200 ? VARIABLES[0] : { detail: 'Not found.' },
                    }
                }
                if (!url.startsWith(`${BASE}insight_variables/`)) {
                    return undefined
                }
                const page = Number(new URL(url).searchParams.get('page') ?? '1')
                const results = page === foundOnPage ? [VARIABLES[0]] : []
                return { status: 200, body: { results, next: `${BASE}insight_variables/?page=${page + 1}` } }
            }),
        })

        expect(result.exitCode).toBe(0)
        expect(result.files['/work/by-type.yaml']).toBe(PULLED_BY_TYPE.replace('type: String', `type: ${type}`))
        expect(result.requests.some((request) => request.url.endsWith('/insight_variables/var-1/'))).toBe(fetchesById)
    })

    test.each([
        [
            'a file that defines another endpoint',
            { '/work/weekly.yaml': 'name: by-type\nquery: SELECT 1\n' },
            { '/work/weekly.yaml': PULLED_BY_TYPE.replace('# by-type.yaml', '# weekly.yaml') },
        ],
        [
            'a file hog cannot read',
            { '/work/weekly.yaml': 'name: weekly\nquery: [unclosed\n' },
            { '/work/weekly.yaml': 'name: weekly\nquery: [unclosed\n' },
        ],
    ])('pull never overwrites %s with another endpoint', async (_name, files, expected) => {
        const result = await runHog(['endpoints', 'pull', '--all', '--yes'], {
            env: AGENT,
            files,
            respond: server([TRENDS, HOGQL]),
        })
        expect(result.exitCode).toBe(1)
        expect(result.files).toMatchObject(expected)
        expect(result.json()).toMatchObject({ problems: [expect.objectContaining({ path: 'weekly.yaml' })] })
    })

    test.each([
        ['files that match PostHog', { 'by-type.yaml': PULLED_BY_TYPE }, 0, []],
        [
            'a changed query',
            { 'by-type.yaml': PULLED_BY_TYPE.replace('count()', 'count(*)') },
            1,
            [{ name: 'by-type', action: 'update', fields: ['query'] }],
        ],
        [
            // The file posthog-cli writes, with the lowercase type it infers from the default.
            'a posthog-cli file',
            { 'by-type.yaml': PULLED_BY_TYPE.replace('type: String', 'type: string') },
            0,
            [],
        ],
        [
            // PostHog keeps the refresh interval of an endpoint that is no longer materialized.
            'materialization turned off on both sides',
            { 'weekly.yaml': `${PULLED_WEEKLY}materialization:\n  enabled: false\n  schedule: 1hour\n` },
            0,
            [],
        ],
        [
            'a changed default',
            { 'by-type.yaml': PULLED_BY_TYPE.replace('default: $pageview', 'default: $autocapture') },
            1,
            [{ name: 'by-type', action: 'update', fields: ['defaults'] }],
        ],
        ['a file with a typo', { 'by-type.yaml': `${PULLED_BY_TYPE}descripton: oops\n` }, 1, []],
    ])('diff with %s', async (_name, files, exitCode, changed) => {
        const result = await runHog(['endpoints', 'diff'], {
            env: AGENT,
            files: {
                '/work/posthog.json': JSON.stringify({ endpoints: { dir: 'endpoints' } }),
                ...Object.fromEntries(Object.entries(files).map(([name, text]) => [`/work/endpoints/${name}`, text])),
            },
            respond: server([TRENDS, HOGQL]),
        })
        expect(result.exitCode).toBe(exitCode)
        const { plan } = result.json(
            z.object({
                plan: z.array(
                    z.object({
                        name: z.string(),
                        action: z.string(),
                        changes: z.array(z.object({ field: z.string() })),
                    })
                ),
            })
        )
        expect(
            plan
                .filter((item) => item.action !== 'skip')
                .map((item) => ({ name: item.name, action: item.action, fields: item.changes.map((c) => c.field) }))
        ).toEqual(changed)
    })

    test('pull escapes terminal control characters in the PostHog side of a preview', async () => {
        const edited = { ...TRENDS, description: '\u001b]52;c;eA==\u0007Weekly signups' }

        const result = await runHog(['endpoints', 'pull', 'weekly', '--dry-run'], {
            stdoutIsTTY: true,
            env: { ...TEST_CREDENTIALS, NO_COLOR: '1' },
            files: { '/work/weekly.yaml': PULLED_WEEKLY },
            respond: server([edited]),
        })

        expect(result.stdout).toContain('\\x1b]52;c;eA==\\x07Weekly signups')
        expect(result.stdout).not.toContain('\u001b')
    })

    test('push previews escape variable names and rejection reasons from PostHog', () => {
        const name = '\u001b]52;c;eA==\u0007x'
        const item = {
            name: 'weekly',
            path: 'weekly.yaml',
            action: 'skip' as const,
            reason: `${name} is used by the query`,
            changes: [],
            variables: [
                { name, change: 'remove' as const },
                { name, change: 'retype' as const, type: 'String', from: 'Number' },
            ],
        }

        const lines = pushPlanLines([item], (text) => text).join('\n')

        expect(lines).toContain('\\x1b]52;c;eA==\\x07x')
        expect(lines).not.toContain('\u001b')
    })

    test('push asks agents for --yes before it changes anything', async () => {
        const result = await runHog(['endpoints', 'push', 'new.yaml'], {
            env: AGENT,
            files: { '/work/new.yaml': 'name: new\nquery: SELECT 1\n' },
            respond: server([]),
        })
        expect(result.error().code).toBe('confirmation_required')
        expect(result.requests.filter((request) => request.method !== 'GET')).toEqual([])
    })

    test('push creates the variables a file needs, then the endpoint, and skips files PostHog would reject', async () => {
        const result = await runHog(['endpoints', 'push', 'endpoints', '--yes'], {
            env: AGENT,
            files: {
                '/work/endpoints/a.yaml': [
                    'name: by-country',
                    'query: SELECT count() FROM events WHERE properties.$geoip_country_code = {variables.country} AND properties.region IN {variables.regions}',
                    'variables:',
                    '  - name: country',
                    // posthog-cli writes lowercase types, and PostHog only accepts its own names.
                    '    type: string',
                    '    default: US',
                    '  - name: regions',
                    '    type: array',
                    '    default: [eu, us]',
                    'materialization:',
                    '  enabled: true',
                    '  schedule: 1hour',
                ].join('\n'),
                '/work/endpoints/b.yaml':
                    'name: unused\nquery: SELECT 1\nvariables:\n  - name: extra\n    type: String\n',
            },
            respond: server([], (url, body) =>
                url === `${BASE}insight_variables/` && body
                    ? {
                          status: 201,
                          body:
                              (body as { code_name: string }).code_name === 'country'
                                  ? { id: 'var-2', name: 'country', code_name: 'country', type: 'String' }
                                  : {
                                        id: 'var-3',
                                        name: 'regions',
                                        code_name: 'regions',
                                        type: 'List',
                                        is_multi: true,
                                    },
                      }
                    : url === `${BASE}endpoints/` && body
                      ? { status: 201, body: { ...endpoint('by-country', {}), ui_url: 'https://ph.example.com/e' } }
                      : undefined
            ),
        })
        expect(result.exitCode).toBe(1)
        expect(result.requests.filter((request) => request.method === 'POST').map((request) => request.body)).toEqual([
            { name: 'country', code_name: 'country', type: 'String', default_value: 'US' },
            // An array default makes a multiple-selection list, or PostHog keeps only its first value.
            { name: 'regions', code_name: 'regions', type: 'List', default_value: ['eu', 'us'], is_multi: true },
            {
                name: 'by-country',
                description: '',
                query: {
                    kind: 'HogQLQuery',
                    query: 'SELECT count() FROM events WHERE properties.$geoip_country_code = {variables.country} AND properties.region IN {variables.regions}',
                    variables: {
                        'var-2': { variableId: 'var-2', code_name: 'country', value: 'US' },
                        'var-3': { variableId: 'var-3', code_name: 'regions', value: ['eu', 'us'] },
                    },
                },
                is_materialized: true,
                data_freshness_seconds: 3600,
            },
        ])
        expect(result.json()).toMatchObject({
            outcomes: [{ name: 'by-country', status: 'created' }],
            plan: [{}, { name: 'unused', action: 'skip', invalid: true, reason: expect.stringContaining('extra') }],
        })
    })

    test.each([
        ['neither a name nor --file', ['endpoints', 'run'], 'usage_error'],
        ['a name and --file', ['endpoints', 'run', 'x', '--file', 'x.yaml'], 'usage_error'],
        ['a variable without a value', ['endpoints', 'run', 'x', '--var', 'country'], 'invalid_variable'],
    ])('run refuses %s', async (_name, argv, code) => {
        const result = await runHog(argv, { env: AGENT })
        expect(result.exitCode).toBe(2)
        expect(result.error().code).toBe(code)
    })

    test('run passes every --var to the endpoint', async () => {
        const result = await runHog(['endpoints', 'run', 'by-type', '--var', 'a=1', '--var', 'b=x=y'], {
            env: AGENT,
            respond: () => ({ status: 200, body: { columns: ['total'], results: [[3]] } }),
        })
        expect(result.requests[0]).toMatchObject({
            url: `${BASE}endpoints/by-type/run/`,
            body: { variables: { a: '1', b: 'x=y' } },
        })
        expect(result.stdout).toBe('[3]\n')
    })

    test('run --file puts variables in the query with their project IDs, and falls back to the file defaults', async () => {
        const result = await runHog(['endpoints', 'run', '--file', 'by-type.yaml', '--var', 'limit=5'], {
            env: AGENT,
            files: {
                '/work/by-type.yaml': `${PULLED_BY_TYPE.replace('count()', 'count() LIMIT {variables.limit}')}  - name: limit\n    type: Number\n`,
            },
            respond: server([], (url) =>
                url === `${BASE}insight_variables/`
                    ? {
                          status: 200,
                          body: {
                              results: [
                                  ...VARIABLES,
                                  { id: 'var-9', name: 'limit', code_name: 'limit', type: 'Number' },
                              ],
                          },
                      }
                    : url === `${BASE}query/`
                      ? { status: 200, body: { columns: ['n'], results: [[1]] } }
                      : undefined
            ),
        })
        expect(result.exitCode).toBe(0)
        expect(result.requests.at(-1)!.body).toMatchObject({
            query: {
                kind: 'HogQLQuery',
                variables: {
                    'var-1': { variableId: 'var-1', code_name: 'event_type', value: '$pageview' },
                    'var-9': { variableId: 'var-9', code_name: 'limit', value: '5' },
                },
            },
        })
        expect(result.requests.at(-1)!.body).not.toHaveProperty('variables')
    })
})