webpagetest/agent

wptagent

![travis]([***]

跨平台WebPageTest代理

镜像概述和主要用途

wptagent是一款跨平台的WebPageTest测试代理，用于执行网页性能测试。它能够与WebPageTest服务器配合，在不同操作系统和浏览器环境下对网页加载性能、脚本执行、请求处理等进行全面测试，并支持流量控制、视频捕获等高级功能。

核心功能和特性

• 跨平台支持：兼容Linux、Windows、OSX（Intel和Apple Silicon）及Android（需tethered主机）
• 多浏览器兼容：支持Chrome、Firefox、Opera、Brave、Microsoft Edge等多种浏览器及其不同版本
• 流量控制：提供多种流量 shaping 方式，包括NetEm、远程服务器控制、Chrome开发者工具等
• 视频捕获：支持指定帧率（1-60 FPS）的视频录制，Linux平台可配合Xvfb实现无头测试
• 脚本命令：支持导航、执行脚本、阻止请求、设置头信息等丰富的测试脚本命令
• 灵活配置：可通过命令行参数配置代理名称、服务器连接、认证信息等
• 健康检查：内置HTTP健康检查接口，便于监控代理运行状态

支持的平台/浏览器

Linux（带显示器或使用Xvfb无头模式）

• Chrome（Stable、Beta和Unstable）
• Firefox（Stable和Nightly）
• Opera（Stable、Beta和Developer）
• Brave（Stable、Beta、Dev和Nightly）
• Microsoft Edge（Dev）
• Epiphany（Ubuntu 20.04+）
• Vivaldi

Windows

• Chrome（Stable、Beta、Dev和Canary）
• Firefox（Stable、ESR、Developer Edition、Beta和Nightly）
• Microsoft Edge（Legacy和基于Chromium的版本）
• Internet Explorer
• Opera（Stable、Beta和Developer）
• Brave（Stable、Beta、Dev和Nightly）

OSX - Intel和Apple Silicon

• Chrome（Stable和Canary）
• Firefox（Stable和Nightly）
• Safari（iOS模拟器）

Android（需要tethered主机 - 推荐使用Raspberry Pi）

• Chrome（Stable、Beta、Dev和Canary）
• Samsung Internet
• 黑盒测试浏览器（仅单页面加载、视觉指标）：Chrome、Samsung Browser、Opera、Opera Mini、UC Browser、UC Mini、Firefox（Stable和Beta）

已知问题

• Internet Explorer不支持操作请求（添加头信息、阻止请求等功能）

安装

安装文档详见此处

使用Docker运行

有关如何在Docker容器中运行代理的详细信息，请查看Docker说明文档

详细使用方法和配置说明

命令行选项

基本代理配置

• -v：增加详细程度（多次指定可获取更多信息），-vvvv用于完整调试输出
• --name：代理名称（默认为机器主机名）
• --exit：指定分钟后退出，适用于定期维护或更新的场景
• --dockerized：标识代理在Docker容器内运行
• --ec2：从EC2用户数据加载配置设置
• --gce：从GCE用户数据加载配置设置
• --log：将严重错误记录到指定文件
• --healthcheckport：HTTP健康检查端口（默认8889，设为0禁用），代理正常运行时返回200，否则返回503

视频捕获/显示设置

• --xvfb：使用xvfb虚拟显示器进行无头测试（仅Linux）
• --fps：视频捕获帧率（默认10，有效范围1-60，仅Linux）

服务器/位置配置（必填项）

• --server：WebPageTest工作URL（例如：[***]
• --location：位置ID（如服务器locations.ini中配置）
• --validcertificate：验证服务器证书（HTTPS服务器，默认False）
• --key：位置密钥（如果在locations.ini中配置）

流量控制选项

• --shaper：覆盖默认流量控制器，支持以下值：
  • none：禁用流量控制（root不可用时）
  • netem,<interface>：使用NetEm桥接rndis流量（指定出站接口，如--shaper netem,eth0）
  • remote,<server>,<down pipe>,<up pipe>：通过ssh连接远程服务器使用dummynet管道（需预先授权root用户ssh密钥）
  • chrome：使用Chrome开发者工具流量控制（仅支持Chromium浏览器，作为最后选择）

Android测试选项

• --android：在连接的Android设备上运行测试
• --device：设备ID（仅多设备连接时需要）
• --gnirehtet：使用gnirehtet进行反向tethering，格式：<external interface>,<dns>（如--gnirehtet eth0,8.8.8.8）
• --tether：Android <7使用-reverse-tether，格式同上
• --tether2：使用-reverse-tether v2（推荐方式），格式同上
• --simplert：使用SimpleRT进行反向tethering，格式：<interface>,<dns1>（如--simplert eth0,8.8.8.8）
• --rndis：已弃用，Android <6.0使用，支持静态地址（如--rndis 192.168.0.8/24,192.168.0.1,8.8.8.8,8.8.4.4）或dhcp

代理与服务器认证选项

• --username：WebPageTest服务器HTTP基本认证用户名
• --password：WebPageTest服务器HTTP基本认证密码
• --cert：客户端证书（用于服务器连接认证）
• --certkey：客户端私钥（如未嵌入证书中）

命令行本地运行测试选项

测试结果以JSON格式输出到stdout，提供服务器信息时会上传测试结果并返回测试ID。

• --testurl：运行指定URL的一次性测试（必填，除非提供testspec），格式：<url>
• --testspec：提供JSON测试参数文件，格式：<path>（详见测试选项文档）
• --testout：输出格式，可选值：id（测试ID）、url（结果URL）、json（原始JSON结果）
• --testoutdir：原始测试结果输出目录，格式：<path>（可选）
• --testruns：测试运行次数，默认1
• --testrv：包含重复视图测试（默认仅首次视图）

当前支持的脚本命令

• navigate、exec (execAndWait)、block、sleep、logData、combineSteps
• setEventName、setUserAgent、setBrowserSize、setViewportSize、setDeviceScaleFactor
• setActivityTimeout、setTimeout、blockDomains、blockDomainsExcept、setDns、setDnsName
• setHeader、addHeader、resetHeaders、setCookie、setABM、click (clickAndWait)
• selectValue、sendClick、setInnerHTML、setInnerText、setValue、submitForm、overrideHost

不支持的脚本命令（无实现计划）

• sendKeyDown、setDOMElement、waitForComplete、overrideHostUrl、ignoreErrors、logErrors
• loadFile、loadVariables、minInterval、endInterval、expireCache、requiredRequest
• setDOMRequest、waitForJSDone（更改为控制台日志消息语义）、if/else/endif

贡献

项目有两个不同许可的开发分支：

• master分支（主要开发分支）：采用Polyform Shield 1.0.0许可
• apache分支：采用Apache 2.0许可 欢迎向任一分支提交拉取请求。