# Cách chạy test và evaluation

## Phân loại

**Loại tài liệu:** How-to.

**Reader job:** kiểm tra một thay đổi bằng các suite phù hợp và lưu bằng chứng
không nói quá phạm vi test.

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

- Python 3.12 khuyến nghị.
- Dependencies của `apps/ai-service` và `ingestion` đã cài.
- Node 20, pnpm 9 cho web.
- Không cần AWS cho unit test mặc định.

## Bước 1 — Chạy AI-service checks

```powershell
Set-Location apps/ai-service
ruff check .
python -m pytest tests -q
```

`tests/conftest.py` mặc định đặt `EMBEDDING_PROVIDER=disabled` trước collection,
nên unit suite không cần Qdrant. `test_live_datastores.py` tự skip trừ khi bật
integration.

## Bước 2 — Chạy ingestion suite

```powershell
Set-Location ../../ingestion
python -m pytest tests -q
```

Suite này kiểm tra extraction, segmentation, chunking, validation, provider
adapters và loader bằng doubles/in-memory store; nó không gọi Bedrock thật.

## Bước 3 — Chạy web checks

```powershell
Set-Location ..
pnpm --filter @duoc-thu/web lint
pnpm --filter @duoc-thu/web build
```

Hiện chưa có frontend test runner. Lint/build xanh không chứng minh request
timeout, citation grouping, middleware rate limit hoặc state UI không regression.

## Bước 4 — Chạy integration datastore khi cần

Khởi động PostgreSQL và Qdrant trước, rồi:

```powershell
Set-Location apps/ai-service
$env:RUN_INTEGRATION='1'
python -m pytest tests/test_live_datastores.py -q
Remove-Item Env:RUN_INTEGRATION
```

Ghi rõ integration environment và version Qdrant/PostgreSQL trong test record.

## Bước 5 — Chạy production/manual battery

Battery gọi endpoint thật và có thể phát sinh Bedrock cost:

```powershell
Set-Location apps/ai-service
python scripts/run_manual_battery.py `
  --base-url http://localhost:3000 `
  --target web `
  --output output/manual-battery.jsonl
```

Script là HTTP recorder với invariant checks, không phải LLM judge. Review các
failure và đối chiếu citation với PDF. Không ghi đè record cũ; tên output nên có
timestamp/commit SHA.

Để thử một subset, dùng `--start`, `--limit` hoặc `--ids` theo `--help`.

## Bước 6 — Ghi kết quả đúng phạm vi

Một test record tối thiểu gồm:

```text
commit SHA
ngày/giờ
command
environment/provider mode
passed / failed / skipped
evaluation cases đã chạy
artifact output
known exclusions
```

Không cộng `skipped` vào `passed`. Không dùng unit suite để tuyên bố chất lượng
lâm sàng hoặc live provider reliability.

## Verify

- AI-service ruff và pytest pass.
- Ingestion pytest pass.
- Web lint/build pass.
- Integration/manual result được ghi riêng nếu đã chạy.
- Không có cloud call ngoài ý muốn.

## CI hiện tại

`.github/workflows/ci.yml` chạy AI-service ruff/pytest, ingestion pytest và web
lint/build trên push và pull request. `deploy.yml` vẫn trigger độc lập; CI đỏ
không tự động chặn production deploy ở cấp workflow.

## Liên quan

- [Testing reference](../18-testing.md)
- [RAG evaluation](../19-rag-evaluation.md)
- [CI/CD](../22-ci-cd.md)