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.

8.1 KB
Raw Blame
import { createHash } from 'node:crypto'
import { mkdtempSync, readdirSync, readFileSync, rmSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join, relative } from 'node:path'
import { z } from 'zod'

import { run } from '@/cli'
import { processRuntime } from '@/core/runtime'
import { readJson } from '@/testing'

import { startFakeServer } from './fake-server'
import { write } from './fixtures'
import { normalize } from './normalize'
import type { ParityScenario } from './scenarios'

// Strict, so a golden with a field hog doesn't produce fails the comparison instead of losing it.
const ParityResultSchema = z.strictObject({
    exitCode: z.number(),
    requests: z.array(
        z.strictObject({
            method: z.string(),
            path: z.string(),
            headers: z.record(z.string(), z.string()),
            body: z.string().optional(),
            upload: z
                .strictObject({
                    sha512: z.string(),
                    length: z.number(),
                    fields: z.record(z.string(), z.string()).optional(),
                    filename: z.string().optional(),
                })
                .optional(),
            status: z.number(),
        })
    ),
    // The files the run created or changed, and null for the ones it deleted.
    files: z.record(z.string(), z.string().nullable()).optional(),
})

export type ParityResult = z.output<typeof ParityResultSchema>

export function readGolden(name: string): ParityResult {
    return readJson(readFileSync(join(import.meta.dir, 'golden', 'e2e', `${name}.json`), 'utf8'), ParityResultSchema)
}

// posthog-cli reads the POSTHOG_CLI_ names and hog the HOG_ ones, so both CLIs get the same credentials.
function environment(serverUrl: string, home: string): Record<string, string> {
    return {
        HOME: home,
        POSTHOG_HOME: home,
        HOG_HOME: home,
        POSTHOG_CLI_API_KEY: 'phx_parity',
        POSTHOG_CLI_PROJECT_ID: '1',
        POSTHOG_CLI_HOST: serverUrl,
        HOG_PERSONAL_API_KEY: 'phx_parity',
        HOG_PROJECT_ID: '1',
        HOG_HOST: serverUrl,
        // hog runs on the real process runtime here, so without this every scenario would send usage
        // events, and every expected failure a real exception, to PostHog's own project.
        HOG_NO_TELEMETRY: '1',
        NO_COLOR: '1',
    }
}

const strictUtf8 = new TextDecoder('utf-8', { fatal: true })

// Files over this size are compared by hash, so goldens stay small. Smaller text files stay
// readable, so a golden diff shows what changed.
const INLINE_LIMIT = 2048

export function encodeFile(bytes: Uint8Array): string {
    try {
        return `utf8:${strictUtf8.decode(bytes)}`
    } catch {
        return `base64:${Buffer.from(bytes).toString('base64')}`
    }
}

export function decodeFile(text: string): Uint8Array {
    if (text.startsWith('sha512:')) {
        throw new Error('This golden stores the file as a hash. Record the scenario with `fullSnapshot`.')
    }
    return text.startsWith('utf8:') ? Buffer.from(text.slice(5), 'utf8') : Buffer.from(text.slice(7), 'base64')
}

// Only what differs from the inputs, so goldens don't repeat fixture files the run left alone.
// Random chunk ids become placeholders before a large file is hashed, so the hash still compares
// where the ids go. `full` keeps every file whole and unchanged, for scenarios others start from.
function changedFiles(
    folder: string,
    inputs: Record<string, string | Uint8Array>,
    options: { full: boolean; randomIds: boolean }
): Record<string, string | null> {
    const before: Record<string, string> = {}
    for (const [path, contents] of Object.entries(inputs)) {
        before[path] = encodeFile(typeof contents === 'string' ? Buffer.from(contents) : contents)
    }
    const after = snapshot(folder)
    let changed: Record<string, string | null> = {}
    for (const path of [...new Set([...Object.keys(before), ...Object.keys(after)])].sort()) {
        if (before[path] !== after[path]) {
            changed[path] = after[path] ?? null
        }
    }
    if (options.full) {
        return changed
    }
    if (options.randomIds) {
        changed = withoutRandomIds({ exitCode: 0, requests: [], files: changed }).files!
    }
    return Object.fromEntries(
        Object.entries(changed).map(([path, text]) => [
            path,
            text === null || text.length <= INLINE_LIMIT
                ? text
                : `sha512:${createHash('sha512').update(text).digest('hex')}`,
        ])
    )
}

function snapshot(folder: string): Record<string, string> {
    const files: Record<string, string> = {}
    const visit = (path: string): void => {
        for (const entry of readdirSync(path, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1))) {
            const entryPath = join(path, entry.name)
            if (entry.isDirectory() && entry.name !== '.git') {
                visit(entryPath)
            } else if (entry.isFile()) {
                files[relative(folder, entryPath)] = encodeFile(readFileSync(entryPath))
            }
        }
    }
    visit(folder)
    return files
}

async function invoke(
    args: string[],
    cli: { rust: string } | 'hog',
    folder: string,
    env: Record<string, string>
): Promise<number> {
    if (cli === 'hog') {
        const runtime = {
            ...processRuntime(),
            env,
            cwd: () => folder,
            stdinIsTTY: false,
            stdoutIsTTY: false,
            stdoutHasColors: false,
            writeStdout: () => {},
            writeStderr: () => {},
            // Retry delays don't change what is sent, so tests skip them.
            sleep: async () => {},
        }
        return run(args, runtime)
    }
    const child = Bun.spawn([cli.rust, ...args], {
        cwd: folder,
        env: { PATH: process.env.PATH ?? '', ...env },
        stdout: 'pipe',
        stderr: 'pipe',
    })
    return child.exited
}

export async function runScenario(scenario: ParityScenario, cli: { rust: string } | 'hog'): Promise<ParityResult> {
    const folder = mkdtempSync(join(tmpdir(), 'hog-parity-'))
    const home = mkdtempSync(join(tmpdir(), 'hog-parity-home-'))
    const inputs = scenario.files()
    write(folder, inputs)
    scenario.setup?.()
    const server = startFakeServer(scenario.server)
    server.store(scenario.objects?.() ?? [])
    try {
        const env = { ...environment(server.url, home), ...scenario.env }
        for (const step of scenario.before ?? []) {
            await invoke(cli === 'hog' ? step.hog : step.rust, cli, folder, env)
        }
        let exitCode = 0
        for (let index = 0; index < (scenario.runs ?? 1); index++) {
            server.requests.length = 0
            exitCode = await invoke(cli === 'hog' ? scenario.hog : scenario.rust, cli, folder, env)
        }
        return {
            exitCode,
            requests: normalize(server.requests),
            ...(scenario.snapshot
                ? {
                      files: changedFiles(folder, inputs, {
                          full: scenario.fullSnapshot === true,
                          randomIds: scenario.randomIds === true,
                      }),
                  }
                : {}),
        }
    } finally {
        server.stop()
        rmSync(folder, { recursive: true, force: true })
        rmSync(home, { recursive: true, force: true })
    }
}

const UUID_V7 = /[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}/g

// Symbol-set mode mints random UUIDv7 chunk ids. They become <v7-n>, numbered by first appearance in
// path order, so two runs compare equal when they put the same kind of id in the same places.
export function withoutRandomIds(result: ParityResult): ParityResult {
    const names = new Map<string, string>()
    const rename = (text: string): string =>
        text.replace(UUID_V7, (id) => {
            if (!names.has(id)) {
                names.set(id, `<v7-${names.size + 1}>`)
            }
            return names.get(id)!
        })
    return {
        ...result,
        files:
            result.files &&
            Object.fromEntries(
                Object.entries(result.files).map(([path, text]) => [path, text === null ? null : rename(text)])
            ),
    }
}