從 0 開始 · 路線 BFrom scratch · Track B
QA 工程師:從 0 跑出第一套測試QA engineer: run your first test suite from scratch
auto_cl 是 ContactLoop 的 E2E 自動化測試專案(Python + Playwright),跑通它就等於把 SW ↔ Ava 整條迴圈驗過一遍。目標:在本機跑出 stg 的綠燈報告。auto_cl is ContactLoop's E2E automation test project (Python + Playwright); running it green verifies the whole SW ↔ Ava loop. Goal: produce an all-green stg report on your machine.
測試覆蓋哪些事What the tests cover
| 測試檔Test file | 驗什麼What it checks |
|---|---|
test_ip.py | 最先跑,確認當前 IP 環境Runs first; confirms the current IP environment |
test_sw_nucleus.py | SW 登入 → 選帳號 → 匯入聯絡人 → 驗證首則 SMS 送達(Quo)→ 模擬 lead 發 5 句 → 登入 Ava 比對訊息一致SW login → pick account → import contacts → verify first SMS delivered (Quo) → simulate the lead sending 5 lines → log in to Ava and assert messages match |
test_sw_page_api_checks.py | 逐頁導航 SW 各核心頁面,攔截真實 XHR,驗狀態碼與關鍵欄位Navigates each core SW page, intercepts real XHRs, asserts status codes and key fields |
test_sw_segments.py | 匯入前後 segment count 增量驗證Verifies the segment count delta before/after import |
test_ava_link.py | 最後跑,Ava 對話中 Ava 發的連結有效性驗證Runs last; verifies the validity of Ava-sent links inside Ava conversations |
安裝步驟Install steps
# 1. 建立虛擬環境並安裝套件
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
# 2. 安裝 Playwright 瀏覽器
playwright install chromium
# 3. 複製環境變數範本並填入
cp .env.example .env # Windows: copy .env.example .env# 1. Create a venv and install deps
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
# 2. Install the Playwright browser
playwright install chromium
# 3. Copy the env template and fill it in
cp .env.example .env # Windows: copy .env.example .env
.env 必填欄位(以 stg 為例)Required .env fields (stg example)
| 變數Variable | 說明Description | 必填?Required? |
|---|---|---|
STG_SW_EMAIL / PASSWORD | stg 的 SW Manager 帳密stg SW Manager credentials | ✅ |
STG_AVA_EMAIL / PASSWORD | stg 的 Ava Messenger 帳密stg Ava Messenger credentials | ✅ |
QUO_API_KEY | Quo SMS API 金鑰(測 SMS 驗證用)Quo SMS API key (for SMS verification) | 跑 Nucleus 才需要Only for Nucleus |
QUO_phoneNumberId | 測試 lead 號碼的 Quo 內部 IDQuo internal ID of the test lead number | 跑 Nucleus 才需要Only for Nucleus |
QUO_participants_stg | stg 對應的 SW 端號碼(E.164)The SW-side number for stg (E.164) | 跑 Nucleus 才需要Only for Nucleus |
SMTP_EMAIL / PASSWORD | 測試結果通知信(Gmail App Password)Result notification email (Gmail App Password) | 要收信才需要Only if you want email |
TEAMS_WEBHOOK_URL | Teams 通知 webhookTeams notification webhook | 要 Teams 通知才需要Only for Teams notifications |
R2_* | Cloudflare R2(影片/報告上傳)Cloudflare R2 (video/report upload) | 要上傳才需要Only if uploading |
跑測試Run the tests
# Windows 先設編碼
$env:PYTHONUTF8=1
# 全部測試(自動排序:IP → Nucleus → 頁面 API → Segments → AvaLink)
pytest --env stg -v
# 只跑某一支
pytest tests/test_sw_segments.py --env stg -v
# 只跑 Ava 相關 / 排除 SMS
pytest -m Ava --env stg -v
pytest tests/test_sw_nucleus.py --env stg -v -m "not Sms"
# 跑單一方法
pytest tests/test_sw_segments.py::TestSW::test_sw_segments_count2 --env stg -v# On Windows, set encoding first
$env:PYTHONUTF8=1
# All tests (auto-ordered: IP → Nucleus → page API → Segments → AvaLink)
pytest --env stg -v
# Run a single file
pytest tests/test_sw_segments.py --env stg -v
# Ava only / exclude SMS
pytest -m Ava --env stg -v
pytest tests/test_sw_nucleus.py --env stg -v -m "not Sms"
# Run a single method
pytest tests/test_sw_segments.py::TestSW::test_sw_segments_count2 --env stg -v
📍
Account ID 不在 .env 裡。The Account ID isn't in .env.它是寫在 conftest.py 的 ENV_CONFIG 裡(例如 stg sw_nucleus.account_id=93)。換帳號要改程式碼,不是改 .env。各環境帳號請找主管或既有 auto_cl 維護者確認。 It lives in ENV_CONFIG inside conftest.py (e.g. stg sw_nucleus.account_id=93). Switching accounts means editing code, not .env. Ask your lead or the existing auto_cl maintainer for each environment's accounts.
產出物在哪Where the outputs land
reports/report.html— HTML 測試報告reports/report.html— HTML test reportreports/test.log— 完整 logreports/test.log— full logvideos/— 每次執行的單一連續影片(.webm,檔名帶環境與時間戳)videos/— one continuous video per run (.webm, filename carries env + timestamp)reports/ava_link_issues.json— Ava 連結異常(有異常才產生)reports/ava_link_issues.json— Ava link issues (only generated if any)reports/sw_page_api_issues.json— SW 頁面 API 檢查異常reports/sw_page_api_issues.json— SW page API check issuesreports/api_metrics.json— API 回應時間統計reports/api_metrics.json— API response time stats- 測試結束自動寄 Email / Teams 通知(若已設定)Auto-sends an Email / Teams notification when tests finish (if configured)