api-testing

API 测试技能

通过模拟响应、拦截请求和监控网络流量来测试 API 集成。

适用场景

此技能会在以下情况下启用：

• 用户想要测试 API 集成
• 用户需要模拟后端响应
• 用户想要模拟错误场景
• 用户询问请求拦截
• 用户需要测试离线行为

功能

响应模拟

browser-devtools-cli stub mock-http-response \
  --pattern "**/api/users" \
  --response '{"action":"fulfill","status":200,"body":[{"id":1,"name":"Test"}]}'

请求拦截

browser-devtools-cli stub intercept-http-request \
  --pattern "**/api/**" \
  --modifications '{"headers":{"Authorization":"Bearer token"}}'

网络监控

browser-devtools-cli --json o11y get-http-requests
browser-devtools-cli --json o11y get-http-requests --resource-type fetch
browser-devtools-cli --json o11y get-http-requests --status '{"min":400}'

存根管理

browser-devtools-cli stub list
browser-devtools-cli stub clear --stub-id <id>
browser-devtools-cli stub clear

常见场景

模拟成功响应

browser-devtools-cli stub mock-http-response \
  --pattern "**/api/users" \
  --response '{"action":"fulfill","status":200,"body":[{"id":1,"name":"Test"}]}'

模拟服务器错误

browser-devtools-cli stub mock-http-response \
  --pattern "**/api/checkout" \
  --response '{"action":"fulfill","status":500,"body":{"error":"Internal Server Error"}}'

模拟 404 未找到

browser-devtools-cli stub mock-http-response \
  --pattern "**/api/missing" \
  --response '{"action":"fulfill","status":404,"body":{"error":"Not Found"}}'

模拟网络超时

browser-devtools-cli stub mock-http-response \
  --pattern "**/api/slow-endpoint" \
  --response '{"action":"abort","abortErrorCode":"timedout"}'

模拟连接失败

browser-devtools-cli stub mock-http-response \
  --pattern "**/api/offline" \
  --response '{"action":"abort","abortErrorCode":"connectionfailed"}'

添加身份验证标头

browser-devtools-cli stub intercept-http-request \
  --pattern "**/api/**" \
  --modifications '{"headers":{"Authorization":"Bearer test-token"}}'

修改请求正文

browser-devtools-cli stub intercept-http-request \
  --pattern "**/api/submit" \
  --modifications '{"body":{"injected":"value"}}'

添加延迟

browser-devtools-cli stub mock-http-response \
  --pattern "**/api/slow" \
  --response '{"action":"fulfill","status":200,"body":{}}' \
  --delay-ms 3000

模拟不稳定的 API

browser-devtools-cli stub mock-http-response \
  --pattern "**/api/unreliable" \
  --response '{"action":"fulfill","status":503}' \
  --chance 0.3

一次性模拟

browser-devtools-cli stub mock-http-response \
  --pattern "**/api/once" \
  --response '{"action":"fulfill","status":200,"body":{"first":true}}' \
  --times 1

测试工作流

SESSION="--session-id api-test"

# 1. Setup mocks before navigation
browser-devtools-cli $SESSION stub mock-http-response \
  --pattern "**/api/users" \
  --response '{"action":"fulfill","status":200,"body":[{"id":1,"name":"Mock User"}]}'

# 2. Navigate to application
browser-devtools-cli $SESSION navigation go-to --url "https://app.example.com"
browser-devtools-cli $SESSION sync wait-for-network-idle

# 3. Interact with the app
browser-devtools-cli $SESSION interaction click --selector "#load-users"
browser-devtools-cli $SESSION sync wait-for-network-idle

# 4. Check network requests
browser-devtools-cli $SESSION --json o11y get-http-requests

# 5. Verify UI shows mocked data
browser-devtools-cli $SESSION content get-as-text --selector ".user-list"

# 6. List active stubs
browser-devtools-cli $SESSION stub list

# 7. Clear all stubs
browser-devtools-cli $SESSION stub clear

# 8. Cleanup
browser-devtools-cli session delete api-test

错误测试工作流

SESSION="--session-id error-test"

# Mock error response
browser-devtools-cli $SESSION stub mock-http-response \
  --pattern "**/api/checkout" \
  --response '{"action":"fulfill","status":500,"body":{"error":"Payment failed"}}'

# Navigate and trigger error
browser-devtools-cli $SESSION navigation go-to --url "https://app.example.com/checkout"
browser-devtools-cli $SESSION interaction click --selector "#pay-button"
browser-devtools-cli $SESSION sync wait-for-network-idle

# Check error handling in UI
browser-devtools-cli $SESSION content take-screenshot --name "error-state"
browser-devtools-cli $SESSION content get-as-text --selector ".error-message"

# Cleanup
browser-devtools-cli $SESSION stub clear
browser-devtools-cli session delete error-test

API 测试期间调试后端

使用真实后端进行测试时，如果需要调试端点失败或返回意外数据的原因，请使用 node-devtools-cli：

# Connect to API server process
node-devtools-cli --session-id api-debug debug connect --process-name "api"

# Set tracepoint on the handler
node-devtools-cli --session-id api-debug debug put-tracepoint \
  --url-pattern "routes/users.ts" \
  --line-number 42

# Trigger the API from browser (or curl), then get snapshots
node-devtools-cli --session-id api-debug --json debug get-probe-snapshots

# Or inspect backend console logs
node-devtools-cli --session-id api-debug --json debug get-logs --search "error"

最佳实践

1. 使用具体的匹配模式，避免模拟非目标请求
2. 测试后清除存根，避免相互干扰
3. 列出存根，以便调试意外行为
4. 使用 times 限制进行一次性模拟
5. 添加延迟以测试加载状态
6. 测试错误场景，而不仅仅是正常流程
7. 在导航前设置模拟，以测试首次加载
8. 监控实际请求，确认模拟正常工作