本機測試

本指南讓您測試已建置的套件，完全按照使用者安裝的方式進行 — 而非原始原始碼。在發佈新版本之前，或在重現使用者回報的錯誤時使用。

先決條件

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 金鑰內部 — 您不需要傳遞組織 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 指向 dist 檔案（TypeScript）尚未執行建置，或新增了原始檔但未重新建置。在 ts/ 中執行 npm run build。

ModuleNotFoundError: No module named 'imbrace'（Python）套件未安裝在啟用的虛擬環境中。重新執行 pip install -e .（editable）或 pip install dist/imbrace-*.whl。

即時呼叫時出現 401 / 403 您的憑證已過期、被撤銷或錯誤。對於 API 金鑰，產生一個新的：

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}'

有關其他執行時期錯誤，請參閱錯誤處理和疑難排解。