Skip to content

Commit 6b25286

Browse files
nohungrynohungry
authored
docs: 更新 root README.md 反映現況 + script 警告清單補 root README (#57)
## README.md 更新（過時內容很多） ### 站台清單 - 補上 RE（BeWin）、RD（狗狗娛樂城）、Dashboard - 加站台中文名欄 - 測試數對齊現況（pytest --collect-only）： - rc 51 → 63、lt 93 → 109、API 2 → 16 - 新增 RE 63 / RD 58 / Dashboard 3 ### 目錄結構 - 補 pages/re/、pages/rd/、pages/dashboard/、pages/dashboard/factory.py - 補 tests/api/<site>/（不再寫死 lt）、tests/re/、tests/rd/、tests/dashboard/ - 補 .github/workflows/、.github/scripts/、.claude/、utils/visual_helpers.py - 砍過時項：tests/lt/__snapshots__/（已不存在）、tests/lt/test_locale_visual_matrix.py（已刪） - `utils/locale_helper.py` cookie name：i18n_redirected_lt → i18n_locale ### 執行範例 - 補 tests/re/ / tests/rd/ / tests/dashboard/ 命令 - 補 `CI=true` 模擬 CI 模式跑法 ### 新增 CI/CD 段 - 列出 3 個 workflow 與觸發規則 - 指向 docs/cicd.md 看細節 ### 環境對照表 - 加 CI 行（_is_ci() 分支說明） ### Markers 段 - 加站台 markers (rc/lt/re/rd) - 補 visual_regression / locale_layout / api / dashboard / game / flaky / docker_only ### 文件資源 - 加 docs/cicd.md / docs/agent-skills-workflow.md / docs/lt-dashboard-sitemap.md / docs/dashboard-technical-notes.md ### WSL 段 - portproxy 命令對齊現況（先前 9223 hardcoded 步驟更正） ### 說明段 - 加 Docs sync check 一行說明 ## script 警告清單補 root README `.github/scripts/check-docs-sync.sh` 警告 docs 候選清單原列 5 個（CLAUDE.md + docs/* 4 個），漏 root README.md。本次補上，避免日後同類遺漏。
1 parent a451135 commit 6b25286

2 files changed

Lines changed: 83 additions & 86 deletions

File tree

‎.github/scripts/check-docs-sync.sh‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,11 +37,12 @@ warn_block() {
3737
$(echo "$changed_code" | sed 's/^/ - /')
3838
3939
請重新確認下列 docs 是否需要同步更新：
40+
- README.md（repo 對外總覽：站台清單 / 測試數 / 目錄樹 / 執行指令）
4041
- CLAUDE.md（架構 / 慣例）
4142
- docs/cicd.md（CI/CD 觸發規則 / 操作）
4243
- docs/i18n_locale_text_reference.md（LT selector / i18n 對照表）
4344
- docs/testing-strategy.md（測試策略）
44-
- docs/README.md（文件索引）
45+
- docs/README.md（docs/ 子資料夾索引）
4546
4647
確認不需要更新時的 override 方式：
4748
- commit message 加 sentinel：[skip-docs-check] 並附理由

‎README.md‎

Lines changed: 81 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,46 @@
11
# Auto Regression - Platform 自動化回歸測試
22

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

55
## 支援站台
66

7-
| 站台 ID | 網址 | 測試數 |
8-
|---------|------|--------|
9-
| `rc` | 見 .env `SITE_RC_URL` | 51 |
10-
| `lt` | 見 .env `SITE_LT_URL` | 93（含 30 tests SKIP 中）|
11-
| API | - | 2 |
7+
| 站台 ID | 中文名 | 網址 | 測試數 |
8+
|---------|--------|------|--------|
9+
| `rc` | 王老吉娛樂城 | 見 .env `SITE_RC_URL` | 63 |
10+
| `lt` | LT 來財 | 見 .env `SITE_LT_URL` | 109 |
11+
| `re` | BeWin | 見 .env `SITE_RE_URL` | 63 |
12+
| `rd` | 狗狗娛樂城 | 見 .env `SITE_RD_URL` | 58 |
13+
| API | (不限站台) | - | 16 |
14+
| Dashboard | (後台) | - | 3 |
1215

13-
> 測試數以 `.venv/bin/pytest --collect-only -q` 為準，會隨新增測試變動。
16+
> 測試數以 `.venv/bin/pytest tests/<site>/ --collect-only -q` 為準，會隨新增測試變動。
1417
1518
## 目錄結構
1619

1720
```
18-
conftest.py — 全域 fixtures、環境偵測、MutationObserver 注入（rc 專用）
21+
conftest.py — 全域 fixtures、環境偵測（Windows/WSL/Linux/CI）、MutationObserver 注入
1922
config/settings.py — 多站台 SiteConfig，從 .env 讀取
20-
pages/factory.py — site_id → LoginPage/HomePage 路由（registry dict）
21-
pages/rc/ — rc 站 Page Objects
22-
pages/lt/ — lt 站 Page Objects
23-
tests/api/lt/ — lt 站 API 層測試（不啟動瀏覽器）
24-
tests/rc/ — rc 站測試
25-
├── conftest.py — rc 專屬：site_config 覆寫、go_home 含公告彈窗處理
26-
├── test_p0_smoke.py — p0 核心流程
27-
├── test_language.py — 多語系下拉結構驗證（暫留）
28-
└── feature/
29-
├── announcement_popup/ — 首頁公告彈窗測試
30-
├── i18n/ — 多語系文案（home/login/sidebar，6 語系）
31-
├── navigation/ — 分類導覽
32-
└── wallet/ — 餘額相關
33-
tests/lt/ — lt 站測試
34-
├── conftest.py — lt 專屬：site_config 覆寫、page fixture 不注入 MutationObserver
35-
├── test_p0_smoke.py — p0 核心流程
36-
├── test_locale_visual_matrix.py — 多語系截圖矩陣（全 SKIP，待定）
37-
├── __snapshots__/ — Visual Regression baseline（目前暫時廢棄）
38-
└── feature/
39-
├── auth/ — 登入後功能
40-
├── copy/ — 文案一致性（預設繁中）
41-
├── i18n/ — 多語系文案（home/login/drawer，5 語系）
42-
├── member/ — 會員功能（個人資料/收件匣/投注紀錄）
43-
├── public/ — 公開頁延伸（客服/版權/語系 icon）
44-
├── visual/ — DOM 視覺健康度 + VR reference 截圖
45-
└── wallet/ — 餘額/存款入口
46-
utils/locale_helper.py — set_locale()：注入 i18n_redirected_lt cookie
47-
utils/dialog_helper.py — 伺服器錯誤彈窗、公告彈窗、Loading 等待
23+
pages/factory.py — 前台：site_id → LoginPage/HomePage 路由（registry dict）
24+
pages/dashboard/factory.py — 後台：site_id → DashboardLoginPage/ManagementPage 路由
25+
pages/rc/, pages/lt/, pages/re/, pages/rd/ — 各站前台 Page Objects
26+
pages/dashboard/<site_id>/ — 各站後台 Page Objects
27+
tests/rc/, tests/lt/, tests/re/, tests/rd/ — 各站前台測試（含 test_p0_smoke.py + feature/）
28+
tests/api/<site_id>/ — API 層測試（不啟動瀏覽器，requests 直打 API）
29+
tests/dashboard/<site_id>/ — 後台管理介面測試
30+
utils/locale_helper.py — set_locale()：注入 `i18n_locale` cookie（LT 用）
31+
utils/dialog_helper.py — 伺服器錯誤彈窗、公告彈窗（含 MutationObserver enforce killer）、Loading 等待
4832
utils/screenshot_helper.py — 截圖系統（元素高亮 + 自動產生繁中 README）
33+
utils/visual_helpers.py — VR reference 截圖 + 動態元素遮蔽
34+
.github/workflows/ — GitHub Actions（p0 / full-regression / docs-sync-check）
35+
.github/scripts/ — CI 共用 script（如 check-docs-sync.sh）
36+
.claude/ — Claude Code 配置（hooks / skills / agents，團隊共用）
4937
docs/ — 團隊共用文件（追蹤於 git）
5038
dev-notes/ — 個人開發筆記（gitignored，僅 README 追蹤）
5139
screenshots/ — 截圖與報告，自動分為 smoke/ 與 feature/（gitignored）
52-
reports/report.html — pytest-html 測試報表
40+
reports/report.html — pytest-html 測試報表（gitignored）
5341
```
5442

55-
> 詳細分工與判斷原則請參考 [`docs/README.md`](docs/README.md) 與 [`dev-notes/README.md`](dev-notes/README.md)。
43+
> 詳細的角色分工與架構決策見 [`CLAUDE.md`](CLAUDE.md)；docs 子資料夾索引見 [`docs/README.md`](docs/README.md)。
5644
5745
## 安裝
5846

@@ -70,40 +58,43 @@ playwright install chromium
7058
.venv/bin/pytest # 全部測試
7159
.venv/bin/pytest tests/rc/ # rc 站
7260
.venv/bin/pytest tests/lt/ # lt 站
73-
.venv/bin/pytest tests/api/ # 僅 API 測試
61+
.venv/bin/pytest tests/re/ # re 站
62+
.venv/bin/pytest tests/rd/ # rd 站
63+
.venv/bin/pytest tests/api/ # 僅 API 測試
64+
.venv/bin/pytest tests/dashboard/ # 僅後台測試
7465
.venv/bin/pytest tests/lt/test_p0_smoke.py -m p0 # lt P0 smoke
7566
.venv/bin/pytest -m p0 # 所有站台 P0
7667
.venv/bin/pytest -m "lt and i18n" # lt 多語系測試
7768
.venv/bin/pytest tests/rc/test_p0_smoke.py::TestLogin::test_login_success # 單一測試
69+
CI=true .venv/bin/pytest tests/rc/test_p0_smoke.py # 模擬 CI 模式：headless chromium 直接 launch（無 CDP）
7870
```
7971

80-
### Visual Regression
81-
82-
LT 站目前採用 **reference screenshot** 策略（存檔供人工確認，不做 pixel 比對）：
72+
### 查看 HTML 報表
8373

8474
```bash
85-
# 執行 VR reference 截圖測試（輸出至 screenshots/lt/vr_reference/）
86-
.venv/bin/pytest tests/lt/feature/visual/test_visual_regression.py -m visual_regression
87-
88-
# DOM 層視覺健康度（非截圖）
89-
.venv/bin/pytest tests/lt/feature/visual/test_visual.py -m visual
75+
explorer.exe reports/report.html # WSL
9076
```
9177

92-
> `tests/lt/test_locale_visual_matrix.py`（WIN-LVIS）目前全部 `skip`，因 pixel-level 比對無法跨環境穩定運作。
93-
> `tests/lt/__snapshots__/` 為舊版 baseline 暫留，目前無測試引用。
78+
## CI/CD
9479

95-
### 查看 HTML 報表
80+
GitHub Actions 自動跑測試與 docs 同步檢查：
9681

97-
```bash
98-
explorer.exe reports/report.html # WSL
99-
```
82+
| Workflow | 觸發 | 跑什麼 |
83+
|---|---|---|
84+
| `.github/workflows/p0.yml` | PR / push to main / daily 09:00 台灣 / 手動 | 4 站 P0 smoke matrix |
85+
| `.github/workflows/full-regression.yml` | 週一 08:00 台灣 / 手動 | 4 站全套（P0 + feature） |
86+
| `.github/workflows/docs-sync-check.yml` | PR | code 變動是否同步更新 docs |
87+
88+
操作細節（trigger 規則、cron 時段、secrets 清單、看 run / 下載 artifact / debug、docs sync check 操作 + override）見 [`docs/cicd.md`](docs/cicd.md)。
10089

10190
## WSL 設定
10291

103-
### 1. 設定 Port Proxy（Windows PowerShell，系統管理員）
92+
### 1. Windows Chrome 啟用 remote debugging
93+
94+
PowerShell（系統管理員）一次設好 portproxy（永久生效）：
10495

10596
```powershell
106-
netsh interface portproxy add v4tov4 listenaddress=<WINDOWS_IP> listenport=9223 connectaddress=127.0.0.1 connectport=9223
97+
netsh interface portproxy add v4tov4 listenport=9223 listenaddress=0.0.0.0 connectport=9223 connectaddress=127.0.0.1
10798
```
10899

109100
### 2. 設定 .env
@@ -114,22 +105,23 @@ CDP_URL=http://<WINDOWS_IP>:9223
114105

115106
查詢 Windows IP：
116107
```bash
117-
cat /etc/resolv.conf | grep nameserver
108+
ip route show | grep -i default | awk '{print $3}' # WSL 預設 gateway = Windows host
118109
```
119110

120111
### 3. 執行測試
121112

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

124-
## 環境對照
115+
完整 port forwarding / 防火牆說明見 [PORTS_AND_SETUP.md](PORTS_AND_SETUP.md)。
125116

126-
| 環境 | 瀏覽器啟動方式 |
127-
|------|----------------|
128-
| Windows | Playwright 直接啟動 |
129-
| WSL | 自動啟動 Windows Chrome，透過 CDP 連接（port 9223） |
130-
| Linux | 手動啟動 Chrome `--remote-debugging-port=9222`，設定 `CDP_URL` |
117+
## 環境對照
131118

132-
Port 轉發與環境設定細節請參考 [PORTS_AND_SETUP.md](PORTS_AND_SETUP.md)。
119+
| 環境 | 瀏覽器啟動方式 | conftest 分支 |
120+
|------|----------------|----------------|
121+
| Windows | Playwright 直接啟動 Chrome | `sys.platform == 'win32'` |
122+
| WSL | 自動啟動 Windows Chrome，CDP 連接（port 9223） | `_is_wsl()` |
123+
| 純 Linux（非 CI） | 手動啟動 Chrome `--remote-debugging-port=9222`，設 `CDP_URL` | else |
124+
| **CI（GitHub Actions）** | **Playwright 內建 chromium headless（無需 CDP）** | **`_is_ci()` → 由 `CI=true` env var 觸發** |
133125

134126
## 測試分級與 Markers
135127

@@ -141,43 +133,47 @@ Port 轉發與環境設定細節請參考 [PORTS_AND_SETUP.md](PORTS_AND_SETUP.m
141133
| `p1` | 功能驗證，重大版本必跑 |
142134
| `p2` | 視覺/完整回歸 |
143135

144-
### 功能分類
136+
### 站台
145137

146-
| Marker | 說明 |
138+
| Marker | 站台 |
147139
|--------|------|
148-
| `login` | 登入相關 |
149-
| `home` | 首頁相關 |
150-
| `member` | 會員功能（個人資料/收件匣） |
151-
| `wallet` | 餘額/存款相關 |
152-
| `i18n` | 多語系文案驗證 |
153-
| `language` | 多語系切換行為 |
154-
| `copy` | 文案一致性（預設語系） |
155-
| `visual` | DOM 層視覺健康度（非截圖） |
156-
| `visual_regression` | 截圖 baseline / reference |
157-
| `locale_visual` | 多語系截圖矩陣 |
158-
| `api` | API 層測試（不啟動瀏覽器） |
140+
| `rc` | rc 站（王老吉娛樂城） |
141+
| `lt` | lt 站（LT 來財） |
142+
| `re` | re 站（BeWin） |
143+
| `rd` | rd 站（狗狗娛樂城） |
159144

160-
### 站台
145+
### 功能 / 其他
161146

162147
| Marker | 說明 |
163148
|--------|------|
164-
| `lt` | lt 站點（LT 來財）專屬測試 |
149+
| `login` / `home` / `member` / `wallet` | 功能領域 |
150+
| `i18n` / `language` / `copy` | 多語系 / 文案 |
151+
| `visual` / `visual_regression` / `locale_layout` | 視覺 |
152+
| `api` / `dashboard` / `game` | 測試類別 |
153+
| `flaky` | 已知偶發 flaky，附理由 |
154+
| `docker_only` | 僅 Docker 環境（pixel-level snapshot） |
165155

166-
> 完整 markers 定義請見 [`pytest.ini`](pytest.ini)。
156+
> 完整 markers 定義與測試分層、flaky 處理原則見 [`pytest.ini`](pytest.ini) 與 [`docs/testing-strategy.md`](docs/testing-strategy.md)。
167157
168158
## 文件資源
169159

170160
| 路徑 | 用途 |
171161
|------|------|
172-
| [`docs/`](docs/) | 團隊共用的事實/策略/規格文件（追蹤於 git） |
173-
| [`docs/i18n_locale_text_reference.md`](docs/i18n_locale_text_reference.md) | 多語系文案對照表（LT + RC） |
174-
| [`CLAUDE.md`](CLAUDE.md) | Claude Code 協作指南與慣例定義 |
162+
| [`CLAUDE.md`](CLAUDE.md) | Claude Code / agent 協作指南、慣例定義、架構說明 |
163+
| [`docs/`](docs/) | 團隊共用的事實/策略/規格文件 |
164+
| [`docs/cicd.md`](docs/cicd.md) | GitHub Actions 操作指南 |
165+
| [`docs/testing-strategy.md`](docs/testing-strategy.md) | 測試分層、通過標準、flaky 處理 |
166+
| [`docs/i18n_locale_text_reference.md`](docs/i18n_locale_text_reference.md) | 多語系文案對照表（LT 5 + RC 6 + RD 5） |
167+
| [`docs/agent-skills-workflow.md`](docs/agent-skills-workflow.md) | Agent / skill / subagent 接力工作流 |
168+
| [`docs/lt-dashboard-sitemap.md`](docs/lt-dashboard-sitemap.md) | LT 後台 25 頁功能地圖 |
169+
| [`docs/dashboard-technical-notes.md`](docs/dashboard-technical-notes.md) | 後台測試技術注意事項 |
175170
| [`PORTS_AND_SETUP.md`](PORTS_AND_SETUP.md) | Port 轉發與環境設定 |
176-
| [`dev-notes/`](dev-notes/) | 個人開發筆記（gitignored，僅 README 追蹤） |
171+
| [`dev-notes/`](dev-notes/) | 個人開發筆記（gitignored） |
177172

178173
## 說明
179174

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

0 commit comments

Comments
 (0)