功能測試導向的 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-plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add PsychQuant/psychquant-claude-plugins.

Contents

Discovered from source

Commands 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 行),要滾動累積才抓得到完整 logspike 觀察
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> envauth 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 / 別的 tabheaded/headless 不同 instance用 --state 一致載入,flag 前置
Unknown command: --persist--persist 單獨用的 parser 雷改用 --state / AGENT_BROWSER_SESSION_NAME
log 只有 ~12 行,抓不到更早virtualized list 只渲染 viewportA3 的滾動累積 + 去重
safari Unknown option$LOCK 沒引號(zsh 不 word-split)bash array "${LOCK[@]}"
Could not connect to SafariSafari 沒開先 safari-browser open 或手動開 Safari
metrics 讀不到數值是圖不是文字screenshot 後讀圖
OAuth Invalid requestheadless 開 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:

  1. Walks the company dashboard via agent-browser by default (headless Chromium — fast, stable, reproducible). Opt into visible safari-browser via --browser safari for live-watch scenarios.
  2. LLM judges each rendered screenshot for defects
  3. 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)
  4. Runs existing test suite + mechanical gate to confirm no regression
  5. 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).

核心原則

RuleDetail
Discovery walkDefault 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 regressionagent-browser (headless Chromium) — confirms mutations don't break existing tests + new contracts catch defects. Independent of the discovery --browser setting.
Mutation boundarySkill 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 commitEach 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 capMP165_ADAPTIVE_BUDGET=100 env var (default 100 calls per session). Short-circuit DIMINISHING when exhausted.
Branch isolationSkill 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 dedupReal 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 → override MP165_ADAPTIVE_BUDGET to N
  • --max-iter N → override MP165_MAX_ITER (default 5)
  • --no-pr → skip auto-PR at end
  • --browser safari|agent → override SHINY_ADAPTIVE_BROWSER env 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_PATH contracts → 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 globWhy
shared/global_scripts/98_test/e2e/contracts/*.yamlAuto-emit contracts to # === auto-suggested === block
shared/global_scripts/98_test/e2e/contracts/contracts.RAdd new primitives when existing 5 + 3 (Phase 1) insufficient
shared/global_scripts/98_test/e2e/run_smoke_lite.RStrengthen walker when navigation gaps surface
shared/global_scripts/98_test/e2e/test-*.RAdd new regression test files for discovered defects
shared/global_scripts/23_deployment/dashboard_presence_gate.RAdd new gate logic / flags
shared/global_scripts/04_utils/fn_debug_mode.RStrengthen NULL detection or add new debug-mode signals

Immutable zone (skill MUST file /idd-issue instead)

Path globReason 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_*.RAnalysis 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 filePrinciple 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)

VerdictTriggerAction
CONVERGED0 new defects this iter AND previous iter's mutations all PASS regressionExit success. Test infra has full coverage of currently-observable defects.
PLATEAUEDSame defect signature set 2 consecutive itersAskUserQuestion 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_REACHEDHit $MAX_ITER without other terminal stateExit partial. User can re-invoke to continue.
BUDGET_EXHAUSTEDLLM_CALLS_USED >= BUDGET mid-iterShort-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 Evaluation hardcoded 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

Skill actions:

  • File /idd-issue for F1+F2+F3 (combined or separate, dedup against #655 if exists)
  • File /idd-issue for F4+F5 (dedup against #656)
  • Mutate qef_design.yaml — append InsightForge module to # === auto-suggested === block with contracts using assert_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'tDo
Edit production code (UI components, business logic)File /idd-issue — skill respects bug ownership boundary
Skip per-iter regression gateALWAYS run test_dir + mechanical gate; auto-rollback on failure
File duplicate bug issuesCompute composite signature + gh issue list --search before filing
Run on dirty working treeRefuse start with uncommitted changes (per Step 1)
Auto-merge PRNEVER push directly to main; only feature branch + PR for human review
Ignore budgetShort-circuit DIMINISHING when LLM_CALLS_USED >= BUDGET

Configuration reference

Env varDefaultEffect
MP165_ADAPTIVE_BUDGET100Max LLM judge calls per skill session
MP165_MAX_ITER5Max iterations before MAX_ITER_REACHED
PARENT_ISSUE653Issue # used in branch name + commit refs
OPEN_PRtrueIf "false", skill doesn't auto-create PR at end
SHINY_ADAPTIVE_BROWSERagentDiscovery browser. Values: safari or agent. Overridden by --browser flag when both are set. See "When to opt into --browser safari" below.

Flags

FlagEffect
--budget NOverride MP165_ADAPTIVE_BUDGET to N
--max-iter NOverride MP165_MAX_ITER to N
--no-prSkip auto-PR (sets OPEN_PR=false)
--browser safari|agentDiscovery 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:

ScenarioWhy safari
Live demo / teachingThe audience needs to see the loop walk the dashboard
In-the-moment debuggingYou want to watch each click land in a real Safari window
Visual regression spot-checkYou'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-loop in kiki830621/ai_martech_global_scripts repo (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.yaml baseline + Track B adaptive walker overlay)
  • Prior art: /glue-bridge MP102 v1.3 self-converging review pattern (CONVERGED / PLATEAUED / DIMINISHING verdicts)
  • Principle exception: 00_principles/.claude/rules/08-shiny-testing.md narrow exception clause permits safari-browser on local for adaptive-walker discovery. The clause stays accurate as written; default browser is agent-browser since the adaptive-walk-agent-browser-default change (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 unset SHINY_ADAPTIVE_BROWSER) — skill runs the default headless agent-browser path.
  • Install safari-browser: macOS-only. See $L4_ENT/.../08-shiny-testing.md Live 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

判斷:

同時記錄關鍵初始化訊息供後續比對:

# 記錄重要的初始化訊息(翻譯、資料庫、元件)
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 腳本。

前置條件
  1. 檢查 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 基礎設施,並跳過此步驟。

  1. 讀取現有 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: 清理

詢問用戶:

  1. 繼續測試 → 回到 Step 5
  2. 產生 E2E 腳本 → 回到 Step 7.5
  3. 結束
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