本地測試

本指南允許測試已建置的套件，方式與消費者從 npm 或 pip 安裝完全相同 — 而非原始原始碼。在發布新版本前，或重現消費者回報的 bug 時使用。

前提條件

TypeScript：Node 18+
Python：Python 3.10+ 和 pip
如需從 Ansible 解密環境變數，需設定 AWS credentials（profile imbrace）

環境 URL

相同的 gateway base URL 適用於兩個 SDK。在測試環境中設定一次：

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

憑證

從 Ansible 拉取實際憑證（或從 portal 貼上）：

# 從 SDK repo 根目錄
AWS_PROFILE=imbrace sops -d ansible/dev/secrets.enc.env | grep IMBRACE >> /tmp/imbrace.env

實際呼叫所需的最低設定：

變數	取得方式
`IMBRACE_API_KEY`	Imbrace Portal，或使用現有 access token 呼叫 `POST /private/backend/v1/third_party_token`
`IMBRACE_BASE_URL`	上表中的某個 URL（未設定時預設 dev）

Org context 已編碼在 API key 中 — 不需要傳遞 organization 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_BASE_URL 中的 gateway 執行完整實際 API 檢查。

SDK 更改的迭代流程

每次編輯都需要重新建置，連結才會使用新的 dist：

# 終端機 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 安裝隱藏的缺失檔案、打包 bug 和匯入路徑問題。

執行測試

cd py
pip install -r tests/requirements.txt
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 執行，以涵蓋兩種 auth 模式。

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

IMBRACE_BASE_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（dist 檔案）（TypeScript）套件尚未建置，或新增了新的原始碼檔案但未重新建置。在 ts/ 中執行 npm run build。

ModuleNotFoundError: No module named 'imbrace'（Python）套件未安裝在目前 venv 中。重新執行 pip install -e .（editable）或 pip install dist/imbrace-*.whl。

實際呼叫回傳 401 / 403 憑證已過期、被撤銷或錯誤。產生新的 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}'

其他執行時錯誤，參閱錯誤處理和問題排查。