run-embedded-app-verify

Verify an embedded Shopify app change in the real admin

Closed loop: preflight → dedicated verify window → navigate the embedded app → interact → assert against the plan → report. On mismatch: fix the code and loop.

Hard rules:

• The dev server is the developer's responsibility. NEVER start it, and NEVER probe it — do not curl the application_url from shopify.app.toml or any tunnel URL: shopify app dev mints a fresh tunnel URL per run, so the toml value may not be the one actually serving. Judge dev-server health only by what the app iframe renders (step 4). If it is down, tell the user and stop.
• NEVER touch browser tabs other than the verify tab you created. The rest of the browser belongs to the developer.
• Delete every screenshot you take once the report is delivered (see step 6).

1. Load project config

Read .claude/shopify-verify.json in the project root:

{ "appHandle": "...", "storeDomain": "...", "iframeSelector": "iframe[name=\"app-iframe\"]" }

If the file is missing, run the setup-embedded-app-verify skill flow first (same plugin), then continue.

2. Preflight

1. Determine the verification URL first — the preflight opens the browser directly on it when it has to launch one: https://admin.shopify.com/store/<storeDomain>/apps/<appHandle>/<page-path> (<page-path> = the app route relevant to the change being verified).

2. Run:

   node ${CLAUDE_PLUGIN_ROOT}/scripts/ensure-browser.mjs --browser "${user_config.browser}" --mode "${user_config.mode}" --port "${user_config.cdp_port}" --url "<the verification URL>"
   

   (The ${user_config.*} values are substituted into this skill at load time; blank or literal placeholders are fine — the script defaults to chrome / profile / 9222.)

   • Exit 0 → CDP is live. Note the BROWSER_STATE: line in the output — launched-at-url, launched, or reused — step 3 branches on it.
   • Non-zero → show the script's stderr message to the user verbatim and stop. (CDP_BLOCKED_DEFAULT_PROFILE means: tell the user to switch the plugin's mode option to "profile" via /plugin → configure. BROWSER_MISMATCH means: a browser other than the configured one owns the CDP port — the user must quit it or change the browser/cdp_port option.) Do NOT probe the dev server or any tunnel URL here (hard rule above) — the app iframe render in step 4 is the only dev-server health check.