Kiểm thử Cục bộ

Hướng dẫn này cho phép bạn kiểm thử gói đã được xây dựng giống hệt như cách người dùng cài đặt — không phải mã nguồn thô. Sử dụng trước khi xuất bản phiên bản mới, hoặc khi tái tạo lỗi mà người dùng đã báo cáo.

Điều kiện tiên quyết

TypeScript: Node 18+
Python: Python 3.10+ và pip
Thông tin AWS đã được cấu hình (hồ sơ imbrace) nếu bạn cần giải mã env vars từ Ansible

URL Môi trường

Cùng một tập hợp các URL cơ sở gateway áp dụng cho cả hai SDK. Đặt một lần trong môi trường kiểm thử của bạn:

Môi trường	`IMBRACE_GATEWAY_URL`
develop	`https://app-gateway.dev.imbrace.co`
sandbox	`https://app-gateway.sandbox.imbrace.co`
stable	`https://app-gatewayv2.imbrace.co`

Thông tin xác thực

Lấy thông tin xác thực trực tiếp từ Ansible (hoặc dán từ cổng thông tin):

# từ thư mục gốc của SDK repo
AWS_PROFILE=imbrace sops -d ansible/dev/secrets.enc.env | grep IMBRACE >> /tmp/imbrace.env

Tối thiểu cần thiết cho các lời gọi trực tiếp:

Biến	Nơi lấy
`IMBRACE_API_KEY`	Cổng thông tin Imbrace, hoặc `POST /private/backend/v1/third_party_token` với access token hiện có
`IMBRACE_GATEWAY_URL`	Một trong các URL trong bảng trên (mặc định là dev nếu không được đặt)

Ngữ cảnh tổ chức được mã hóa bên trong API key — bạn không cần truyền ID tổ chức.

TypeScript — liên kết thư mục dist đã xây dựng

Thiết lập một lần

cd ts
npm install
npm run build
npm link        # hiển thị @imbrace/sdk toàn cục

Sau đó trong thư mục kiểm thử:

cd ts/tests/local
npm link @imbrace/sdk
cp ../../.env.example .env
# điền .env

Chạy kiểm thử

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

Không có thông tin xác thực — chỉ chạy kiểm tra khởi tạo + bề mặt resource (không có mạng).
Có IMBRACE_API_KEY được đặt — chạy tất cả kiểm tra API trực tiếp với gateway trong IMBRACE_GATEWAY_URL.

Lặp lại khi thay đổi SDK

Mỗi lần chỉnh sửa cần xây dựng lại để liên kết nhận được thay đổi:

# terminal 1 — ts/
npm run dev          # tsc --watch

# terminal 2 — ts/tests/local
node test-local.mjs  # chạy lại bất kỳ lúc nào

Python — cài đặt từ wheel hoặc editable

Cài đặt editable (lặp nhanh nhất)

Từ thư mục py/:

cd py
pip install -e .

Các chỉnh sửa mã được nhận mà không cần cài đặt lại.

Cài đặt Wheel (xác minh hình dạng xuất bản)

cd py
python -m build               # tạo ra dist/imbrace-*.whl
pip install dist/imbrace-*.whl --force-reinstall

Điều này phát hiện các tệp bị thiếu, lỗi đóng gói và vấn đề đường dẫn import mà cài đặt editable che giấu.

Chạy kiểm thử

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

Để kiểm thử hồi quy luồng đầy đủ tương ứng với Hướng dẫn toàn diện (chạy từ thư mục gốc của repo):

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

Cùng một kiểm thử chạy với cả IMBRACE_API_KEY và IMBRACE_ACCESS_TOKEN để bao phủ cả hai chế độ xác thực.

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/

Khắc phục sự cố

Cannot find package '@imbrace/sdk' (TypeScript) Chạy npm link @imbrace/sdk từ trong thư mục kiểm thử lại. Liên kết có thể bị hỏng nếu bạn xóa và cài đặt lại node_modules trong ts/.

ERR_MODULE_NOT_FOUND cho tệp trong dist (TypeScript) Bản dựng chưa được chạy, hoặc tệp nguồn đã được thêm mà không xây dựng lại. Chạy npm run build trong ts/.

ModuleNotFoundError: No module named 'imbrace' (Python) Gói chưa được cài đặt trong venv đang hoạt động. Chạy lại pip install -e . (editable) hoặc pip install dist/imbrace-*.whl.

401 / 403 trên các lời gọi trực tiếp Thông tin xác thực của bạn đã hết hạn, bị thu hồi hoặc sai. Đối với API key, hãy tạo một key mới:

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

Đối với các lỗi thời gian chạy khác, xem Xử lý Lỗi và Khắc phục sự cố.