
r-shiny-debugger
功能測試導向的 R Shiny App Debug 工具,整合 agent-browser(前端)與 R console(後端)+ shiny-adaptive-walk 自我收斂測試 loop + connect-cloud-logs 部署後 Posit Connect Cloud runtime log 診斷。/shiny-adaptive-walk default browser inverted to agent-browser (safari opt-in via --browser safari) since v1.2.0 (#77).
- version
- 1.3.0
Install
/plugin install r-shiny-debugger@psychquant-claude-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add PsychQuant/psychquant-claude-plugins.
Contents
Discovered from sourceCommands 3
Connect Cloud Logs
抓取 Posit Connect Cloud(SaaS,connect.posit.cloud)部署後的後端 runtime log,診斷部署後才出現的 lag / crash / 資料異常 bug。
這是
/shiny-debug(local app)的 remote 部署版。local Shiny log 在.shiny-debug/shiny.log;Connect Cloud 的等價物是 web UI 的 Logs 面板(你截圖底部那塊),本 command 把它自動化。
⚠️ 核心事實(2026-06-23 spike 驗證)
| 事實 | 來源 |
|---|---|
| Connect Cloud 沒有 programmatic log API / CLI / API key | 官方 docs.posit.co/connect-cloud system 文件確認 |
網路上的 CONNECT_API_KEY / connectapi R package / curl 抓 log / usermanager CLI 全是 self-hosted Posit Connect,不適用 Cloud SaaS | 兩個是不同產品 |
| Cloud log 只能從 web UI 的 Logs 面板看 → 只能 browser 自動化 | — |
| Logs 面板是 React virtualized list — DOM 只渲染 viewport 內幾行(~12 行),要滾動累積才抓得到完整 log | spike 觀察 |
Metrics(CPU / 記憶體 / 連線曲線)是圖,只能 screenshot,讀不到數值 | spike 觀察 |
敏感欄位(Port / Database / User / password)已被 ***REDACTED*** | Connect Cloud 安全功能,正常 |
所以 lag bug 診斷:lag 通常不跳紅字,重點看 metrics 曲線 + log timestamp gap(哪兩行之間 gap 異常大)。必要時在 R code 嫌疑處埋 message(Sys.time(), " ...") 再 redeploy。
兩條路徑(按情境選)
| Path A: safari-browser(主路、推薦) | Path B: agent-browser(進階) | |
|---|---|---|
| 何時用 | 快速看 log、spot-check、不需要 network | 要看 network(lag = 慢 XHR)、要背景 headless |
| 登入持久 | ✅ 真實 Safari,cookie 天然持久,登一次永久 | ⚠️ 需 state save/load(見下方「auth 設定」) |
| 干擾 | 用到 Safari 視窗(--url lock 控) | 不干擾(但 instance 模型 fragile) |
| 平台 | macOS only | 跨平台 |
| 看 network | ❌ | ✅ agent-browser network |
預設走 Path A。 只有要看 network request timing(診斷某個 API/DB call 慢)才用 Path B。
Step 0:前置 + 取得 content URL
which safari-browser || echo "Path A 需要 safari-browser"
which agent-browser || echo "Path B 需要 agent-browser"
取得目標公司的 Connect Cloud content。優先讀 .claude/companies.yaml(每公司的 deployed URL + metadata):
# 從 l4_enterprise 專案根目錄
grep -iE "url|connect|content" .claude/companies.yaml 2>/dev/null
- Connect Cloud 主控台(看 log 的管理介面):
https://connect.posit.cloud/ - 已知 live app URL 範例:MAMBA =
https://kyleyhl-ai-martech-l4-mamba.share.connect.posit.cloud/ $ARGUMENTS給了公司名(如QEF_DESIGN)→ 用它對應 content
Path A:safari-browser(主路)
A1. 開主控台 + 登入(一次性,cookie 持久)
LOCK=(--url connect.posit.cloud)
safari-browser open "https://connect.posit.cloud/" "${LOCK[@]}"
Tab lock 紀律(CRITICAL):一律用 bash array
LOCK=(--url connect.posit.cloud)+"${LOCK[@]}"。 不要寫LOCK="--url x"+ 未引號$LOCK— zsh 不 word-split,會報Unknown option(Claude Code Bash 跑在 zsh)。
若未登入 → 請使用者在 Safari 手動完成 OAuth 登入(不能代點)。Safari cookie 持久,之後不用再登。
A2. 導航到 content 的 Logs 面板
# snapshot 找 content 連結(refs 是 per-snapshot 臨時值,每次重新取)
safari-browser snapshot -i "${LOCK[@]}"
# 點進目標 content(ref 依 snapshot 結果)
safari-browser click @eN "${LOCK[@]}"
safari-browser wait 3000 "${LOCK[@]}"
開 Logs 面板:右側欄 Logs 圖示,或按 ~ 鍵:
safari-browser press "~" "${LOCK[@]}" # 或 click Logs icon 的 ref
safari-browser wait 2000 "${LOCK[@]}"
A3. 抓 log(處理 virtualized list)
⚠️ virtualized list 只渲染 viewport 內幾行。要抓完整 log 必須往上滾 + 累積去重,不能一次 snapshot 就當抓全(那是 silent truncation):
# 先抓當前可見
safari-browser snapshot "${LOCK[@]}" > /tmp/cclog_0.txt
# 往上滾載入更早的 log,逐段抓(N 依需要的歷史長度)
for i in 1 2 3 4 5; do
safari-browser scroll up 600 "${LOCK[@]}"
safari-browser wait 800 "${LOCK[@]}"
safari-browser snapshot "${LOCK[@]}" > /tmp/cclog_$i.txt
done
# 合併去重(時間戳開頭的行)
cat /tmp/cclog_*.txt | sort -u > /tmp/cclog_merged.txt
🔧 首次實機微調:scroll 像素(600)+ 圈數(5)依該 content log 長度調。確認合併後最舊那行的時間戳有涵蓋到你要看的時段,否則加圈數。
A4. 抓 metrics(lag 診斷關鍵)
safari-browser screenshot /tmp/cc_metrics.png "${LOCK[@]}"
讀截圖看 CPU / 記憶體 / 連線曲線哪個時間點飆高 — lag 多半在這裡,不在 log 文字。
Path B:agent-browser(進階,看 network)
⭐ auth 設定(spike 最核心 — 必讀,否則一定踩雷)
agent-browser 的 3 個 auth 概念不要混淆:
| 機制 | 用途 | 雷 |
|---|---|---|
state save ./auth.json / --state ./auth.json | 跨 headed→headless 的橋(登入存檔,headless 載入) | flag 前置 |
AGENT_BROWSER_SESSION_NAME=<name> env | auth state auto-save/restore by name | 只管 auth,不選 instance |
AGENT_BROWSER_SESSION=<name> env | 選 instance(isolated session) | 跟上面是不同 env |
--persist / --no-isolated | 固定 profile dir | ⚠️ 這版單獨用會 Unknown command,別賴它 |
致命雷(spike 卡 10+ 步的主因):
agent-browser 的 headed 和 headless 是不同 browser instance,
session list還不一定追蹤 headed 的。所以--headed open的視窗,跟後續無 flag 的snapshot/get url連到不同 instance → 一直連錯、抓到 about:blank 或別的殘留 tab。
正解 = state save/load 橋接(官方 skills get core --full line 218-221):
# === 一次性:headed 登入 → 存 auth ===
agent-browser --headed open "https://connect.posit.cloud/"
# 使用者在彈出視窗手動 OAuth 登入(headless 會 OAuth Invalid request,必須 headed)
agent-browser --headed state save ~/.agent-browser-posit-auth.json # 從登入的 headed instance 存
# === 之後每次:headless 載入 auth ===
agent-browser --state ~/.agent-browser-posit-auth.json open "https://connect.posit.cloud/content/<id>"
agent-browser --state ~/.agent-browser-posit-auth.json snapshot -i
auth 過期 → 重跑「一次性」段落重存。flag(
--headed/--state)一律前置於 command。
B1-B3. 導航 / 抓 log / metrics
同 Path A 的 A2-A4,但命令是 agent-browser(帶 --state),且:
# Path B 獨有:看 network(lag = 慢 XHR / DB call)
agent-browser --state ~/.agent-browser-posit-auth.json network
找耗時最長的 request — 那常是 lag 的真兇(慢 query、慢 OpenAI call、慢 Supabase round-trip)。
Step 9:分析 log + 輸出
# error / warning
grep -iE "error|warning|fail|exception|cannot|timeout" /tmp/cclog_merged.txt
# timestamp gap(找哪兩行之間 gap 大 = 那段慢)— 人工掃時間戳,或:
awk '{print $1, $2}' /tmp/cclog_merged.txt # 看連續行的時間戳差
輸出格式:
═══════════════════════════════════════════
Connect Cloud Log — QEF_DESIGN
路徑: Path A (safari-browser)
抓取範圍: 21:48:54 ~ 21:49:00(6 秒,N 圈滾動)
─────────────────────────────────────────
🔴 Error/Warning: (無 / 列出)
⏱ 最大 timestamp gap: 21:48:57→21:49:00(3s,連 Supabase PostgreSQL)
📊 Metrics(截圖 /tmp/cc_metrics.png): CPU 在 21:49 飆至 X%
─────────────────────────────────────────
診斷: lag 來自 Supabase 連線 round-trip(3s)
建議: 在 dbConnectAppData() 前後埋 message(Sys.time()) 確認 / 考慮連線池
═══════════════════════════════════════════
踩雷速查
| 症狀 | 原因 | 解 |
|---|---|---|
| agent-browser snapshot 抓到 about:blank / 別的 tab | headed/headless 不同 instance | 用 --state 一致載入,flag 前置 |
Unknown command: --persist | --persist 單獨用的 parser 雷 | 改用 --state / AGENT_BROWSER_SESSION_NAME |
| log 只有 ~12 行,抓不到更早 | virtualized list 只渲染 viewport | A3 的滾動累積 + 去重 |
safari Unknown option | $LOCK 沒引號(zsh 不 word-split) | bash array "${LOCK[@]}" |
Could not connect to Safari | Safari 沒開 | 先 safari-browser open 或手動開 Safari |
| metrics 讀不到數值 | 是圖不是文字 | screenshot 後讀圖 |
| OAuth Invalid request | headless 開 OAuth 頁 | 登入那刻必須 --headed |
跟 /shiny-debug 的關係
| 情境 | 工具 |
|---|---|
Local dev app(localhost:3838)log | /shiny-debug(讀 .shiny-debug/shiny.log) |
| 部署後 Connect Cloud runtime log | 本 command |
| Live app 前端 UI 驗證(不看 log) | safari-browser 直接調用(見 08-shiny-testing.md) |
部署後 lag/crash bug 的標準流程:本 command 抓 Connect Cloud log → 定位慢的那段 → 回 local 用 /shiny-debug 重現 + 修 → redeploy。
Shiny Adaptive Walk
Self-converging test-builder loop for MP165 dashboard rendering acceptance. Each iteration:
- Walks the company dashboard via agent-browser by default (headless Chromium — fast, stable, reproducible). Opt into visible safari-browser via
--browser safarifor live-watch scenarios. - LLM judges each rendered screenshot for defects
- Bifurcates per defect:
- test_infra_gap → skill auto-mutates
qef_design.yaml/contracts.R/run_smoke_lite.R - real_bug → skill files
/idd-issue(does NOT touch production code)
- test_infra_gap → skill auto-mutates
- Runs existing test suite + mechanical gate to confirm no regression
- Repeats until CONVERGED / PLATEAUED / DIMINISHING
Refs: spectra change adaptive-dashboard-test-loop (issue #653) / sister of /shiny-debug (interactive debug, single-pass) / MP165 v1.2 Track B (adaptive overlay vs Track A declarative baseline).
使用方式
/shiny-adaptive-walk QEF_DESIGN # default config (browser=agent)
/shiny-adaptive-walk QEF_DESIGN --browser safari # opt into visible Safari (live watch)
/shiny-adaptive-walk QEF_DESIGN --budget 50 # cap LLM calls at 50
/shiny-adaptive-walk QEF_DESIGN --max-iter 3 # cap iterations at 3 (default 5)
/shiny-adaptive-walk QEF_DESIGN --no-pr # don't open PR after converge
Required argument: <COMPANY> matching app_config.yaml company code (QEF_DESIGN / D_RACING / MAMBA / WISER / kitchenMAMA).
核心原則
| Rule | Detail |
|---|---|
| Discovery walk | Default agent-browser (headless Chromium) — fast, reproducible, no tab-focus contention. Opt into safari-browser via --browser safari for live observation; see "When to opt into --browser safari" below. Both engines render real DOM; 08-shiny-testing.md narrow exception clause covers the opt-in safari path. |
| Mechanical regression | agent-browser (headless Chromium) — confirms mutations don't break existing tests + new contracts catch defects. Independent of the discovery --browser setting. |
| Mutation boundary | Skill CAN edit test infra (98_test/e2e/**, 23_deployment/dashboard_presence_gate.R, 04_utils/fn_debug_mode.R). Skill MUST NOT touch production code (10_rshinyapp_components/, 16_derivations/, 04_utils/fn_analysis_*.R, update_scripts/ETL/, update_scripts/DRV/) → files /idd-issue instead. |
| Atomic per-iter commit | Each iteration ships as ONE commit iter-N: <summary> (refs <#issue>). If post-mutation tests fail, git reset --hard HEAD~1 reverts the iter. |
| LLM budget cap | MP165_ADAPTIVE_BUDGET=100 env var (default 100 calls per session). Short-circuit DIMINISHING when exhausted. |
| Branch isolation | Skill operates on idd/<N>-adaptive-test-loop feature branch from main. NEVER pushes to remote during loop (Phase 6 final action: open PR for human review). |
| Issue dedup | Real bugs filed with composite signature <company>:<module>:<sub_tab>:<defect_class>:<key_phrase>. Skill gh issue list --search before filing — match → comment on existing instead of new issue. |
執行步驟
Step 0: Pre-flight checks
# Browser selection — flag overrides env var overrides static `agent` default.
# BROWSER_FLAG is set by the flag-parsing pass below (empty if --browser not given).
BROWSER="${BROWSER_FLAG:-${SHINY_ADAPTIVE_BROWSER:-agent}}"
case "$BROWSER" in
safari|agent) ;;
*) abort "--browser must be one of: safari, agent (got: $BROWSER)" ;;
esac
# Required tools — only the selected browser's CLI is required.
if [ "$BROWSER" = "safari" ]; then
which safari-browser || abort "safari-browser CLI required for --browser safari (macOS only). Pass --browser agent to switch, or install safari-browser. See $L4_ENT/.../08-shiny-testing.md Live URL section"
else
which agent-browser || abort "agent-browser CLI required for default browser mode. npm install -g agent-browser && agent-browser install (or pass --browser safari if safari-browser is available)"
fi
which gh || abort "gh CLI required"
command -v Rscript || abort "R + Rscript required"
# Required env
COMPANY="${1:?company required (QEF_DESIGN / D_RACING / MAMBA / WISER / kitchenMAMA)}"
BUDGET="${MP165_ADAPTIVE_BUDGET:-100}"
MAX_ITER="${MP165_MAX_ITER:-5}"
OPEN_PR="${OPEN_PR:-true}"
Parse flags:
--budget N→ overrideMP165_ADAPTIVE_BUDGETto N--max-iter N→ overrideMP165_MAX_ITER(default 5)--no-pr→ skip auto-PR at end--browser safari|agent→ overrideSHINY_ADAPTIVE_BROWSERenv var (precedence: flag > env >agent)
No tab-focus / window-count probing is performed — browser mode is determined explicitly by the precedence chain above. There is no runtime auto-fallback.
Step 1: Working tree + branch setup
# Must start clean
test -z "$(git status --porcelain)" || abort "uncommitted changes; commit or stash first"
# Determine parent issue for branch name (default #653, can override)
PARENT_ISSUE="${PARENT_ISSUE:-653}"
# Branch: idd/<N>-adaptive-test-loop[-2|-3...]
BASE_BRANCH="idd/${PARENT_ISSUE}-adaptive-test-loop"
BRANCH="$BASE_BRANCH"
suffix=2
while git rev-parse --verify "$BRANCH" >/dev/null 2>&1; do
BRANCH="${BASE_BRANCH}-${suffix}"
suffix=$((suffix + 1))
done
git checkout main
git pull origin main
git checkout -b "$BRANCH"
echo "→ Working on branch: $BRANCH"
Step 2: Pre-loop reconnaissance — read existing yaml
YAML_PATH="shared/global_scripts/98_test/e2e/contracts/$(echo "$COMPANY" | tr '[:upper:]' '[:lower:]').yaml"
test -f "$YAML_PATH" || YAML_NEW=1
# Snapshot pre-state for dedup
PRE_CONTRACTS_HASH=$(test -f "$YAML_PATH" && sha256sum "$YAML_PATH" | cut -d' ' -f1 || echo "missing")
If $YAML_PATH doesn't exist (e.g., wiser / kitchenmama), skill will CREATE it during first iter with the standard schema header + reserved # === auto-suggested === block.
Step 3: Iteration loop (max $MAX_ITER)
ITER=1
LLM_CALLS_USED=0
PREV_DEFECTS_HASH=""
while [ $ITER -le $MAX_ITER ]; do
echo "═══ Iteration $ITER / $MAX_ITER ═══"
echo "Budget remaining: $((BUDGET - LLM_CALLS_USED)) / $BUDGET LLM calls"
if [ $LLM_CALLS_USED -ge $BUDGET ]; then
VERDICT="DIMINISHING"
REASON="budget exhausted at iter $ITER"
break
fi
iter_result=$(run_iteration $ITER)
case "$iter_result" in
"converged") VERDICT="CONVERGED"; break ;;
"plateaued") VERDICT="PLATEAUED"; break ;;
"diminishing") VERDICT="DIMINISHING"; break ;;
"rollback") echo " iter $ITER rolled back due to regression"; ITER=$((ITER + 1)) ;;
"progress") ITER=$((ITER + 1)) ;;
esac
done
if [ -z "$VERDICT" ]; then
VERDICT="MAX_ITER_REACHED"
fi
Step 3a: Discovery walk
The discovery walk uses the browser selected in Step 0 ($BROWSER). All five discovery primitives (open / snapshot / click / fill / screenshot) flow through a single dispatcher helper:
# Single source of truth for browser dispatch.
# safari mode appends --url "$URL_SUBSTR" for tab targeting;
# agent mode runs headless with a single ephemeral context (no --url needed).
# Supported subcommands: open / snapshot / click / fill / screenshot.
browser_cmd() {
local subcmd="$1"; shift
if [ "$BROWSER" = "safari" ]; then
safari-browser "$subcmd" "$@" --url "$URL_SUBSTR"
else
agent-browser "$subcmd" "$@"
fi
}
discover_defects() {
# 1. Start Shiny app via nohup
cd "$COMPANY_DIR"
pkill -TERM -f "Rscript app.R" 2>/dev/null
sleep 1
mkdir -p .shiny-debug
rm -f .shiny-debug/shiny.log
SHINY_DEBUG_MODE=TRUE nohup Rscript app.R > .shiny-debug/shiny.log 2>&1 &
APP_PID=$!
# 2. Wait for "Listening on" marker
for i in $(seq 1 60); do
if grep -q "Listening on" .shiny-debug/shiny.log 2>/dev/null; then break; fi
sleep 1
done
URL=$(grep "Listening on" .shiny-debug/shiny.log | tail -1 | grep -oE "http://[^[:space:]]+")
URL_SUBSTR=$(echo "$URL" | sed -E 's#https?://##; s#/$##')
# 3. Open the app (safari uses --url tab targeting; agent uses headless single-context)
browser_cmd open "$URL"
sleep 2
# 4. Login
browser_cmd snapshot -i > /tmp/snap_login.txt
PWD_REF=$(extract_ref_from_snap /tmp/snap_login.txt "textbox.*密碼|textbox.*password")
SUBMIT_REF=$(extract_ref_from_snap /tmp/snap_login.txt "button.*進入|button.*Login")
browser_cmd fill "${PWD_REF:-@e1}" VIBE
browser_cmd click "${SUBMIT_REF:-@e2}"
sleep 3
# 5. Walk top-level + sub-tabs, screenshot each
SCREENSHOTS=()
for tab in "總覽儀表板" "TagPilot" "Marketing Vital-Signs" "BrandEdge" "InsightForge 360" "報告中心"; do
browser_cmd snapshot -i > "/tmp/snap_${tab}.txt"
TAB_REF=$(extract_ref_from_snap "/tmp/snap_${tab}.txt" "link.*${tab}")
[ -n "$TAB_REF" ] || continue
browser_cmd click "$TAB_REF"
sleep 2.5 # bs4Dash accordion settle
# Take screenshot for top-level
browser_cmd screenshot "/tmp/walk_iter${ITER}_${tab}.png"
SCREENSHOTS+=("/tmp/walk_iter${ITER}_${tab}.png")
# Re-snap to find sub-tabs (reuse run_smoke_lite.R::.smoke_extract_sub_tab_refs)
SUB_REFS=$(R -e "source('shared/global_scripts/98_test/e2e/run_smoke_lite.R'); cat(.smoke_extract_sub_tab_refs(snap_text, '$tab', remaining_tabs))")
for sub_ref in $SUB_REFS; do
browser_cmd click "$sub_ref"
sleep 1
browser_cmd screenshot "/tmp/walk_iter${ITER}_${tab}_${sub_ref}.png"
SCREENSHOTS+=("/tmp/walk_iter${ITER}_${tab}_${sub_ref}.png")
done
done
kill -TERM "$APP_PID" 2>/dev/null
}
No literal safari-browser or agent-browser CLI invocation should appear in Step 3a outside the browser_cmd helper.
Step 3b: LLM judge classification (per screenshot)
For each screenshot in ${SCREENSHOTS[@]}, classify defects using hybrid rule + LLM:
Hard rules (deterministic, no LLM call needed):
- Text content contains
Error:/[object Object]/<NA>/NaN→real_bug(production-visible error) - KPI card value is
--/-/N/A→real_bug(data path broken) - Title contains TitleCase English (4+ chars, not in DT controls whitelist) →
real_bug(i18n regression) - Sub-tab visible in safari but absent from
$YAML_PATHcontracts →test_infra_gap
LLM judgment (for ambiguous cases):
Prompt template (for each screenshot):
You are evaluating a Shiny dashboard screenshot for defects.
Context:
- Company: $COMPANY
- Tab: $TAB_NAME / $SUB_TAB
- Product line: $PRODUCT_LINE
- Reference healthy state: $HEALTHY_REF_SCREENSHOT (when available)
Classify each visible defect:
- real_bug: user-visible error, missing data, broken render
- test_infra_gap: render is OK but test contracts don't cover this element
- acceptable: empty state with explanatory message (e.g., "請先選擇產品線")
Return JSON: { "defects": [{"signature": "...", "class": "real_bug|test_infra_gap|acceptable", "evidence": "..." }] }
Increment LLM_CALLS_USED += 1 per LLM invocation. Use Claude Haiku 4.5 (per CLAUDE.md performance rule: lightweight + high-frequency).
Step 3c: Mutation bifurcation
for defect in $defects_json; do
signature=$(echo "$defect" | jq -r .signature)
class=$(echo "$defect" | jq -r .class)
evidence=$(echo "$defect" | jq -r .evidence)
case "$class" in
"real_bug")
handle_real_bug "$signature" "$evidence"
;;
"test_infra_gap")
handle_test_infra_gap "$signature" "$evidence"
;;
"acceptable")
# No action; just log
echo " $signature: acceptable empty state, no defect"
;;
esac
done
handle_real_bug — file /idd-issue with dedup
handle_real_bug() {
local sig="$1" # e.g., "QEF_DESIGN:insightforge:market_track:error_object:coefficient"
local evidence="$2"
# Dedup: search existing issues
existing=$(gh issue list --repo kiki830621/ai_martech_global_scripts \
--state open --search "in:body \"$sig\"" --json number -q '.[0].number')
if [ -n "$existing" ]; then
# Re-observed during this run; comment instead of new issue
gh issue comment "$existing" --repo kiki830621/ai_martech_global_scripts \
--body "Re-observed during \`/shiny-adaptive-walk\` iter $ITER ($(date -u +%Y-%m-%d)). Signature: \`$sig\`"
FILED_ISSUES+=("$existing (re-observed)")
else
# New issue
new_url=$(gh issue create --repo kiki830621/ai_martech_global_scripts \
--title "[bug][$COMPANY] $(echo "$evidence" | head -1)" \
--label "bug,confidence:confirmed,priority:P2,company:$COMPANY" \
--body "$(cat <<EOF
## Problem
Discovered during \`/shiny-adaptive-walk $COMPANY\` iteration $ITER.
**Defect signature**: \`$sig\`
**Evidence**: $evidence
## Source
Surfaced during \`/shiny-adaptive-walk\` adaptive testing loop (refs spectra change \`adaptive-dashboard-test-loop\`, parent issue #$PARENT_ISSUE). Per IC_R011 commercial low-bar filing — skill files this rather than fixing because production code is OUTSIDE mutation boundary.
## Files NOT touched by skill
- \`shared/global_scripts/10_rshinyapp_components/**\`
- \`shared/global_scripts/16_derivations/**\`
- \`shared/global_scripts/04_utils/fn_analysis_*.R\`
- \`shared/update_scripts/ETL/**\`
- \`shared/update_scripts/DRV/**\`
Bug fix is human responsibility.
EOF
)")
FILED_ISSUES+=("$new_url")
fi
}
handle_test_infra_gap — mutate test framework
handle_test_infra_gap() {
local sig="$1"
local evidence="$2"
# Parse signature to identify which file + what mutation
module=$(echo "$sig" | cut -d: -f2)
sub_tab=$(echo "$sig" | cut -d: -f3)
gap_type=$(echo "$sig" | cut -d: -f4)
case "$gap_type" in
"missing_contract")
# Append to # === auto-suggested === block in yaml
append_yaml_contract "$YAML_PATH" "$module" "$sub_tab" "$evidence"
;;
"weak_primitive")
# New primitive or strengthen existing in contracts.R
add_contracts_primitive "$evidence"
;;
"walker_miss")
# Strengthen run_smoke_lite.R walker logic
strengthen_walker "$evidence"
;;
*)
log_warn " Unknown gap_type '$gap_type', skipping mutation"
;;
esac
}
Auto-suggested yaml append pattern:
# === auto-suggested by adaptive walker (2026-MM-DD iter N) ===
modules:
insightforge:
enabled: true
sub_tabs:
market_track:
active_product_lines: [hsg, sfg, ...] # detected from app config
contracts:
- selector: "insightforge_market-kpi_track_champion"
assertion: "no_error_placeholder"
severity: critical
- selector: "insightforge_market-table_track_analysis"
assertion: "no_error_text"
severity: critical
Skill must preserve hand-maintained sections of yaml above the # === auto-suggested === marker. Diff-aware: walker only modifies content AFTER the marker.
Step 3d: Per-iter safety gate
run_safety_gate() {
# 1. Existing test suite
echo " Running existing test suite..."
if ! NOT_CRAN=true Rscript -e "testthat::test_dir('shared/global_scripts/98_test/e2e', reporter='summary')" > /tmp/test_dir.log 2>&1; then
echo " ✗ Existing tests broke — iter $ITER will rollback"
return 1
fi
# 2. Mechanical gate against current company
echo " Running mechanical gate..."
if ! Rscript shared/global_scripts/23_deployment/dashboard_presence_gate.R \
--company "$COMPANY" \
--app-dir "$COMPANY_DIR" \
--allow-warnings \
--password VIBE \
--timeout 90 > /tmp/gate.log 2>&1; then
echo " ✗ Mechanical gate failed — iter $ITER will rollback"
return 1
fi
return 0
}
# Commit + safety check + rollback if needed.
# Per-iter commit body carries an audit-trail line BROWSER=<safari|agent>
# so commit history records which browser produced this iter's evidence.
if [ -n "$(git status --porcelain)" ]; then
git add -A
COMMIT_BODY="BROWSER=$BROWSER"
if [ -n "$ITER_BODY_EXTRA" ]; then
COMMIT_BODY="$COMMIT_BODY
$ITER_BODY_EXTRA"
fi
git commit -m "iter-$ITER: $ITER_SUMMARY (refs #$PARENT_ISSUE)" -m "$COMMIT_BODY" 2>&1
if ! run_safety_gate; then
git reset --hard HEAD~1
echo " ROLLBACK: iter $ITER mutations reverted"
iter_result="rollback"
else
iter_result="progress"
fi
fi
Step 3e: Convergence detection
# Defect signatures this iter
CURRENT_DEFECTS_HASH=$(echo "${DEFECT_SIGNATURES[@]}" | sort | sha256sum | cut -d' ' -f1)
# Real-bug ratio
REAL_BUG_RATIO=$(echo "scale=2; ${#FILED_ISSUES[@]} / (${#DEFECT_SIGNATURES[@]} + 0.001)" | bc)
if [ ${#DEFECT_SIGNATURES[@]} -eq 0 ]; then
iter_result="converged"
REASON="0 defects this iter, mutations from iter $((ITER-1)) all PASS regression"
elif [ "$CURRENT_DEFECTS_HASH" = "$PREV_DEFECTS_HASH" ]; then
iter_result="plateaued"
REASON="same defect set 2 consecutive iters; user intervention needed"
elif (( $(echo "$REAL_BUG_RATIO > 0.8" | bc -l) )); then
iter_result="diminishing"
REASON="${#FILED_ISSUES[@]} real bugs filed vs only ${#MUTATIONS_THIS_ITER[@]} test gaps — test infra converged, await bug fixes"
fi
PREV_DEFECTS_HASH="$CURRENT_DEFECTS_HASH"
Step 4: PLATEAUED handling — AskUserQuestion
When VERDICT="PLATEAUED", surface to user before exit:
AskUserQuestion:
question: "Loop plateaued at iter $ITER on $defect_count same defects 2 iters. How to handle?"
options:
- "force-converge: accept current state, exit"
- "bulk-file: file remaining defects as omnibus issue"
- "abort: leave branch as-is, user investigates manually"
Step 5: Final report
══════════════════════════════════════════
/shiny-adaptive-walk $COMPANY — $VERDICT
══════════════════════════════════════════
Iterations: $ITER / $MAX_ITER
LLM calls: $LLM_CALLS_USED / $BUDGET
Branch: $BRANCH
Walk time: ${ELAPSED}s total
Test framework mutations:
$(printf ' - %s\n' "${MUTATIONS[@]}")
Real bugs filed (per IC_R011 commercial low-bar):
$(printf ' - %s\n' "${FILED_ISSUES[@]}")
Rollbacks: $ROLLBACK_COUNT
Reason: $REASON
Next: review git diff main..$BRANCH + open PR for human review
Step 6: Open PR (if --no-pr not specified)
if [ "$OPEN_PR" = "true" ]; then
git push -u origin "$BRANCH"
gh pr create --repo kiki830621/ai_martech_global_scripts \
--base main --head "$BRANCH" \
--title "[adaptive-test] $COMPANY iter $ITER $VERDICT (refs #$PARENT_ISSUE)" \
--body "$(cat <<EOF
Refs #$PARENT_ISSUE — \`/shiny-adaptive-walk $COMPANY\` run
## Convergence
- Verdict: **$VERDICT**
- Iterations: $ITER / $MAX_ITER
- LLM budget: $LLM_CALLS_USED / $BUDGET
## Mutations
$(printf '- %s\n' "${MUTATIONS[@]}")
## Real bugs filed
$(printf '- %s\n' "${FILED_ISSUES[@]}")
## Cross-co (IC_P002)
Single-co run for $COMPANY. Verified: trailer requires running on 5 cos (per parent spectra change adaptive-dashboard-test-loop Phase 5).
🤖 Generated by /shiny-adaptive-walk
EOF
)"
fi
Mutation boundary spec (CRITICAL)
Mutable zone (skill CAN edit)
| Path glob | Why |
|---|---|
shared/global_scripts/98_test/e2e/contracts/*.yaml | Auto-emit contracts to # === auto-suggested === block |
shared/global_scripts/98_test/e2e/contracts/contracts.R | Add new primitives when existing 5 + 3 (Phase 1) insufficient |
shared/global_scripts/98_test/e2e/run_smoke_lite.R | Strengthen walker when navigation gaps surface |
shared/global_scripts/98_test/e2e/test-*.R | Add new regression test files for discovered defects |
shared/global_scripts/23_deployment/dashboard_presence_gate.R | Add new gate logic / flags |
shared/global_scripts/04_utils/fn_debug_mode.R | Strengthen NULL detection or add new debug-mode signals |
Immutable zone (skill MUST file /idd-issue instead)
| Path glob | Reason for immutability |
|---|---|
shared/global_scripts/10_rshinyapp_components/** | UI component source code — code-under-test |
shared/global_scripts/16_derivations/** | Business logic derivations |
shared/global_scripts/04_utils/fn_analysis_*.R | Analysis functions |
shared/update_scripts/ETL/** | ETL pipeline scripts |
shared/update_scripts/DRV/** | Derivation execution scripts |
shared/global_scripts/01_db/** | Database connection / DDL |
Any .qmd principle file | Principle changes require explicit human decision |
Pre-mutation check: before any file edit, verify path is in mutable zone via hard glob match. Refuse mutation if file is in immutable zone — file issue instead.
Convergence model (mirrors /glue-bridge MP102 v1.3)
| Verdict | Trigger | Action |
|---|---|---|
| CONVERGED | 0 new defects this iter AND previous iter's mutations all PASS regression | Exit success. Test infra has full coverage of currently-observable defects. |
| PLATEAUED | Same defect signature set 2 consecutive iters | AskUserQuestion 3-option (force-converge / bulk-file / abort) |
| DIMINISHING | >80% real_bug classifications this iter (test gaps mostly resolved, remaining defects are code bugs awaiting human fix) | Exit success with list of filed bugs. Test infra is converged for what's testable. |
| MAX_ITER_REACHED | Hit $MAX_ITER without other terminal state | Exit partial. User can re-invoke to continue. |
| BUDGET_EXHAUSTED | LLM_CALLS_USED >= BUDGET mid-iter | Short-circuit DIMINISHING. User can re-invoke with --budget override. |
Examples
Today's #653 F1-F5 retroactive walkthrough
If /shiny-adaptive-walk QEF_DESIGN were run against current main (assuming Phase 1+2 already merged), expected behavior:
Iter 1:
- Discovery walks 6 top + 8 sub-tabs (Phase 2 walker)
- LLM judge classifies:
- F1 InsightForge 市場賽道
Error: [object Object]→ real_bug (hard rule) - F2 InsightForge 精準行銷
--KPI → real_bug (hard rule) - F3 InsightForge 時間分析
0/0/--/0→ real_bug (LLM judges as broken data path) - F4 BrandEdge KFE
Key Factor Evaluationhardcoded English → real_bug (hard rule) - F5 BrandEdge 理想點分析 hardcoded English subtitle → real_bug (hard rule)
- meta: InsightForge sub-tabs absent from
qef_design.yaml→ test_infra_gap
- F1 InsightForge 市場賽道
Skill actions:
- File
/idd-issuefor F1+F2+F3 (combined or separate, dedup against #655 if exists) - File
/idd-issuefor F4+F5 (dedup against #656) - Mutate
qef_design.yaml— append InsightForge module to# === auto-suggested ===block with contracts usingassert_no_error_text+assert_kpi_no_error_placeholder - Commit
iter-1: file 5 bugs + add InsightForge contracts (refs #653) - Run safety gate — confirm new contracts catch F1-F5 + existing tests pass
Iter 2:
- Discovery walks again
- Same F1-F5 defects appear (no code fix yet)
- LLM judge classifies all as real_bug — but dedup finds existing issues, skip filing
- No new test_infra_gap (yaml already has contracts)
- DIMINISHING verdict (100% real_bug, no new mutations)
Final report: CONVERGED on test infra, 5 bugs filed awaiting human fix.
Empty company (already-covered)
If /shiny-adaptive-walk D_RACING runs and walker finds no new defects:
Iter 1:
- Walks 6 tabs + sub-tabs
- LLM judge: 0 defects across all screenshots
- No mutations needed, no bugs filed
- CONVERGED at iter 1
Final yaml # === auto-suggested === block contains # (none — already covered).
Anti-patterns
| Don't | Do |
|---|---|
| Edit production code (UI components, business logic) | File /idd-issue — skill respects bug ownership boundary |
| Skip per-iter regression gate | ALWAYS run test_dir + mechanical gate; auto-rollback on failure |
| File duplicate bug issues | Compute composite signature + gh issue list --search before filing |
| Run on dirty working tree | Refuse start with uncommitted changes (per Step 1) |
| Auto-merge PR | NEVER push directly to main; only feature branch + PR for human review |
| Ignore budget | Short-circuit DIMINISHING when LLM_CALLS_USED >= BUDGET |
Configuration reference
| Env var | Default | Effect |
|---|---|---|
MP165_ADAPTIVE_BUDGET | 100 | Max LLM judge calls per skill session |
MP165_MAX_ITER | 5 | Max iterations before MAX_ITER_REACHED |
PARENT_ISSUE | 653 | Issue # used in branch name + commit refs |
OPEN_PR | true | If "false", skill doesn't auto-create PR at end |
SHINY_ADAPTIVE_BROWSER | agent | Discovery browser. Values: safari or agent. Overridden by --browser flag when both are set. See "When to opt into --browser safari" below. |
Flags
| Flag | Effect |
|---|---|
--budget N | Override MP165_ADAPTIVE_BUDGET to N |
--max-iter N | Override MP165_MAX_ITER to N |
--no-pr | Skip auto-PR (sets OPEN_PR=false) |
--browser safari|agent | Discovery browser. Default agent. Overrides SHINY_ADAPTIVE_BROWSER env var. See "When to opt into --browser safari" below. |
When to opt into --browser safari
The default agent-browser (headless Chromium) is the right choice for almost every invocation: unattended runs, CI, multi-hour cross-company rollouts, and any case where nobody is watching the loop iterate. Headless is faster (no Safari startup or window animation per iteration), more reproducible (ephemeral context, no user-profile cookies or extensions), and immune to macOS Safari's tab-focus contention.
Opt into --browser safari only when realtime visibility is the value:
| Scenario | Why safari |
|---|---|
| Live demo / teaching | The audience needs to see the loop walk the dashboard |
| In-the-moment debugging | You want to watch each click land in a real Safari window |
| Visual regression spot-check | You're suspicious of an engine-specific WebKit rendering issue |
If none of those apply, leave the default. Both engines render real DOM; for Shiny apps built on bs4Dash + plotly + DT there is no meaningful rendering difference. The "real renderer ground truth" framing that earlier versions of this skill carried was Safari-bias, not fact.
Cross-references
- Sister skill:
/shiny-debug— single-pass interactive functional debug (this skill = self-converging adaptive loop) - Parent spectra change:
adaptive-dashboard-test-loopinkiki830621/ai_martech_global_scriptsrepo (openspec/changes/adaptive-dashboard-test-loop/) - Parent issue: kiki830621/ai_martech_global_scripts#653
- MP165 v1.2 amendment: codifies dual-track architecture (Track A declarative
qef_design.yamlbaseline + Track B adaptive walker overlay) - Prior art:
/glue-bridgeMP102 v1.3 self-converging review pattern (CONVERGED / PLATEAUED / DIMINISHING verdicts) - Principle exception:
00_principles/.claude/rules/08-shiny-testing.mdnarrow exception clause permits safari-browser on local for adaptive-walker discovery. The clause stays accurate as written; default browser isagent-browsersince theadaptive-walk-agent-browser-defaultchange (issue PsychQuant/psychquant-claude-plugins#77), and safari is opt-in via--browser safari. - Default browser change: PsychQuant/psychquant-claude-plugins#77 — inverted default from safari to agent.
- Bug filing discipline: IC_R011 commercial low-bar filing
Troubleshooting
safari-browser missing (only matters when --browser safari is selected)
safari-browser --version
If safari-browser is missing and you passed --browser safari (or set SHINY_ADAPTIVE_BROWSER=safari), Step 0 pre-flight aborts with a message naming the missing CLI. Two ways forward:
- Drop the safari opt-in: invoke without
--browser(and unsetSHINY_ADAPTIVE_BROWSER) — skill runs the default headlessagent-browserpath. - Install safari-browser: macOS-only. See
$L4_ENT/.../08-shiny-testing.mdLive URL section.
If you did NOT opt into safari, this section does not apply — the default agent-browser path bypasses safari-browser entirely.
agent-browser missing (default path)
agent-browser --version
If agent-browser is missing and you are on the default browser mode (no --browser flag and no SHINY_ADAPTIVE_BROWSER=safari), Step 0 pre-flight aborts. Install with npm install -g agent-browser && agent-browser install. Most macOS dev environments already have it (used by /shiny-debug sister skill). Common in bare Linux CI containers.
Branch collision
If idd/<N>-adaptive-test-loop already exists, skill auto-suffixes to -2, -3, etc. (per Step 1).
LLM judge returns inconsistent classification
Skill caches LLM responses per screenshot (content hash). Re-running iter N with same screenshots reuses cache. To invalidate: rm -rf /tmp/adaptive_walk_cache_*.
git status not clean after iter
If git status shows untracked files (e.g., new test fixture in 98_test/e2e/test-foo-fixture-iter1.png), those are skill artifacts. Commit them as part of the iter's mutations OR add to .gitignore. Skill should NEVER leave dirty state mid-loop — debug if encountered.
R Shiny Debugger
功能測試導向的 R Shiny App Debug 工具。採用 Log-First 原則:每進入一個新狀態,先檢查 R log 確認沒有錯誤,才繼續下一步。發現錯誤時立即修復程式碼。
使用方式
/shiny-debug— 互動模式,列出 UI 元素後詢問測試目標/shiny-debug 上傳後圖表更新— 直接測試指定功能
核心原則:Log-First
每一步操作後:
1. 讀取 R log(tail + grep error/warning)
2. log 乾淨? → 繼續下一步
3. log 有錯誤? → 停止測試 → 分析錯誤 → 修改程式 → 重啟 App → 從頭重新驗證
絕不跳過 log 檢查。 前端看起來正常不代表後端沒問題。
執行步驟
Step 1: 檢查前置需求
which agent-browser || echo "請先安裝: npm install -g agent-browser && agent-browser install"
which R || echo "請先安裝 R"
Step 2: 偵測 Shiny App
ls app.R ui.R server.R 2>/dev/null
app.R存在 → 單檔模式ui.R+server.R→ 雙檔模式- 都沒有 → 詢問用戶 app 路徑
如果專案有 .claude/rules/ 目錄,讀取測試相關的 rule 檔案(如 08-shiny-testing.md),取得專案特定的 port、密碼、檢查項目等設定。
Step 3: 啟動 App(背景執行)
mkdir -p .shiny-debug
# 清除舊 log
rm -f .shiny-debug/shiny.log
# 檢查 port
lsof -i :3838 | grep LISTEN && echo "Port 3838 被占用"
# 啟動
Rscript -e "shiny::runApp('.', port=3838, launch.browser=FALSE)" 2>&1 | tee .shiny-debug/shiny.log &
# 等待啟動
for i in {1..30}; do
grep -q "Listening on http" .shiny-debug/shiny.log 2>/dev/null && break
sleep 1
done
Step 3.1: 🔍 Log 檢查 — App 啟動後
必須在開啟瀏覽器之前執行。
# 檢查啟動過程中的錯誤
grep -iE "^Error|^Warning.*Error|subscript out of bounds|could not find function|cannot open|fatal" .shiny-debug/shiny.log
判斷:
- 無錯誤 → 繼續 Step 4
- 有錯誤 → 進入 錯誤修復流程
同時記錄關鍵初始化訊息供後續比對:
# 記錄重要的初始化訊息(翻譯、資料庫、元件)
grep -iE "\[Translation\]|\[DB\]|INITIALIZE|PROFILE" .shiny-debug/shiny.log
Step 4: 開啟瀏覽器
agent-browser open http://localhost:3838 --headed
Step 4.1: 🔍 Log 檢查 — 頁面載入後
# 後端:新產生的錯誤
grep -iE "^Error|^Warning.*Error|subscript out of bounds" .shiny-debug/shiny.log | tail -5
# 前端:JS 錯誤
agent-browser errors
判斷:
- 無錯誤 → 取得 UI snapshot,繼續 Step 5
- 有錯誤 → 進入 錯誤修復流程
無錯誤時才取 snapshot:
agent-browser snapshot -i
Step 5: 確認測試目標
如果用戶提供了 $ARGUMENTS,解析測試描述並規劃步驟。
如果沒有,詢問:
你想測試什麼功能?
- "上傳 CSV 後圖表應該更新"
- "空輸入時不應該 crash"
- 或直接操作:"click @e3"
Step 6: 執行測試(Log-First 迴圈)
對每一個測試步驟,都遵循以下順序:
┌─────────────────────────────────────────┐
│ 1. 執行操作(click / fill / navigate) │
│ 2. 等待(agent-browser wait 1000-3000)│
│ 3. 🔍 檢查 R log │
│ 4. 🔍 檢查前端 errors │
│ 5. log 乾淨?→ 記錄 ✅,下一步 │
│ log 有錯?→ 進入錯誤修復流程 │
└─────────────────────────────────────────┘
可用操作:
| 操作 | 命令 |
|---|---|
| 點擊 | agent-browser click @ref |
| 輸入 | agent-browser fill @ref "text" |
| 選擇 | agent-browser select @ref "value" |
| 上傳 | agent-browser upload @ref /path/file |
| 等待 | agent-browser wait 1000 |
| 截圖 | agent-browser screenshot path.png |
| 快照 | agent-browser snapshot -i |
每步驟後的 Log 檢查(不可省略):
# 後端 log(必做)
tail -20 .shiny-debug/shiny.log
grep -iE "^Error|^Warning.*Error|subscript|not found|cannot open" .shiny-debug/shiny.log | tail -5
# 前端 errors(必做)
agent-browser errors
Step 7: 輸出報告
成功:
═══════════════════════════════════════════
測試: 上傳 CSV 後圖表會更新
1. ✅ App 啟動 → [log] 無錯誤
2. ✅ 頁面載入 → [log] 無錯誤
3. ✅ 上傳 test.csv → [log] "Uploaded"
4. ✅ 選擇欄位 → [log] "Rendering"
5. ✅ 圖表已更新 → [log] 無錯誤
結果: ✅ 通過
═══════════════════════════════════════════
失敗後修復:
═══════════════════════════════════════════
測試: 驗證 UI 翻譯
1. ✅ App 啟動 → [log] 無錯誤
2. ❌ 登入 → [log] Error: subscript out of bounds
🔧 修復: fn_translation.R — named vector 改用 %in% names()
3. 🔄 重啟 App
4. ✅ App 啟動 → [log] 無錯誤
5. ✅ 登入 → [log] 無錯誤
6. ✅ Dashboard 載入 → "平台"、"產品線" 顯示中文
修復數: 1
結果: ✅ 通過(修復後)
═══════════════════════════════════════════
Step 7.5: 產生 E2E 腳本(可選)
測試報告輸出後,詢問用戶:
要從這次 debug session 產生 E2E 測試腳本嗎?(shinytest2)
如果用戶同意,根據 debug session 中的操作步驟,產生 shinytest2 腳本。
前置條件
- 檢查 E2E 基礎設施是否存在:
ls scripts/global_scripts/98_test/e2e/_setup.R 2>/dev/null
ls scripts/global_scripts/98_test/e2e/helpers/fn_e2e_app_driver.R 2>/dev/null
如果不存在,告知用戶需要先建立 E2E 基礎設施,並跳過此步驟。
- 讀取現有 E2E helpers 以了解可用的 assertion 函數:
cat scripts/global_scripts/98_test/e2e/helpers/fn_e2e_assertions.R
操作對應表
將 debug session 中的 agent-browser 操作轉換為 shinytest2 API:
| Debug 操作 | shinytest2 對應 |
|---|---|
| 登入(fill password + click submit) | create_logged_in_app()(helper 已封裝) |
| 切換 tab(click sidebar item) | app$set_inputs(sidebar_menu = "tabName") |
| 填入 input(fill @ref "value") | app$set_inputs(\input-id` = "value")` |
| 點擊按鈕(click @ref) | app$click("input-id") |
| 檢查 log 無錯誤 | assert_no_r_errors(app, context = "描述") |
| 檢查 tab 載入正常 | assert_tab_loads(app, "tabName") |
| 驗證 AI 按鈕可用 | assert_ai_button_works(app, "tabName", "module_id") |
| 等待 | app$wait_for_idle(timeout = 10000) + Sys.sleep(N) |
優先使用既有 helper:如果操作對應到 assert_tab_loads() 或 assert_ai_button_works(),直接用 helper 而不是拆成底層操作。
腳本模板
# E2E Test: {場景名稱}
# Level: L{級別} ({級別名稱})
# Generated from /shiny-debug session on {日期}
#
# Principles: TD_R007 (E2E testing)
test_that("{場景描述}", {
app <- create_logged_in_app()
on.exit(stop_app_safely(app), add = TRUE)
# Verify login worked
assert_logged_in(app)
# --- 以下根據 debug session 操作產生 ---
# {步驟 1 描述}
{shinytest2 操作}
app$wait_for_idle(timeout = 10000)
assert_no_r_errors(app, context = "{步驟 1 描述}")
# {步驟 2 描述}
{shinytest2 操作}
app$wait_for_idle(timeout = 10000)
assert_no_r_errors(app, context = "{步驟 2 描述}")
# ... 更多步驟
})
測試級別判斷
根據 debug session 的操作類型自動判斷級別:
| 操作內容 | 級別 | 理由 |
|---|---|---|
| 只有登入 + 首頁載入 | L1 Smoke | 最基本驗證 |
| Tab 切換、無 R 錯誤 | L2 Navigation | 導航正常性 |
| 元件互動、資料篩選、KPI 檢查 | L3 Functional | 功能正確性 |
| 截圖比對 | L4 Visual | 視覺一致性 |
命名與放置
- 檔名:
test-{場景名}.R(kebab-case,與既有檔案一致) - 位置:
scripts/global_scripts/98_test/e2e/test-{場景名}.R - 如果該檔案已存在,詢問用戶:覆蓋 or 追加 test_that block
產生後驗證
# 確認語法正確
Rscript -e "parse('scripts/global_scripts/98_test/e2e/test-{場景名}.R'); cat('PARSE OK\n')"
Step 8: 清理
詢問用戶:
- 繼續測試 → 回到 Step 5
- 產生 E2E 腳本 → 回到 Step 7.5
- 結束
agent-browser close
pkill -f "shiny::runApp"
錯誤修復流程
當 Log 檢查發現錯誤時,依照以下流程處理:
1. 分析錯誤
# 完整錯誤上下文
grep -B2 -A5 -iE "^Error|^Warning.*Error" .shiny-debug/shiny.log | tail -20
2. 定位問題程式碼
根據錯誤訊息找到對應的 R 檔案和行號。常見模式:
| 錯誤訊息 | 可能原因 | 常見位置 |
|---|---|---|
subscript out of bounds | [[key]] 存取不存在的 key | 翻譯函數、config 讀取 |
could not find function | 函數未 source 或套件未載入 | 初始化區塊 |
Column not found | 資料表 schema 不符 | 元件 server 函數 |
cannot open connection | 資料庫/檔案路徑錯誤 | 連線區塊 |
Error in source() | 找不到被 source 的檔案 | 路徑設定 |
3. 修復程式碼
直接修改有問題的 R 檔案。修復時同時改善錯誤訊息的明確度:
# 不好:只知道失敗
result <- some_operation(data)
# 好:知道是哪個元件、什麼輸入出問題
tryCatch({
result <- some_operation(data)
}, error = function(e) {
message("[ComponentName] Failed: ", e$message)
message("[ComponentName] Input: class=", class(data), " nrow=", NROW(data))
})
4. 驗證修復
# R parse check
Rscript -e "parse('path/to/modified_file.R')"
5. 重啟 App 並從頭測試
agent-browser close
pkill -f "shiny::runApp"
rm -f .shiny-debug/shiny.log
# 重新啟動(回到 Step 3)
Rscript -e "shiny::runApp('.', port=3838, launch.browser=FALSE)" 2>&1 | tee .shiny-debug/shiny.log &
重要:修復後必須從 Step 3 重新開始,不能只跳到出錯的步驟。 因為修改可能影響初始化流程。
測試檔案(可選)
如果有 .shiny-tests.yaml:
tests:
- name: test_upload
description: "上傳後圖表更新"
steps:
- action: upload
target: fileInput
file: test.csv
- action: verify
expect:
backend_log: "Rendering"
常見問題
App 啟動失敗:
cat .shiny-debug/shiny.log
Port 被占用:
kill $(lsof -t -i:3838)
找不到元素:
agent-browser snapshot -i
Log 太長找不到重點:
# 只看 Error 和 Warning 行
grep -n -iE "^Error|^Warning" .shiny-debug/shiny.log
# 看最近 50 行
tail -50 .shiny-debug/shiny.log
Sponsors
Details
- Marketplace
- PsychQuant/psychquant-claude-plugins
- Source
- plugins/r-shiny-debugger
- Author
- Che Cheng
- Category
- Development
More from PsychQuant/psychquant-claude-plugins
All 42- safari-browserv2.11.0
- tool-finderv1.0.0
- agent-cacherv0.1.0
- ai-docs-guidev1.4.0
- archive-firstv2.2.0
- batch-ocrv0.1.0
- bestocrv0.1.0
- che-apple-devv1.2.0
- che-apple-mail-mcpv2.0.1
- che-apple-notes-mcpv0.2.1
- che-archive-linesv1.0.0
- che-axiom-systemsv1.0.0
- che-biblatex-mcpv0.4.0
- che-bot-toolkitv0.1.0
- che-creative-suitev0.1.0
- che-dropbox-ignorev2.1.0
- che-duckdb-mcpv2.3.0
- che-ical-mcpv1.7.0
- che-latex-mcpv0.7.0
- che-pixel-mcpv0.1.0
- che-svg-mcpv0.1.0
- che-telegram-mcpv1.0.0
- che-things-mcpv1.7.1
- che-word-mcpv1.17.0