Blank page in the inspector
If the inspector loads but the resource iframe is blank:- Check the browser console for errors (especially CSP or CORS issues)
- Make sure your resource component is the default export from
src/resources/{name}/{name}.tsx - Verify you have at least one simulation in
tests/simulations/that references your tool
sunpeak inspect --server), verify your MCP server is running and reachable at the URL you provided.
Tests failing with iframe errors
E2E tests must use the double-iframe locator pattern because resource content renders inside a nested sandbox:mcp fixture from sunpeak/test, result.app() returns a locator already scoped to the inner iframe, so you don’t need to chain frameLocator manually:
Flaky E2E tests
The double-iframe sandbox proxy can be overwhelmed by too many concurrent Playwright workers. If you see PostMessage relay timeouts or intermittent failures:- Limit workers to 2 locally (
workers: 2in your Playwright config) - In CI, use 1 worker (
workers: process.env.CI ? 1 : 2)
defineConfig() from sunpeak/test/config sets these defaults automatically.
Live test authentication
'Not logged into ChatGPT' error
'Not logged into ChatGPT' error
On first run, a browser window opens for you to log in to ChatGPT. The session is saved to
.auth/chatgpt.json but typically only lasts a few hours because Cloudflare’s cf_clearance cookie is HttpOnly and cannot be persisted across runs. When you see this error, just re-authenticate in the browser window that opens. If it keeps failing, delete the .auth/ directory and run pnpm test:live again.Tunnel not reachable
Tunnel not reachable
Verify your tunnel is running and the URL is correct. The test checks the tunnel’s
/health endpoint before proceeding.'ChatGPT DOM may have changed' warning
'ChatGPT DOM may have changed' warning
ChatGPT occasionally updates their UI. The
ChatGPTPage class checks selector health at startup. If selectors are stale, update the SELECTORS constant in chatgpt-page.mjs.Tool not called by ChatGPT
Tool not called by ChatGPT
Live tests use specific prompts like “Use the show-albums tool to…” to reliably trigger tool calls. If a tool isn’t called, the test retries once. Persistent failures may indicate the tool isn’t properly connected — check ChatGPT settings.
For dev server, tunnel, and build-related troubleshooting, see App Framework Troubleshooting.