本地测试

本指南让你测试构建后的包，就像消费者安装它一样 — 而不是原始源码。在发布新版本之前使用它，或者在复现消费者报告的错误时使用。

先决条件

TypeScript：Node 18+
Python：Python 3.10+ 和 pip
已配置 AWS 凭证（imbrace 配置文件），如果需从 Ansible 解密环境变量

环境 URL

相同的网关基础 URL 集适用于两个 SDK。在你的测试环境中设置一次：

环境	`IMBRACE_GATEWAY_URL`
develop	`https://app-gateway.dev.imbrace.co`
sandbox	`https://app-gateway.sandbox.imbrace.co`
stable	`https://app-gatewayv2.imbrace.co`

凭证

从 Ansible 拉取实时凭证（或从门户粘贴）：

# 从 SDK 仓库根目录
AWS_PROFILE=imbrace sops -d ansible/dev/secrets.enc.env | grep IMBRACE >> /tmp/imbrace.env

实时调用所需的最低要求：

变量	获取位置
`IMBRACE_API_KEY`	Imbrace 门户，或使用现有访问令牌调用 `POST /private/backend/v1/third_party_token`
`IMBRACE_GATEWAY_URL`	上表中的 URL 之一（未设置时默认为 dev）

组织上下文编码在 API Key 内部 — 你不需要传递组织 ID。

TypeScript — 链接构建后的 dist

一次性设置

cd ts
npm install
npm run build
npm link        # 将 @imbrace/sdk 暴露到全局

然后在测试文件夹中：

cd ts/tests/local
npm link @imbrace/sdk
cp ../../.env.example .env
# 填写 .env

运行测试

cd ts/tests/local
node test-local.mjs

没有凭证时 — 仅运行实例化 + 资源表面检查（无网络）。
设置了 IMBRACE_API_KEY 时 — 对 IMBRACE_GATEWAY_URL 中的网关运行所有实时 API 检查。

迭代 SDK 更改

每次编辑都需要重新构建，链接才能生效：

# 终端 1 — ts/
npm run dev          # tsc --watch

# 终端 2 — ts/tests/local
node test-local.mjs  # 随时重新运行

Python — 从 wheel 或 editable 安装

Editable 安装（最快迭代）

从 py/ 文件夹：

cd py
pip install -e .

代码编辑后无需重新安装即可生效。

Wheel 安装（验证发布形态）

cd py
python -m build               # 生成 dist/imbrace-*.whl
pip install dist/imbrace-*.whl --force-reinstall

这可以捕获 editable 安装隐藏的文件缺失、打包错误和导入路径问题。

运行测试

cd py
pip install -e ".[dev]"
python -m pytest tests/

对于镜像完整流程指南的全流程回归测试（从仓库根目录运行）：

cd test-pip-pkg/py
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m pytest tests/test_guide_flow.py -v

同样的测试以 IMBRACE_API_KEY 和 IMBRACE_ACCESS_TOKEN 两种认证模式运行。

IMBRACE_GATEWAY_URL=https://app-gateway.sandbox.imbrace.co node test-local.mjs

IMBRACE_GATEWAY_URL=https://app-gateway.sandbox.imbrace.co python -m pytest tests/

故障排除

Cannot find package '@imbrace/sdk' (TypeScript) 在测试文件夹中再次运行 npm link @imbrace/sdk。如果你在 ts/ 中删除并重新安装 node_modules，链接可能会断开。

ERR_MODULE_NOT_FOUND for a dist file (TypeScript) 构建还未运行，或者添加了源文件但没有重新构建。在 ts/ 中运行 npm run build。

ModuleNotFoundError: No module named 'imbrace' (Python) 包未安装在当前虚拟环境中。重新运行 pip install -e .（editable）或 pip install dist/imbrace-*.whl。

401 / 403 on live calls 你的凭证已过期、被撤销或错误。对于 API Key，生成一个新的：

curl -X POST https://app-gateway.dev.imbrace.co/private/backend/v1/third_party_token \
  -H "x-access-token: <your_existing_token>" \
  -H "Content-Type: application/json" \
  -d '{"expirationDays": 30}'

对于其他运行时错误，请参见错误处理和故障排除。