setup-web-tests

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Claude Code for web — test setup

网页版Claude Code — 测试环境搭建

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.

本文档介绍如何在无法使用flox的网页版Claude Code环境中搭建并运行Python测试。

如果按照本指南操作时遇到问题，请告知用户并寻求他们的指导。同时建议用户更新本指南。

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

项目的

pyproject.toml

中指定了特定的Python版本（查看

requires-python

字段），但：

网页版Claude Code环境的系统Python版本可能不同
如果uv尚未索引该版本，
```
uv python install <version>
```
可能会失败
```
uv sync
```
会强制要求严格匹配版本，Python版本错误时会运行失败

Solution: Download Python from python-build-standalone

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

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

pyproject.toml

bash

undefined

从python-build-standalone的GitHub发布页下载对应版本。以下脚本会自动从

pyproject.toml

中检测所需版本：

bash

undefined

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

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](https://github.com/astral-sh/python-build-standalone/releases) manually and look for a `cpython-<version>+<tag>-x86_64-unknown-linux-gnu-install_only.tar.gz` asset.

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


如果自动检测未找到对应下载链接（例如版本过新），可手动浏览[发布页](https://github.com/astral-sh/python-build-standalone/releases)，寻找名为`cpython-<version>+<tag>-x86_64-unknown-linux-gnu-install_only.tar.gz`的资源。

Install dependencies and run tests

安装依赖并运行测试

bash

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

bash

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

Run a specific test

pytest path/to/test.py::TestClass::test_method -v

Run all tests in a directory

pytest posthog/hogql/test/ -v

undefined

pytest posthog/hogql/test/ -v

undefined

Docker Services

Docker服务

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

bash

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.

大多数测试需要后端服务运行。如果环境支持Docker，可通过以下命令启动服务：

bash

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

查看

docker-compose.dev.yml

可获取完整的服务列表和端口信息。部分测试目录的特定服务要求会在其自身的配置文件中说明。

Hosts file setup

主机文件配置

Tests expect certain hostnames to resolve to localhost:

bash

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

测试要求特定主机名解析到本地回环地址：

bash

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

.env

for local development defaults.

测试需要的环境变量定义在

.github/workflows/ci-backend.yml

中（查看文件顶部的

env:

区域）。你也可以复制

.env.example

文件为

.env

，使用本地开发的默认配置。

Additional Setup

额外配置

Frontend dist placeholders

前端dist占位文件

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

bash

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

部分测试要求前端构建产物存在（即使是空文件）：

bash

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

SAML dependencies (if needed)

SAML依赖（按需安装）

For SAML-related functionality:

bash

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

若需使用SAML相关功能：

bash

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

Pytest Configuration

Pytest配置

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

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

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

若测试环境搭建遇到问题，可参考

.github/workflows/ci-backend.yml

中的权威CI配置。该文件展示了：

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

Limitations

局限性

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

无Docker支持：依赖服务的测试在无Docker环境下会失败
网络限制：下载Python需要能访问GitHub
Temporal测试：需要额外配置Temporal服务