PostHog Web测试环境设置指南：解决Python版本冲突与依赖安装

setup-web-tests by posthog/posthog

81 周安装量

32,400 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/posthog/posthog --skill setup-web-tests

Python Web框架开发测试

🇨🇳中文介绍

Claude Code for web — 测试设置

本文档描述了在无法使用 flox 的 Claude Code for web 环境中如何设置和运行 Python 测试。

如果在遵循这些说明时遇到困难，请退出并向用户寻求指导。建议他们更新本指南。

问题

项目在 pyproject.toml 中锁定了特定的 Python 版本（检查 requires-python），但是：

Claude Code for web 环境可能具有不同的系统 Python 版本
如果 uv 尚未索引该版本，uv python install <version> 可能会失败
uv sync 强制执行确切的版本约束，如果 Python 版本错误将会失败

解决方案：从 python-build-standalone 下载 Python

从 python-build-standalone GitHub 发布版下载确切的版本。以下脚本自动从 pyproject.toml 检测所需版本：

# Auto-detect the required version from pyproject.toml
REQUIRED_VERSION=$(grep requires-python pyproject.toml | grep -oP '[\d.]+')
echo "Required Python: $REQUIRED_VERSION"

# Get the latest release tag from python-build-standalone
RELEASE_TAG=$(curl -sL "https://api.github.com/repos/astral-sh/python-build-standalone/releases/latest" | grep '"tag_name"' | cut -d'"' -f4)

# Find and download the matching build
DOWNLOAD_URL=$(curl -sL "https://api.github.com/repos/astral-sh/python-build-standalone/releases/latest" | \
  grep "browser_download_url" | grep "$REQUIRED_VERSION" | grep "x86_64-unknown-linux-gnu-install_only.tar.gz" | head -1 | cut -d'"' -f4)

mkdir -p /tmp/python-install && cd /tmp/python-install
curl -L -o python.tar.gz "$DOWNLOAD_URL"
tar -xzf python.tar.gz

# Verify
/tmp/python-install/python/bin/python3 --version

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

安装依赖项并运行测试

cd /home/user/posthog
uv sync --python /tmp/python-install/python/bin/python3
source .venv/bin/activate

# Run a specific test (if hogli is available)
hogli test path/to/test.py::TestClass::test_method -v

# Or use pytest directly
pytest path/to/test.py::TestClass::test_method -v

# Run all tests in a directory
hogli test posthog/hogql/test/ -v

大多数测试需要后端服务运行。如果 Docker 可用，请使用以下命令启动它们：

docker compose -f docker-compose.dev.yml up -d

有关完整服务列表和端口，请参阅 docker-compose.dev.yml。一些测试目录在它们自己的配置文件中记录了特定的服务要求。

测试期望某些主机名解析到 localhost：

echo "127.0.0.1 kafka clickhouse clickhouse-coordinator objectstorage" | sudo tee -a /etc/hosts

测试需要环境变量，定义在 .github/workflows/ci-backend.yml 中（参见文件顶部的 env: 部分）。您也可以将 .env.example 复制为 .env 以获取本地开发默认值。

前端 dist 占位符

某些测试要求前端构建产物存在（即使为空）：

mkdir -p frontend/dist
touch frontend/dist/index.html
touch frontend/dist/layout.html
touch frontend/dist/exporter.html

SAML 依赖项（如果需要）

对于 SAML 相关功能：

sudo apt-get update
sudo apt-get install libxml2-dev libxmlsec1-dev libxmlsec1-openssl

pytest.ini 设置了：

pythonpath = . common
DJANGO_SETTINGS_MODULE = posthog.settings
DEBUG=1, TEST=1

默认忽略项：--ignore=posthog/user_scripts --ignore=services/llm-gateway --ignore=common/ingestion/acceptance_tests

如果遇到测试设置问题，请参考 .github/workflows/ci-backend.yml 以获取权威的 CI 配置。该文件显示了：

CI 中使用的确切 Python 版本
安装的系统依赖项
设置的环境变量
Docker 服务配置
测试执行命令

Docker 不可用：需要服务的测试在没有 Docker 的情况下会失败
网络限制：下载 Python 需要访问 GitHub
Temporal 测试：需要额外的 Temporal 服务设置

🇺🇸English

Claude Code for web — test setup

This document describes how to set up and run Python tests in a Claude Code for web environment, where flox is not available.

If you get stuck following these instructions, please bail out to the user and seek their guidance. Please suggest that they update this guide.

Problem

The project requires a specific Python version pinned in pyproject.toml (check requires-python), but:

Claude Code for web environments may have a different system Python version
uv python install <version> may fail if the version isn't yet indexed by uv
uv sync enforces the exact version constraint and will fail with the wrong Python version

Solution: Download Python from python-build-standalone

Download the exact version from python-build-standalone GitHub releases. The script below auto-detects the required version from pyproject.toml:

# Auto-detect the required version from pyproject.toml
REQUIRED_VERSION=$(grep requires-python pyproject.toml | grep -oP '[\d.]+')
echo "Required Python: $REQUIRED_VERSION"

# Get the latest release tag from python-build-standalone
RELEASE_TAG=$(curl -sL "https://api.github.com/repos/astral-sh/python-build-standalone/releases/latest" | grep '"tag_name"' | cut -d'"' -f4)

# Find and download the matching build
DOWNLOAD_URL=$(curl -sL "https://api.github.com/repos/astral-sh/python-build-standalone/releases/latest" | \
  grep "browser_download_url" | grep "$REQUIRED_VERSION" | grep "x86_64-unknown-linux-gnu-install_only.tar.gz" | head -1 | cut -d'"' -f4)

mkdir -p /tmp/python-install && cd /tmp/python-install
curl -L -o python.tar.gz "$DOWNLOAD_URL"
tar -xzf python.tar.gz

# Verify
/tmp/python-install/python/bin/python3 --version

If the auto-detection doesn't find a URL (e.g., the version is too new), browse the releases page manually and look for a cpython-<version>+<tag>-x86_64-unknown-linux-gnu-install_only.tar.gz asset.

Install dependencies and run tests

cd /home/user/posthog
uv sync --python /tmp/python-install/python/bin/python3
source .venv/bin/activate

# Run a specific test (if hogli is available)
hogli test path/to/test.py::TestClass::test_method -v

# Or use pytest directly
pytest path/to/test.py::TestClass::test_method -v

# Run all tests in a directory
hogli test posthog/hogql/test/ -v

Docker Services

Most tests require backend services running. If Docker is available, start them with:

docker compose -f docker-compose.dev.yml up -d

See docker-compose.dev.yml for the full list of services and ports. Some test directories have specific service requirements documented in their own configuration files.

Hosts file setup

Tests expect certain hostnames to resolve to localhost:

echo "127.0.0.1 kafka clickhouse clickhouse-coordinator objectstorage" | sudo tee -a /etc/hosts

Environment Variables

Tests require environment variables defined in .github/workflows/ci-backend.yml (see the env: section at the top of the file). You can also copy .env.example to .env for local development defaults.

Additional Setup

Frontend dist placeholders

Some tests require frontend build artifacts to exist (even if empty):

mkdir -p frontend/dist
touch frontend/dist/index.html
touch frontend/dist/layout.html
touch frontend/dist/exporter.html

SAML dependencies (if needed)

For SAML-related functionality:

sudo apt-get update
sudo apt-get install libxml2-dev libxmlsec1-dev libxmlsec1-openssl

Pytest Configuration

The pytest.ini sets:

pythonpath = . common
DJANGO_SETTINGS_MODULE = posthog.settings
DEBUG=1, TEST=1

Default ignores: --ignore=posthog/user_scripts --ignore=services/llm-gateway --ignore=common/ingestion/acceptance_tests

Debugging Installation Issues

If you encounter issues with the test setup, refer to .github/workflows/ci-backend.yml for the authoritative CI configuration. This file shows:

Exact Python version used in CI
System dependencies installed
Environment variables set
Docker services configuration
Test execution commands

Limitations

Docker unavailable : Tests requiring services will fail without Docker
Network restrictions : Downloading Python requires GitHub access
Temporal tests : Require additional Temporal service setup

Weekly Installs

Repository

posthog/posthog

GitHub Stars

32.4K

First Seen

Feb 12, 2026

Security Audits

Gen Agent Trust HubWarn SocketPass SnykWarn

Installed on

gemini-cli79

opencode79

cursor78

claude-code78

github-copilot78

amp78

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

166,500 周安装