Auto Regression - Platform 自動化回歸測試

使用 Python + pytest-playwright，針對 T9 Platform 旗下多個遊戲站台進行端對端回歸測試，支援 Windows / WSL / Linux / CI 四種環境自動偵測。

支援站台

站台 ID	中文名	網址	測試數
rc	王老吉娛樂城	見 .env SITE_RC_URL	63
lt	LT 來財	見 .env SITE_LT_URL	109
re	BeWin	見 .env SITE_RE_URL	63
rd	狗狗娛樂城	見 .env SITE_RD_URL	58
API	(不限站台)	-	16
Dashboard	(後台)	-	3

測試數以 .venv/bin/pytest tests/<site>/ --collect-only -q 為準，會隨新增測試變動。

目錄結構

conftest.py                          — 全域 fixtures、環境偵測（Windows/WSL/Linux/CI）、MutationObserver 注入
config/settings.py                   — 多站台 SiteConfig，從 .env 讀取
pages/factory.py                     — 前台：site_id → LoginPage/HomePage 路由（registry dict）
pages/dashboard/factory.py           — 後台：site_id → DashboardLoginPage/ManagementPage 路由
pages/rc/, pages/lt/, pages/re/, pages/rd/   — 各站前台 Page Objects
pages/dashboard/<site_id>/           — 各站後台 Page Objects
tests/rc/, tests/lt/, tests/re/, tests/rd/   — 各站前台測試（含 test_p0_smoke.py + feature/）
tests/api/<site_id>/                 — API 層測試（不啟動瀏覽器，requests 直打 API）
tests/dashboard/<site_id>/           — 後台管理介面測試
utils/locale_helper.py               — set_locale()：注入 `i18n_locale` cookie（LT 用）
utils/dialog_helper.py               — 伺服器錯誤彈窗、公告彈窗（含 MutationObserver enforce killer）、Loading 等待
utils/screenshot_helper.py           — 截圖系統（元素高亮 + 自動產生繁中 README）
utils/visual_helpers.py              — VR reference 截圖 + 動態元素遮蔽
.github/workflows/                   — GitHub Actions（p0 / full-regression / docs-sync-check）
.github/scripts/                     — CI 共用 script（如 check-docs-sync.sh）
.claude/                             — Claude Code 配置（hooks / skills / agents，團隊共用）
docs/                                — 團隊共用文件（追蹤於 git）
dev-notes/                           — 個人開發筆記（gitignored，僅 README 追蹤）
screenshots/                         — 截圖與報告，自動分為 smoke/ 與 feature/（gitignored）
reports/report.html                  — pytest-html 測試報表（gitignored）

詳細的角色分工與架構決策見 CLAUDE.md；docs 子資料夾索引見 docs/README.md。

安裝

cp .env.example .env        # 填入站台帳號密碼與 CDP_URL
pip install -r requirements.txt
playwright install chromium

執行

請使用專案 virtualenv（.venv/）執行所有指令。

.venv/bin/pytest                                                          # 全部測試
.venv/bin/pytest tests/rc/                                               # rc 站
.venv/bin/pytest tests/lt/                                               # lt 站
.venv/bin/pytest tests/re/                                               # re 站
.venv/bin/pytest tests/rd/                                               # rd 站
.venv/bin/pytest tests/api/                                              # 僅 API 測試
.venv/bin/pytest tests/dashboard/                                        # 僅後台測試
.venv/bin/pytest tests/lt/test_p0_smoke.py -m p0                         # lt P0 smoke
.venv/bin/pytest -m p0                                                    # 所有站台 P0
.venv/bin/pytest -m "lt and i18n"                                        # lt 多語系測試
.venv/bin/pytest tests/rc/test_p0_smoke.py::TestLogin::test_login_success # 單一測試
CI=true .venv/bin/pytest tests/rc/test_p0_smoke.py                       # 模擬 CI 模式：headless chromium 直接 launch（無 CDP）

查看 HTML 報表

explorer.exe reports/report.html   # WSL

CI/CD

GitHub Actions 自動跑測試與 docs 同步檢查：

Workflow	觸發	跑什麼
.github/workflows/p0.yml	PR / push to main / daily 09:00 台灣 / 手動	4 站 P0 smoke matrix
.github/workflows/full-regression.yml	週一 08:00 台灣 / 手動	4 站全套（P0 + feature）
.github/workflows/docs-sync-check.yml	PR	code 變動是否同步更新 docs

操作細節（trigger 規則、cron 時段、secrets 清單、看 run / 下載 artifact / debug、docs sync check 操作 + override）見 docs/cicd.md。

WSL 設定

1. Windows Chrome 啟用 remote debugging

PowerShell（系統管理員）一次設好 portproxy（永久生效）：

netsh interface portproxy add v4tov4 listenport=9223 listenaddress=0.0.0.0 connectport=9223 connectaddress=127.0.0.1

2. 設定 .env

CDP_URL=http://<WINDOWS_IP>:9223

查詢 Windows IP：

ip route show | grep -i default | awk '{print $3}'   # WSL 預設 gateway = Windows host

3. 執行測試

conftest.py 偵測到 WSL 後，若 Chrome 尚未啟動會自動呼叫 chrome.exe --remote-debugging-port=9223，不需手動開啟瀏覽器。

完整 port forwarding / 防火牆說明見 PORTS_AND_SETUP.md。

環境對照

環境	瀏覽器啟動方式	conftest 分支
Windows	Playwright 直接啟動 Chrome	sys.platform == 'win32'
WSL	自動啟動 Windows Chrome，CDP 連接（port 9223）	_is_wsl()
純 Linux（非 CI）	手動啟動 Chrome --remote-debugging-port=9222，設 CDP_URL	else
CI（GitHub Actions）	Playwright 內建 chromium headless（無需 CDP）	_is_ci() → 由 CI=true env var 觸發

測試分級與 Markers

優先級

Marker	說明
p0	核心 Smoke，每次 Release 必跑
p1	功能驗證，重大版本必跑
p2	視覺/完整回歸

站台

Marker	站台
rc	rc 站（王老吉娛樂城）
lt	lt 站（LT 來財）
re	re 站（BeWin）
rd	rd 站（狗狗娛樂城）

功能 / 其他

Marker	說明
login / home / member / wallet	功能領域
i18n / language / copy	多語系 / 文案
visual / visual_regression / locale_layout	視覺
api / dashboard / game	測試類別
flaky	已知偶發 flaky，附理由
docker_only	僅 Docker 環境（pixel-level snapshot）

完整 markers 定義與測試分層、flaky 處理原則見 pytest.ini 與 docs/testing-strategy.md。

文件資源

路徑	用途
CLAUDE.md	Claude Code / agent 協作指南、慣例定義、架構說明
docs/	團隊共用的事實/策略/規格文件
docs/cicd.md	GitHub Actions 操作指南
docs/testing-strategy.md	測試分層、通過標準、flaky 處理
docs/i18n_locale_text_reference.md	多語系文案對照表（LT 5 + RC 6 + RD 5）
docs/agent-skills-workflow.md	Agent / skill / subagent 接力工作流
docs/lt-dashboard-sitemap.md	LT 後台 25 頁功能地圖
docs/dashboard-technical-notes.md	後台測試技術注意事項
PORTS_AND_SETUP.md	Port 轉發與環境設定
dev-notes/	個人開發筆記（gitignored）

說明

• 多站台支援：在 .env 增加 SITE_<X>_URL / USERNAME / PASSWORD，於 pages/<site_id>/ 建立 Page Objects，在 pages/factory.py 的 registry dict 註冊，再於 tests/<site_id>/ 建立測試目錄即可（dashboard 走 pages/dashboard/factory.py 同模式）
• 伺服器錯誤彈窗：conftest.py 內建 MutationObserver 注入，自動處理 rc 站的伺服器錯誤彈窗；lt 站在 tests/lt/conftest.py 覆寫 page fixture 關閉此注入（避免 lt 錯誤 dialog 撞同 selector）
• 截圖系統：每個測試自動截圖並高亮操作元素（紅框），存於 screenshots/<site_id>/<timestamp>/<smoke|feature>/<test_name>/，自動依測試路徑分類，並產生繁中操作流程 README
• 報表與截圖：reports/、screenshots/ 均已加入 .gitignore
• Docs sync check：commit 時自動檢查 code 變動有沒有對應 .md 更新（hook + CI 雙保險），見 docs/cicd.md