Back to Details

proxy

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
No MCP? The CLI has full feature parity — use 
helpmetest proxy start/stop/list
instead of 
helpmetest_proxy({...})
. See the CLI reference.
没有MCP？ CLI的功能完全一致——使用
helpmetest proxy start/stop/list
代替
helpmetest_proxy({...})
。请查看CLI参考。

HelpMeTest Proxy Setup

HelpMeTest 代理设置

Sets up proxy tunnels to test local development servers through HelpMeTest.
通过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:
  1. You start a proxy via the MCP tool — it registers a tunnel with the proxy server and spawns an frpc process
  2. The tunnel maps a domain (e.g. 
    dev.local
    ) to your local port
  3. HelpMeTest's test runner routes traffic for that domain through the tunnel back to your machine
  4. 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 (
Go To
, 
helpmetest_run_interactive_command
, etc.).
HelpMeTest的测试运行在远程基础设施上，你的本地开发服务器（localhost:3000）无法从外部访问，代理会创建一个TCP隧道：
  1. 你通过MCP工具启动代理——它会在代理服务器上注册一个隧道，并启动一个frpc进程
  2. 隧道会将一个域名（例如
    dev.local
    ）映射到你的本地端口
  3. HelpMeTest的测试运行器会将该域名的流量通过隧道路由回你的机器
  4. 你的本地服务器响应请求，就像被直接访问一样
**代理后的URL（例如http://dev.local）无法从你的本地浏览器或curl访问**，它仅在HelpMeTest的测试命令（`Go To
、
helpmetest_run_interactive_command`等）中生效。

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
  • 开发过程中针对本地主机测试
  • 将生产URL替换为本地版本
  • 路由运行在不同端口的前端和后端服务
  • 编写或运行任何本地测试之前

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" })
启动代理：
helpmetest_proxy({ action: "start", domain: "dev.local", sourcePort: 3000 })
验证生效（使用HelpMeTest，不要用curl）：
helpmetest_run_interactive_command({ command: "Go To  http://dev.local" })
应该会加载你的本地应用，如果没有加载成功，请先修复代理问题再编写测试。
查看活跃代理：
helpmetest_proxy({ action: "list" })
停止代理：
helpmetest_proxy({ action: "stop", domain: "dev.local" })

Three Proxy Strategies

三种代理策略

Strategy 1: Single Tunnel to Frontend

策略1：单隧道连接前端

When: Your dev server already proxies some routes internally (e.g., Vite's 
server.proxy
sends 
/api
to backend port)
helpmetest_proxy({ action: "start", domain: "dev.local", sourcePort: 5001 })
Tests use 
http://dev.local
— both UI and API calls work through one tunnel.
适用场景： 你的开发服务器已经在内部代理了部分路由（比如Vite的
server.proxy
将
/api
请求转发到后端端口）
helpmetest_proxy({ action: "start", domain: "dev.local", sourcePort: 5001 })
测试使用
http://dev.local
——UI和API请求都可以通过一个隧道正常工作。

Strategy 2: Separate Tunnels for Frontend and Backend

策略2：前后端分离隧道

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 
http://frontend.local
for UI and 
http://backend.local
for API.
适用场景： 服务需要不同的主机名（cookie、CORS场景），或者没有配置内部代理。
helpmetest_proxy({ action: "start", domain: "frontend.local", sourcePort: 5001 })
helpmetest_proxy({ action: "start", domain: "backend.local", sourcePort: 3001 })
测试使用
http://frontend.local
访问UI，
http://backend.local
访问API。

Strategy 3: Substitute Production with Local

策略3：将生产地址替换为本地地址

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 
http://my.awesome.app
— routes to localhost:3000 instead of production.
Port mapping:
  • domain
    — hostname in test URLs
  • externalPort
    — port in test URLs (default 80 for HTTP)
  • sourcePort
    — your local development port
适用场景： 你有针对生产URL运行的测试，想要在不修改测试代码的情况下测试本地改动。
helpmetest_proxy({ action: "start", domain: "my.awesome.app", sourcePort: 3000, externalPort: 80 })
测试使用
http://my.awesome.app
——会路由到localhost:3000而不是生产环境。
端口映射说明：
  • domain
    —— 测试URL中的主机名
  • externalPort
    —— 测试URL中的端口（HTTP默认是80）
  • sourcePort
    —— 你的本地开发端口

WebSocket Support

WebSocket支持

  • wss://
    (TLS WebSocket) works through the tunnel via CONNECT
  • ws://
    (plain WebSocket) does NOT work — browsers block non-TLS WebSocket through HTTP proxy
If your app uses WebSocket, make sure it connects over 
wss://
.
  • wss://
    （TLS加密WebSocket）可以通过CONNECT方式通过隧道正常工作
  • ws://
    （明文WebSocket）无法工作——浏览器会阻止通过HTTP代理的非TLS WebSocket请求
如果你的应用使用WebSocket，请确保它通过
wss://
连接。

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.
启动代理后，请始终使用HelpMeTest交互式命令验证：
helpmetest_run_interactive_command({ command: "Go To  http://dev.local" })
预期结果：你的本地应用成功加载。如果你看到
chrome-error://chromewebdata/
或者连接错误，说明代理没有正常工作——请先修复问题再编写测试。
不要尝试用curl或本地浏览器验证——代理仅在HelpMeTest的基础设施内部生效。

Troubleshooting

故障排查

Tests show chrome-error or connection refused

测试显示chrome错误或连接被拒绝

  1. Check proxy is running: 
    helpmetest_proxy({ action: "list" })
  2. Check local server is running: 
    curl http://127.0.0.1:3000
    (this works locally)
  3. Restart proxy if needed: Stop and start again
  1. 检查代理是否正在运行： 
    helpmetest_proxy({ action: "list" })
  2. 检查本地服务器是否正在运行： 
    curl http://127.0.0.1:3000
    （该命令在本地应该正常工作）
  3. 必要时重启代理： 先停止再重新启动

Stale frpc processes blocking new proxy

陈旧的frpc进程阻塞新代理

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: 
    ps aux | grep frpc
如果启动代理失败并提示“proxy already exists”：
  • 之前的frpc进程可能仍在使用相同名称运行
  • 先停止代理：
    helpmetest_proxy({ action: "stop", domain: "dev.local" })
  • 或者停止所有代理：
    helpmetest_proxy({ action: "stop_all" })
  • 如果MCP管理的停止命令无效，请查找孤立的frpc进程：
    ps aux | grep frpc

MCP tool shows old output format

MCP工具显示旧输出格式

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 
/mcp
.
如果代理工具的输出和本文档描述的不同，说明MCP服务器可能运行的是旧版本代码。使用
/mcp
命令重启MCP服务器。

Custom hostname not resolving

自定义主机名无法解析

Custom hostnames (like 
frontend.local
) are handled entirely by the proxy — no 
/etc/hosts
edits needed. If verification fails:
  1. Verify proxy is running with 
    list
    action
  2. Make sure you're using HTTP (not HTTPS) unless you have TLS configured
  3. Check the exact domain matches what you used in 
    start
自定义主机名（比如
frontend.local
）完全由代理处理——不需要修改
/etc/hosts
文件。如果验证失败：
  1. 使用
    list
    操作验证代理正在运行
  2. 确保你使用的是HTTP（不是HTTPS），除非你已经配置了TLS
  3. 检查使用的域名和你
    start
    操作中填写的域名完全一致

Multiple Services Example

多服务示例

undefined
undefined

Local frontend on port 5001

Local frontend on port 5001

helpmetest_proxy({ action: "start", domain: "frontend.local", sourcePort: 5001 })
helpmetest_proxy({ action: "start", domain: "frontend.local", sourcePort: 5001 })

Local backend API on port 3001

Local backend API on port 3001

helpmetest_proxy({ action: "start", domain: "api.local", sourcePort: 3001 })
helpmetest_proxy({ action: "start", domain: "api.local", sourcePort: 3001 })

Production service running locally on port 8000

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.
helpmetest_proxy({ action: "start", domain: "prod.myapp.com", sourcePort: 8000, externalPort: 80 })

现在测试可以在HelpMeTest命令中使用这三个域名。

Best Practices

最佳实践

  1. Start proxy BEFORE writing tests — don't debug test failures caused by missing proxy
  2. Always verify with HelpMeTest — use interactive commands, not curl or browser
  3. Choose simplest strategy — if frontend already proxies backend, use Strategy 1
  4. Use consistent domains — if you use 
    frontend.local
    in one test, use it in all tests for that service
  5. Stop proxies when done — 
    stop_all
    cleans up everything
Version: 0.2
  1. 在编写测试之前启动代理——不要调试因为代理缺失导致的测试失败
  2. 始终使用HelpMeTest验证——使用交互式命令，不要用curl或浏览器
  3. 选择最简单的策略——如果前端已经代理了后端，使用策略1
  4. 使用一致的域名——如果你在一个测试中使用
    frontend.local
    ，该服务的所有测试都应该使用同一个域名
  5. 使用完后停止代理——
    stop_all
    可以清理所有代理
版本： 0.2