helpmetest-proxy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HelpMeTest Proxy Setup

HelpMeTest 代理设置

Sets up proxy tunnels to test local development servers through HelpMeTest.

设置代理隧道，以通过HelpMeTest测试本地开发服务器。

Purpose

用途

HelpMeTest tests run against URLs (http://localhost, http://my.app.com). For local development, the proxy tunnels these URLs to your local ports so tests can access your dev servers.

HelpMeTest测试针对URL运行（http://localhost、http://my.app.com）。对于本地开发场景，代理会将这些URL通过隧道转发到你的本地端口，让测试可以访问你的开发服务器。

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

开发过程中针对localhost进行测试
用本地版本替换生产环境URL
路由运行在不同端口的前端和后端服务
编写或运行任何本地测试之前

Quick Start

快速开始

Basic setup:

bash

undefined

基础设置：

bash

undefined

If your app runs on port 3000

如果你的应用运行在3000端口

helpmetest proxy start localhost:3000


**Verify it works:**
```robot

helpmetest proxy start localhost:3000


**验证是否生效：**
```robot

Use HelpMeTest interactive command

使用HelpMeTest交互命令

helpmetest_run_interactive_command({ command: "Go To http://localhost" })

Should load your local app

应当加载出你的本地应用


**Then write/run tests using:**
```robot
Go To  http://localhost


**之后可以使用以下代码编写/运行测试：**
```robot
Go To  http://localhost

Three Proxy Strategies

三种代理策略

Strategy 1: Single Tunnel to Frontend

策略1：单隧道连接前端

When to use: Your dev server already proxies some routes internally (e.g.,

/api

→ backend port)

Setup:

bash

undefined

适用场景： 你的开发服务器已经在内部代理了部分路由（例如

/api

→ 后端端口）

设置方式：

bash

undefined

Frontend on port 5001, it proxies /api internally to port 3001

前端运行在5001端口，内部将/api代理到3001端口

helpmetest proxy start localhost:5001


**In tests:**
```robot
Go To  http://localhost

helpmetest proxy start localhost:5001


**测试中的用法：**
```robot
Go To  http://localhost

Both UI and /api calls work through the single tunnel

UI和/api请求都可以通过单条隧道正常工作


**Example:** Vite, webpack-dev-server with proxy configuration

---


**示例：** 配置了代理的Vite、webpack-dev-server

---

Strategy 2: Separate Tunnels for Frontend and Backend

策略2：前后端使用独立隧道

When to use:

Services need different hostnames (cookies, CORS)
You want explicit separation in tests
No internal proxy configured

Setup:

bash

undefined

适用场景：

服务需要不同的主机名（cookie、CORS要求）
你希望在测试中明确区分服务
没有配置内部代理

设置方式：

bash

undefined

Frontend on port 5001

前端运行在5001端口

helpmetest proxy start frontend.local:5001

Backend on port 3001

后端运行在3001端口

helpmetest proxy start backend.local:3001


**In tests:**
```robot
Go To  http://frontend.local      # For UI

helpmetest proxy start backend.local:3001


**测试中的用法：**
```robot
Go To  http://frontend.local      # 访问UI

API calls use http://backend.local/api

API请求使用http://backend.local/api

---

---

Strategy 3: Substitute Production with Local

策略3：用本地服务替换生产环境

When to use:

You have tests running against production URLs
Want to test local changes without modifying test code
Need production domain for cookies/sessions

Setup:

bash

undefined

适用场景：

你有针对生产环境URL运行的测试
希望测试本地变更而无需修改测试代码
需要生产域名用于cookie/会话校验

设置方式：

bash

undefined

Intercept my.awesome.app and route to local port 3000

拦截my.awesome.app请求并转发到本地3000端口

helpmetest proxy start my.awesome.app:80:3000


**In tests:**
```robot
Go To  http://my.awesome.app

helpmetest proxy start my.awesome.app:80:3000


**测试中的用法：**
```robot
Go To  http://my.awesome.app

Routes to localhost:3000 instead of production

会转发到localhost:3000而非生产环境


**The port mapping format:**
- `domain` - hostname in test URLs
- `external_port` - port in test URLs (usually 80 for HTTP, 443 for HTTPS)
- `source_port` - your local development port

**Example:** Production tests use `http://my.awesome.app:80`, but you want to test local code running on port 3000


**端口映射格式说明：**
- `domain` - 测试URL中的主机名
- `external_port` - 测试URL中的端口（HTTP通常为80，HTTPS通常为443）
- `source_port` - 你的本地开发端口

**示例：** 生产测试使用`http://my.awesome.app:80`，但你想要测试运行在3000端口的本地代码

Verification

验证

After starting proxy, always verify using HelpMeTest:

The proxy only intercepts traffic within HelpMeTest's infrastructure. Use interactive commands to verify:

robot

undefined

启动代理后，务必使用HelpMeTest验证：

代理仅会拦截HelpMeTest基础设施内的流量。使用交互命令验证：

robot

undefined

For localhost

验证localhost

helpmetest_run_interactive_command({ command: "Go To http://localhost" })

For custom hostnames

验证自定义主机名

helpmetest_run_interactive_command({ command: "Go To http://frontend.local" })

For production substitution

验证生产环境替换

helpmetest_run_interactive_command({ command: "Go To http://my.awesome.app" })


**Expected:** You should see your local app load successfully, not a connection error.

**If verification fails:** Don't write tests yet - fix the proxy setup first.

helpmetest_run_interactive_command({ command: "Go To http://my.awesome.app" })


**预期结果：** 你应该能看到本地应用成功加载，而非连接错误。

**如果验证失败：** 先不要编写测试，优先修复代理设置问题。

Troubleshooting

故障排查

Tests can't reach the URL

测试无法访问URL

Check proxy is running:

bash

ps aux | grep "helpmetest proxy"

Check local server is running:

bash

undefined

检查代理是否运行：

bash

ps aux | grep "helpmetest proxy"

检查本地服务器是否运行：

bash

undefined

Direct connection to your local port (bypasses proxy)

直接连接本地端口（绕过代理）

curl http://127.0.0.1:3000


**Check proxy output shows your tunnel:**

✓ Proxying localhost -> localhost:3000

curl http://127.0.0.1:3000


**检查代理输出是否显示你的隧道：**

✓ Proxying localhost -> localhost:3000

or

或者

✓ Proxying frontend.local -> localhost:5001


**If tunnel missing:** Restart the proxy command

---

✓ Proxying frontend.local -> localhost:5001


**如果缺少隧道：** 重启代理命令

---

Custom hostname not resolving (frontend.local, etc.)

自定义主机名无法解析（frontend.local等）

Custom hostnames are handled by the proxy - you don't need to edit

/etc/hosts

. If verification fails:

Verify proxy is running
Check the exact hostname in proxy output
Ensure you're using HTTP (not HTTPS) unless you configured SSL

自定义主机名由代理处理——你不需要编辑

/etc/hosts

。如果验证失败：

确认代理正在运行
检查代理输出中的主机名是否完全匹配
确保你使用的是HTTP（而非HTTPS），除非你配置了SSL

Production substitution not working

生产环境替换不生效

Check port mapping:

bash

undefined

检查端口映射：

bash

undefined

Wrong (missing source port)

错误（缺少源端口）

helpmetest proxy start my.awesome.app:80

Correct

正确

helpmetest proxy start my.awesome.app:80:3000


**Verify substitution:**
```robot

helpmetest proxy start my.awesome.app:80:3000


**验证替换效果：**
```robot

Use HelpMeTest to verify routing

使用HelpMeTest验证路由

helpmetest_run_interactive_command({ command: "Go To http://my.awesome.app" })

Should load from localhost:3000, not production

应当从localhost:3000加载内容，而非生产环境

undefined

undefined

Multiple Services Example

多服务示例

Complex setup with frontend, backend, and production substitution:

bash

undefined

包含前端、后端和生产替换的复杂设置：

bash

undefined

Local frontend

本地前端

helpmetest proxy start frontend.local:5001

Local backend API

本地后端API

helpmetest proxy start api.local:3001

Production service running locally

本地运行的生产服务

helpmetest proxy start prod.myapp.com:80:8000


**Tests can now use all three:**
```robot
Go To  http://frontend.local

helpmetest proxy start prod.myapp.com:80:8000


**现在测试可以使用全部三个服务：**
```robot
Go To  http://frontend.local

Make API call to http://api.local/endpoint

向http://api.local/endpoint发起API请求

Access production service at http://prod.myapp.com

访问http://prod.myapp.com的生产服务

undefined

undefined

Best Practices

最佳实践

Start proxy BEFORE writing tests - Don't waste time debugging test failures caused by proxy not running
Always verify with HelpMeTest - Use
```
helpmetest_run_interactive_command
```
to confirm routing works before writing automated tests
Choose simplest strategy - If frontend already proxies backend, use Strategy 1 (single tunnel)
Keep proxy running - Start in background/separate terminal, don't restart unnecessarily
Use consistent hostnames - If you use
```
frontend.local
```
in one test, use it in all tests for that service

编写测试前先启动代理——不要浪费时间调试由代理未运行导致的测试失败
始终使用HelpMeTest验证——在编写自动化测试前，使用
```
helpmetest_run_interactive_command
```
确认路由正常工作
选择最简单的策略——如果前端已经代理了后端，使用策略1（单隧道）即可
保持代理运行——在后台/独立终端启动，无需不必要的重启
使用统一的主机名——如果你在一个测试中使用
```
frontend.local
```
，该服务的所有测试都应使用相同的主机名

Output Messages

输出信息说明

Success:

✓ Proxying localhost -> localhost:3000

Already exists (safe to ignore):

[W] new proxy type error: proxy already exists

Means tunnel is already registered - your tests will still work.

Version: 0.1

成功：

✓ Proxying localhost -> localhost:3000

已存在（可安全忽略）：

[W] new proxy type error: proxy already exists

表示隧道已经注册，你的测试仍然可以正常工作。

版本： 0.1