ContactLoop

內部上手指南 · 請先登入

沒有密碼?請向管理員索取。

QA 工程師

auto_cl 測試在做什麼

auto_cl 是 ContactLoop 的自動化測試:用程式開一個 Chromium 瀏覽器,像真人一樣登入 SW Manager 和 Ava Messenger、匯入聯絡人、收發簡訊、切換頁面,邊做邊檢查結果對不對;跑完自動產生報告、錄影,並發 Email 與 Teams 通知。用 Python + pytest + Playwright 寫的。怎麼安裝、怎麼跑,見 從 0 跑出第一套測試;這頁講「跑起來之後每一步在做什麼」。

1. 整個程式怎麼運作

flowchart TD
  A["執行 pytest --env=stg / cl1 / prod<br>(或 scripts/run_stg.sh 等)"] --> B["開場:清掉上一次留下的<br>問題紀錄檔"]
  B --> C["排順序:test_ip 排最前、<br>test_ava_link 排最後,其他依檔名"]
  C --> D["開一個 Chromium 瀏覽器<br>全程錄影 + 記錄所有網路請求"]
  D --> T1["① test_ip<br>確認這台電腦目前的 IP"]
  T1 --> T2["② test_api_metrics<br>API 效能統計工具的單元測試"]
  T2 --> T3["③ test_sw_nucleus<br>SW 匯入 → 簡訊 → 模擬回覆 → Ava 對照"]
  T3 --> T4["④ test_sw_page_api_checks<br>逐頁切換,檢查每頁打的 API"]
  T4 --> T5["⑤ test_sw_segments<br>匯入前後 Segment 人數有沒有正確增加"]
  T5 --> T6["⑥ test_ava_link<br>點 Ava 對話裡的連結,看打不打得開<br>(CircleCI 只在 prod 跑)"]
  T6 --> E["關閉瀏覽器,存影片<br>產生 report.html / junit.xml / test.log"]
  E --> F["收尾:整理 API 效能資料<br>(最慢的 5 支 API)"]
  F --> G["歸檔到 runs/ 並上傳報告、log、影片"]
  G --> H["寄 Email 結果通知"]
  H --> I{"有設定 Teams?"}
  I -->|有| J["發 Teams 通知"]
  I -->|沒有| K["結束"]
  J --> K

文字版。執行 pytest --env=環境(預設 stg)後:先清掉上次的問題紀錄檔 → 把測試排好順序(test_ip 最先、test_ava_link 最後,中間其他檔依檔名排序)→ 開一個 Chromium 瀏覽器,全程錄影並記錄網路請求 → 依序執行 6 個測試檔(所有測試共用同一個瀏覽器分頁)→ 關閉瀏覽器並把影片存到 videos/,產生報告 → 整理 API 效能資料 → 歸檔到 runs/ 並上傳 → 寄 Email,有設定的話再發 Teams 通知。瀏覽器預設會顯示畫面,設定 HEADLESS=true 才在背景跑。

💡

CircleCI 上 stg、cl1 不跑 ⑥ test_ava_link(設定裡用 --ignore 排除),只有 prod 會跑,所以 prod 報告比另外兩個多 3 項。自己在本機跑 pytest --env=stg 則 6 個檔都會跑。

💡

README 寫的順序少了一個檔。README 列 5 個測試檔,但實際上 test_api_metrics.py(單元測試,不開瀏覽器)也會跑,依檔名排在 test_sw_nucleus 前面。

2. 六個測試檔,依執行順序

#檔案在做什麼(步驟)
①test_ip.py開一個查 IP 的網頁,把這台電腦目前對外的 IP 記進 log。用來確認從哪個網路在跑(有些環境會限制來源 IP)。
②test_api_metrics.py「API 效能統計工具」本身的單元測試(網址正規化、平均與 P95 計算、存檔、讀取網路紀錄檔時的各種異常)。不開瀏覽器、不碰任何環境,幾秒就跑完。
③test_sw_nucleus.py最完整的端到端流程:1 SW 登入 → 2 選帳號 → 3 匯入一筆聯絡人 → 4 透過簡訊服務 Quo 讀簡訊,確認 SW 發出的第一則簡訊有送達(最多等約 5 分鐘)→ 5 模擬聯絡人連續回幾則訊息(從語句池隨機挑不重複的句子),每則都等到系統自動回覆才送下一則 → 6 Ava 登入 → 7 選帳號、打開那段對話、把訊息抓下來 → 8 比對:SW 的第一則訊息與模擬的回覆,在 Ava 對話頁上是不是都一字不差出現。
④test_sw_page_api_checks.py登入 SW、選帳號,然後一頁一頁切換 Contacts、Actions、Reports 等核心頁面,攔截每頁載入時打出去的 API,檢查狀態碼正常、回應是合法資料、而且有該有的欄位。測試報告上的 20 項就是這一檔,逐項說明在下面第 3 節。
⑤test_sw_segments.py1 SW 登入 → 2 選帳號 → 3 用 API 查一次各 Segment 的人數(匯入前)→ 4 匯入一筆聯絡人 → 5 等一下(cl1 等 60 秒、其他 30 秒)再查一次,檢查人數有沒有照規則增加:第 1 個 Segment 一定 +1;另外三個 Segment 分別在 email、姓氏、名字符合條件時 +1。用來確認「聯絡人進來後有被正確分到 Segment」。
⑥test_ava_link.py1 Ava 登入 → 2 逐一選帳號、進 Conversations、隨機抽幾段對話 → 3 點開每段對話裡 Ava 發出的連結,看能不能正常打開(打不開、跳到瀏覽器錯誤頁、或 HTTP 400 以上都算異常)。抽到的對話沒有 Ava 連結時,會從剩下的對話隨機補一段。異常會整理成表格放進通知。

③④⑤⑥ 都是「同一個瀏覽器分頁、照步驟往下走」:前一步失敗,後面依賴它的步驟通常也會跟著失敗,看報告時先找第一個失敗的步驟。

報告上每一項對應哪個檔(依報告順序)

#報告上的名稱項數說明
①test_ip1查 IP
②test_replaces_numeric_segments … test_skips_malformed_entry_without_crashing16API 效能統計工具的單元測試,每項幾毫秒。名稱裡的 segments 指的是「網址的片段」,跟 SW 的 Segment 無關
③test_sw_nucleus_login → test_sw_nucleus_select_account → test_import_contacts → test_verify_sms → test_simulate_lead_messages → test_ava_nucleus_login → test_ava_nucleus_select_account → test_compare_messages8對應上表 ③ 的 8 個步驟。test_verify_sms 約 30 秒、test_simulate_lead_messages 約 1 分半,是整套最花時間的部分之一
④test_login → test_select_account → test_page_triggers_expected_api[…] ×17 → test_actions_3month_range_completeness_not_capped20逐項說明見第 3 節
⑤test_sw_segments_login → test_sw_segments_select_account → test_sw_segments_count → test_import_contacts → test_sw_segments_count25count = 匯入前查人數,count2 = 匯入後再查並比對。test_import_contacts 在 ③ 和 ⑤ 各出現一次,是兩個不同檔的同名步驟
⑥test_ava_link_login → test_ava_link_select_and_filter → test_ava_link_click_links3只在 prod 報告出現;點連結那一步約 10 分鐘以上,是最久的一項

合計:stg、cl1 共 51 項,prod 共 54 項。

3. 測試報告上的 20 項(依報告順序)

這 20 項都來自 test_sw_page_api_checks.py。第 3~19 項做的事都一樣:打開那一頁 → 等那一頁該打的 API 出現 → 檢查回應;等不到或回應不對會重新整理再試,最多 3 次。同一頁常會連續打好幾次同一支 API,只要其中有一支正常就算通過。

#報告上的名稱檢查什麼stgcl1 / prod
1test_login登入 SWPassedPassed
2test_select_account選測試帳號,並記下選帳號時遇到的是新版還是舊版介面(舊版介面 → 後面的頁面檢查全部 Skipped)PassedPassed
3[Home]首頁有打出 Actions 或 Contacts 的資料 APIPassedPassed
4[Contacts-27]Contacts 打新版表格 API,回應有表格資料與總筆數PassedXPassed ¹
5[Contacts - Marketing Sources]同上(新版表格 API)PassedXPassed ¹
6[Contacts - Endpoint Attributes]同上PassedXFailed ²
7[Contacts - Technographics]同上PassedXFailed ²
8[Contacts - API]選單裡的「API」其實是 API 文件頁,檢查它有讀到帳號的 API Key 資料PassedPassed
9[Contacts (old)]舊版 Contacts 打舊版清單 API(一頁 20 筆),回應有聯絡人清單與分頁資訊PassedPassed
10[Contacts Grid (old)]舊的 Contacts Grid 頁打新版表格 APIPassedXFailed ³
11[Contacts-26 (old)]舊的 Contacts-26 頁打新版表格 APIPassedXFailed ³
12[Actions]Actions 打新版 Actions 表格 API,回應有總計(Total)與「資料是否完整」資訊PassedXFailed ⁴
13[Actions - Marketing Sources]這頁目前新舊兩支 API 都會打,檢查舊版那支有正常回應PassedPassed
14[Actions - Endpoint Breakdowns]打新版 Actions 表格 APIPassedXFailed ⁴
15[Actions - Technographics]同上PassedXFailed ⁴
16[Action Deep Dive]同上PassedXFailed ⁴
17[Action Report (legacy)]舊版 Action Report 打舊版報表 APIPassedPassed
18[Contact Report (legacy)]Contact Report 打聯絡人報表 APIPassedPassed
19[Visitor Report (legacy)]Visitor Report 打訪客報表 APIPassedPassed
20test_actions_3month_range_completeness_not_capped回歸測試:用近 3 個月的日期區間開 Actions,檢查回應說「資料沒有被截斷」。對應已知 bug(Trello f1cfO0nU:區間太大時 Total: Filtered 會失準)XPassed ⁵XFailed ⁵
  1. 1

    保險用的 xfail:這兩頁即使旗標關著通常也會打新版並通過,所以 cl1、prod 都顯示 XPassed。標記當初是為了保護 prod 第一次換新版時不要讓 CI 變紅;prod 換版後行為已跟 cl1 一樣。

  2. 2

    Contacts 新版功能的旗標在 cl1 / prod 沒開(功能還沒完成,刻意關著),所以這兩頁還在打舊版 API,攔不到新版的。不是測試程式壞掉、也不是部署慢,等旗標打開才會自動變 XPassed。

  3. 3

    在 cl1 版的前端,這兩個舊網址會直接轉到 Contacts-27,已經不是獨立頁面(SW 選單裡也已經拿掉);stg 還保留著。屬環境版本差異。

  4. 4

    Actions 新版功能的旗標在 cl1 / prod 沒開,這些頁還在打舊版 API。同 ²,旗標打開才會變 XPassed。

  5. 5

    已知 bug 的回歸測試,標記為 xfail。stg 目前跑出 XPassed(資料沒被截斷,代表 stg 上已經不再重現);cl1、prod 仍是 XFailed(還會截斷)。等每個環境都變 XPassed,就可以把這個標記拿掉。

上表是現行(2026-10-01)stg、cl1、prod 三份報告的結果,cl1 和 prod 完全相同。旗標打開、bug 修好或部署版本變動時結果會跟著變,看到跟上表不同時,先對照上面的註解判斷是「好消息」還是真的壞了。如果在第 2 項偵測到舊版介面,第 3~20 項會全部顯示 Skipped。

報告開頭那行數字怎麼看

例如 cl1:「ALL PASSED — 共 51 項:✅ 40 passed, ❌ 0 failed, ⚠️ 0 error」。passed 只算真正的 Passed,XFailed / XPassed 不算在裡面,所以 40 + 11(2 個 XPassed + 9 個 XFailed)= 51。只要 failed 和 error 都是 0,就會顯示 ALL PASSED。三個環境的現行數字:

環境共passedXPassedXFailed
stg515010
cl1514029
prod544329

4. 報告上的結果代號

代號意思要不要處理
Passed通過不用
Failed失敗,而且不是已知狀況要看:會被寫進問題紀錄檔,出現在 Email / Teams 通知的表格裡
XFailed「預期中」的失敗:已知的環境差異或已知 bug不用,不會讓 CI 變紅,也不會出現在通知的問題表格
XPassed原本預期會失敗,結果通過了好消息:代表旗標已經打開或 bug 已修,可以把那筆 xfail 標記拿掉
Skipped被略過(例如環境還是舊版介面)看原因,通常是正常的

5. 跑完會留下什麼

檔案 / 位置內容
reports/report.html測試報告(就是上面那 20 項那份),單一檔案可以直接用瀏覽器開
reports/junit.xml同樣的結果,給 CI 讀的格式
reports/test.log每一步的詳細紀錄,出錯時看這裡
videos/整次執行的錄影(檔名帶環境與時間)
reports/sw_page_api_issues.json、ava_link_issues.json頁面 API 檢查、Ava 連結檢查的問題清單(有問題才會產生;已知的 xfail 不算)
reports/api_metrics.json整次執行所有 API 的耗時統計,通知裡會列最慢的 5 支
runs/<run_id>/每次執行的歸檔(報告、log、執行資訊),也會上傳一份到雲端,通知裡附連結
Email / Teams 通知通過 / 失敗數量摘要、錯誤訊息、頁面 API 與 Ava 連結的問題表格、最慢的 5 支 API
⚠️

每次執行都會覆蓋 reports/ 裡的檔案,要留存請看 runs/ 的歸檔。另外,如果某次執行中途沒有產生新報告,歸檔時可能會帶到上一次的報告 —— 對照報告內容時,以報告裡實際的頁面網址判斷是哪個環境。