AI 測試驗證規範

部署完成後必跑：煙霧測試 + 瀏覽器測試 + 測試報告

用途

部署完成後，AI 必須主動執行完整測試，而不是丟下一句「已部署完成」就結束。測試分三階段：Smoke Test（指令驗證）→ Browser Test（實際操作）→ Test Report（markdown 測試報告）。

階段一：Smoke Test（煙霧測試）

用 curl 驗證基本連通性與關鍵端點。

必測項目

測試	指令	通過條件
HTTPS 連通	`curl -sI https://<site>.1gb.us/`	HTTP 200/301/302
首頁內容	`curl -s https://<site>.1gb.us/ \| head`	回傳預期 HTML（含 title 或關鍵字）
API 健康檢查	`curl -s https://<site>.1gb.us/health`	回 200 + `{"ok":true}` 類似內容
主要 API 端點	`curl -s https://<site>.1gb.us/api/...`	回傳符合 schema 的 JSON
靜態資源	`curl -sI https://<site>.1gb.us/assets/style.css`	HTTP 200、Content-Type 正確
404 行為	`curl -sI https://<site>.1gb.us/not-exist`	HTTP 404（有處理好）

資源檢查

Smoke test 同時驗證資源沒爆：

Response time < 3s（首次訪問可能冷啟動慢一點）
沒有 502/503/504（container 沒掛）
沒有 413（request 被 nginx 擋）

階段二：Browser Test（瀏覽器測試）

用瀏覽器自動化工具（Playwright / Puppeteer / Chrome MCP）做實際使用者操作。

必測流程

首頁載入：開啟 https://<site>.1gb.us/，等到 DOMContentLoaded
視覺截圖：截圖存檔（報告用）
Console 錯誤：確認沒有 JS error、沒有紅色 network error
關鍵互動：
- 有表單 → 填入測試資料 submit
- 有按鈕 → 點擊確認行為
- 有路由 → 切換頁面確認不 404
- 有登入 → 註冊/登入流程
Responsive 檢查：切換 mobile viewport 截一張圖
網路錄製：確認 API 請求都 200

工具	何時用
Chrome MCP（`mcp__chrome-devtools__*`）	AI 原生支援，首選
Playwright（`npx playwright`）	通用、截圖/錄影/網路錄製完整
Puppeteer	Node 專案內嵌用
curl + HTML parse	極簡靜態站用

失敗處理

任一步失敗 → 立即診斷，不要假裝通過
Container 掛了 → 看 log（可請 user 協助 docker logs <site>）
Port 接不到 → 檢查 deploy JSON 的 port 跟 Dockerfile EXPOSE 是否一致
資料遺失 → 檢查是否有寫到 /data/

階段三：Test Report（測試報告）

產出 markdown 格式測試報告，直接呈現在 chat 中給 user。

報告範本

# 部署測試報告 — <site>.1gb.us

**測試時間**：<ISO datetime>
**網址**：https://<site>.1gb.us
**技術棧**：<e.g. Hono + Drizzle + SQLite>
**Container**：<image name> / 200 MB limit
**總結**：✅ 全部通過 / ⚠️ 部分通過 / ❌ 失敗

---

## 1. Smoke Test

| 測試 | 結果 | 說明 |
|---|---|---|
| HTTPS 連通 | ✅ 200 | 0.4s |
| 首頁內容 | ✅ | 含預期 <title> |
| /health | ✅ | {"ok":true} |
| GET /api/posts | ✅ | 回 JSON array |
| 靜態資源 | ✅ | /assets/style.css 200 |
| 404 處理 | ✅ | 正確回 404 |

## 2. Browser Test

| 測試 | 結果 | 截圖 |
|---|---|---|
| 首頁載入 | ✅ | [desktop.png] |
| Console 無錯誤 | ✅ | — |
| 表單送出 | ✅ | [form-submit.png] |
| 新增資料後顯示 | ✅ | [after-create.png] |
| Mobile 畫面 | ✅ | [mobile.png] |
| API 網路請求 | ✅ | 所有 request 200 |

## 3. 發現的問題

（若有）
- ⚠️ 首頁 favicon 404（非阻塞）
- ⚠️ 首次載入 2.8s，冷啟動慢

## 4. 已驗證功能

- [x] 首頁渲染
- [x] 文章列表 API
- [x] 新增文章
- [x] 刪除文章
- [x] 資料持久化（/data/app.db）

## 5. 建議下一步

- 考慮加 favicon
- 首頁可加 loading state
- 資料庫建議跑一次 PRAGMA optimize

---

**結論**：可以交付給 user 使用 ✅

報告原則

誠實：失敗就標 ❌，不要為了好看灌水
可追溯：每個測試項目要能被 user 自己重跑
簡潔：表格 > 段落，能打 ✅/❌ 就不要長篇大論
截圖附上：如果有瀏覽器工具，至少附一張首頁截圖
有問題就講：哪怕不阻塞也要列出來，user 要知道現狀

禁止行為

❌ 不測就說「已完成」
❌ 只測 HTTP 200 就認為通過
❌ Container 起不來就改規格直到起得來（應該先診斷原因）
❌ 忽略 console error 和 network error
❌ 測試失敗不告訴 user 就嘗試掩蓋
❌ 報告裡只寫好事不寫壞事

建議執行順序

部署完成（讀 /deploy.html 執行）
等 3-5 秒讓 container 啟動
跑 Smoke Test，全過才進入下一步
跑 Browser Test，收集截圖和觀察
產出 markdown 測試報告呈現給 user
若有問題，問 user 是否要修；若全過，告知 user 可以開始使用

← 回到 1gb.us ｜開發規範｜部署指南