rhwp GUI Agent
使用此技能操控 rhwp-studio,它既是面向人類的網頁編輯器,也是可由代理控制的 GUI。功能檢查請優先使用真實 GUI 動作;僅在需要確認就緒狀態、檢查狀態、載入樣本及驗證匯出結果時,才使用 ?agent=1 橋接。
快速開始
從 rhwp 儲存庫根目錄執行:
cp .env.docker.example .env.docker
docker compose --env-file .env.docker run --rm wasm
cd rhwp-studio
npm ci
npm run build
python3 -m http.server 8765 --bind 0.0.0.0 -d dist
開啟 http://127.0.0.1:8765/?agent=1。如果沒有 ?agent=1,編輯器仍可供使用者操作,但不會暴露自動化橋接。
核心工作流程
- 執行 Studio 前,必須先建置
pkg/rhwp.js和pkg/rhwp_bg.wasm。如果npm run build顯示Cannot find module '@wasm/rhwp.js',表示 WASM 套件尚未建置。 - 提供建置後的應用程式,或執行 Vite。當 Vite 無法在沙箱中綁定埠號時,請使用
python3 -m http.server ... -d dist。 - 啟動瀏覽器自動化工作階段,連線至
/?agent=1。 - 使用 GUI 選擇器執行操作:
- 選單:
#menu-bar .menu-item[data-menu="<menu>"] .menu-title - 選單命令:
[data-cmd="<command-id>"] - 工具列按鈕:
.tb-btn[data-cmd="<command-id>"] - 樣式列控制項:
#style-name、#font-lang、#font-name、#font-size、#btn-bold、#btn-italic、#btn-underline、#btn-strike、#btn-text-color、#btn-highlight、對齊按鈕以及#linespacing-select - 檔案輸入:
#file-input - 畫布編輯器:
#scroll-container canvas
- 選單:
- 使用
window.__rhwpAgent進行觀察:ready()context()commands()pageCount()fileName()loadSample(path)loadBytes(bytes, fileName)createNewDocument()exportHwp()、exportHwpx()
- 在每個功能群組後擷取螢幕截圖和匯出的檔案。將點擊失敗、命令停用、主控台錯誤和空白畫布視為測試失敗。
功能涵蓋範圍
在列舉或測試所有 GUI 功能時,請參閱 references/feature-map.md。該檔案列出了頂層選單、命令 ID、對話框、工具列控制項以及 hwpctl 動作。
若要執行自動化冒煙測試,請使用:
cd rhwp-studio
node e2e/agent-gui-full-smoke.mjs
如果環境禁止啟動瀏覽器,仍可執行:
npm run build
然後檢視 e2e/agent-gui-full-smoke.mjs,並在支援瀏覽器的環境中執行它。
測試策略
使用三層測試:
- 建置驗證:
docker compose --env-file .env.docker run --rm wasm,接著npm run build。 - GUI 冒煙測試:新增文件、輸入文字、切換字元/段落格式、建立表格、開啟圖形選擇器、開啟符號對話框、載入
.hwp和.hwpx樣本、儲存/下載.hwp,並擷取螢幕截圖。 - 深度檢查:當有真實瀏覽器可用時,執行現有的
rhwp-studio/e2e/*.mjs測試與 hwpctl 情境。
優先使用內建樣本:
public/samples/basic/KTX.hwp
public/samples/form-002.hwpx
public/samples/BlogForm_BookReview.hwp
public/samples/biz_plan.hwp
public/samples/field-01.hwp
public/samples/footnote-01.hwp
public/samples/number-bullet.hwp
下載公開的 HWP/HWPX 樣本時,請將其儲存在 rhwp-studio/public/samples/external/ 下,載入前驗證檔案簽章,並記錄來源 URL、檔案名稱、位元組大小以及載入結果。
代理橋接規則
使用橋接來觀察狀態和載入可重複的測試固件,而非繞過 GUI 涵蓋範圍。對於像「表格建立功能正常」這類功能聲明,應點擊工具列/選單和對話框。對於像「文件已載入」這類聲明,使用 window.__rhwpAgent.pageCount() 是合適的。
不要僅因為命令出現在 HTML 中就假定它已實作。請與 src/command/commands/*.ts 交叉比對;某些選單項目是佔位符或會根據上下文停用。
常見失敗
listen EPERM:在允許的埠號上使用靜態伺服器,或在沙箱外執行。- 瀏覽器啟動失敗:在允許執行 Chrome/Chromium 的環境中執行腳本;必要時設定
CHROME_PATH。 - HWPX 儲存停用:在目前測試版路徑中,來源為 HWPX 的文件會出現此預期行為。
@wasm/rhwp.js遺失:使用 Docker 重建 WASM。- 無頭 Chrome 中無法使用 File System Access API:預期會回退至下載流程。