No MCP? The CLI has full feature parity — use
helpmetest proxy start/stop/list
instead of
. See the
CLI reference.
HelpMeTest Proxy Setup
Sets up proxy tunnels to test local development servers through HelpMeTest.
How It Works
HelpMeTest tests run on remote infrastructure. Your local dev server (localhost:3000) is not reachable from there. The proxy creates a TCP tunnel:
- You start a proxy via the MCP tool — it registers a tunnel with the proxy server and spawns an frpc process
- The tunnel maps a domain (e.g. ) to your local port
- HelpMeTest's test runner routes traffic for that domain through the tunnel back to your machine
- Your local server responds as if accessed directly
The proxied URL (e.g. http://dev.local) is NOT accessible from your local browser or curl. It only works inside HelpMeTest test commands (
,
helpmetest_run_interactive_command
, etc.).
When to Use
- Testing against localhost during development
- Substituting production URLs with local versions
- Routing frontend and backend on different ports
- Before writing or running any local tests
Quick Start
Start a proxy:
helpmetest_proxy({ action: "start", domain: "dev.local", sourcePort: 3000 })
Verify it works (use HelpMeTest, NOT curl):
helpmetest_run_interactive_command({ command: "Go To http://dev.local" })
Should load your local app. If it doesn't, fix the proxy before writing tests.
Check active proxies:
helpmetest_proxy({ action: "list" })
Stop a proxy:
helpmetest_proxy({ action: "stop", domain: "dev.local" })
Three Proxy Strategies
Strategy 1: Single Tunnel to Frontend
When: Your dev server already proxies some routes internally (e.g., Vite's
sends
to backend port)
helpmetest_proxy({ action: "start", domain: "dev.local", sourcePort: 5001 })
Tests use
— both UI and API calls work through one tunnel.
Strategy 2: Separate Tunnels for Frontend and Backend
When: Services need different hostnames (cookies, CORS), or no internal proxy configured.
helpmetest_proxy({ action: "start", domain: "frontend.local", sourcePort: 5001 })
helpmetest_proxy({ action: "start", domain: "backend.local", sourcePort: 3001 })
Tests use
for UI and
for API.
Strategy 3: Substitute Production with Local
When: You have tests running against production URLs and want to test local changes without modifying test code.
helpmetest_proxy({ action: "start", domain: "my.awesome.app", sourcePort: 3000, externalPort: 80 })
Tests use
— routes to localhost:3000 instead of production.
Port mapping:
- — hostname in test URLs
- — port in test URLs (default 80 for HTTP)
- — your local development port
WebSocket Support
- (TLS WebSocket) works through the tunnel via CONNECT
- (plain WebSocket) does NOT work — browsers block non-TLS WebSocket through HTTP proxy
If your app uses WebSocket, make sure it connects over
.
Verification
After starting a proxy, always verify using HelpMeTest interactive commands:
helpmetest_run_interactive_command({ command: "Go To http://dev.local" })
Expected: Your local app loads successfully. If you see
chrome-error://chromewebdata/
or a connection error, the proxy is not working — fix it before writing tests.
Do NOT try to verify with curl or your local browser — the proxy only works inside HelpMeTest's infrastructure.
Troubleshooting
Tests show chrome-error or connection refused
- Check proxy is running:
helpmetest_proxy({ action: "list" })
- Check local server is running:
curl http://127.0.0.1:3000
- Restart proxy if needed: Stop and start again
Stale frpc processes blocking new proxy
If starting a proxy fails with "proxy already exists":
- A previous frpc process may still be running with the same name
- Stop the proxy first:
helpmetest_proxy({ action: "stop", domain: "dev.local" })
- Or stop all:
helpmetest_proxy({ action: "stop_all" })
- If MCP-managed stop doesn't work, check for orphaned frpc processes:
MCP tool shows old output format
If the proxy tool output looks different from what's documented here, the MCP server may be running old code. Restart the MCP server with
.
Custom hostname not resolving
Custom hostnames (like
) are handled entirely by the proxy — no
edits needed. If verification fails:
- Verify proxy is running with action
- Make sure you're using HTTP (not HTTPS) unless you have TLS configured
- Check the exact domain matches what you used in
Multiple Services Example
# Local frontend on port 5001
helpmetest_proxy({ action: "start", domain: "frontend.local", sourcePort: 5001 })
# Local backend API on port 3001
helpmetest_proxy({ action: "start", domain: "api.local", sourcePort: 3001 })
# Production service running locally on port 8000
helpmetest_proxy({ action: "start", domain: "prod.myapp.com", sourcePort: 8000, externalPort: 80 })
Tests can now use all three domains inside HelpMeTest commands.
Best Practices
- Start proxy BEFORE writing tests — don't debug test failures caused by missing proxy
- Always verify with HelpMeTest — use interactive commands, not curl or browser
- Choose simplest strategy — if frontend already proxies backend, use Strategy 1
- Use consistent domains — if you use in one test, use it in all tests for that service
- Stop proxies when done — cleans up everything
Version: 0.2