Hướng Dẫn Test

Cập nhật: 2026-04-10

Cài Đặt Môi Trường

Python SDK

cd py

# Cài dependencies + dev tools (pytest, ruff, mypy, pytest-httpx)
pip install -e ".[dev]"

Tạo file py/.env (chỉ cần cho integration test):

IMBRACE_API_KEY=api_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
IMBRACE_BASE_URL=https://app-gatewayv2.imbrace.co
IMBRACE_ORG_ID=org_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

TypeScript SDK

cd ts
npm install

---

Python — Lệnh Chạy & Test

Unit Tests (không cần API key)

cd py

# Chạy toàn bộ unit tests
pytest tests/unit -v

# Chạy một file cụ thể
pytest tests/unit/test_http.py -v
pytest tests/unit/resources/test_channel.py -v

# Chạy một test case cụ thể
pytest tests/unit/test_http.py::test_401_raises_auth_error -v

# Chạy theo keyword
pytest tests/unit -k "channel" -v
pytest tests/unit -k "boards" -v

Integration Tests (cần API key thật)

Kiểm thử tích hợp gọi thật tới API Gateway.

cd py

# Cách 1: Set key trực tiếp trong lệnh
IMBRACE_API_KEY=api_xxx pytest tests/integration -v -m integration

# Cách 2: Dùng .env (SDK tự đọc)
pytest tests/integration -v -m integration

Chạy tất cả (unit + integration)

pytest tests/ -v

Coverage Report

pytest tests/unit --cov=src/imbrace --cov-report=term-missing

---

TypeScript — Lệnh Chạy & Test

Build

cd ts

# Build một lần
npm run build

# Build watch mode (tự rebuild khi thay đổi)
npm run dev

# Xóa dist/
npm run clean

Unit Tests (không cần API key)

cd ts

# Chạy toàn bộ unit tests
npm test

# Chạy một file cụ thể
npx vitest run tests/unit/http.test.ts
npx vitest run tests/unit/resources/contacts.test.ts

# Watch mode (tự chạy lại khi code thay đổi)
npm run test:watch

Integration Tests (cần API key thật)

cd ts

IMBRACE_API_KEY=api_xxx npm run test:integration

Chạy tất cả (unit + integration)

npm run test:all

---

Chi Tiết Từng File Test

Python — Unit Tests

tests/unit/test_auth.py — TokenManager

Kiểm tra lưu/xóa token thread-safe.

Test case	Kiểm tra
test_initial_token_none	Token ban đầu là None
test_initial_token_set	Token được lưu từ constructor
test_set_token	Token thay đổi thành công
test_clear_token	Token bị xóa, get_token() → None
test_thread_safety	2 thread đọc/ghi đồng thời — không crash, không race condition

tests/unit/test_exceptions.py — Error classes

Loại lỗi	Khi nào xảy ra
AuthError	Server trả 401, 403
ApiError	Server trả 4xx, 5xx khác
NetworkError	Mất kết nối, timeout

Test case	Kiểm tra
test_hierarchy	Cả 3 đều là subclass của ImbraceError
test_api_error_message	status_code và message đúng format [404] Not Found
test_auth_error_is_catchable_as_imbrace_error	Bắt được bằng except ImbraceError

tests/unit/test_http.py — HttpTransport

Dùng pytest-httpx để giả lập server — không có request thật.

Test case	Kịch bản	Kiểm tra
test_get_success	Server trả 200	Response parse đúng
test_sets_api_key_header	Request với api_key	Header x-api-key có trong request
test_sets_bearer_token_header	Request với access token	Token đè lên api_key
test_401_raises_auth_error	Server trả 401	Raise AuthError, không retry
test_403_raises_auth_error	Server trả 403	Raise AuthError, không retry
test_404_raises_api_error	Server trả 404	Raise ApiError(status_code=404)
test_500_retries_then_raises	Server trả 500 liên tiếp	Retry 2 lần → tổng 3 request → raise ApiError
test_network_error_retries_then_raises	Mạng bị ngắt	Retry 2 lần → raise NetworkError

tests/unit/test_client.py — ImbraceClient

Test case	Kiểm tra
test_default_base_url	URL mặc định đúng
test_custom_base_url	Trailing slash bị strip
test_reads_api_key_from_env	Đọc IMBRACE_API_KEY từ env
test_explicit_api_key_overrides_env	Param trực tiếp ưu tiên hơn env
test_all_resources_initialized	Tất cả resources được khởi tạo
test_set_access_token	Token được cập nhật
test_context_manager	with block tự gọi close()

tests/unit/resources/ — Resource tests

File	Endpoint kiểm tra
test_account.py	GET /v1/backend/account
test_agent.py	GET/POST/PATCH/DELETE /v2/backend/templates
test_ai.py	AI completion, embedding, streaming
test_auth.py	OTP signin, verify, signout
test_boards.py	Board CRUD, items, search, export CSV
test_campaigns.py	Campaign CRUD, touchpoints list/get/create/update/delete/validate
test_channel.py	Channel list, get, delete, conv count
test_contacts.py	Contacts list, search, update, notifications
test_conversations.py	Views count, create, search
test_messages.py	List, send (text/image)
test_message_suggestion.py	POST /v1/message-suggestion — gợi ý câu trả lời AI
test_organizations.py	List, pagination, auth header
test_predict.py	POST /predict/ — chấm điểm ML
test_sessions.py	List sessions, directory filter
test_settings.py	Message templates, users, bulk invite
test_teams.py	List, my teams, add/remove users
test_workflows.py	List, tag filter, channel automation, create/update

---

Lint & Type Check

Python

cd py

# Kiểm tra code style
ruff check src/ tests/

# Tự fix lỗi ruff có thể sửa
ruff check src/ tests/ --fix

# Kiểm tra type annotations
mypy src/imbrace

TypeScript

cd ts

# Type check
npm run typecheck

# Lint
npm run lint

# Build (compile ra JS)
npm run build