web_benchmarks testing 目录运行指南Flutter Web 基准测试的客户端-服务器端到端实践【免费下载链接】packagesA collection of useful packages maintained by the Flutter team项目地址: https://gitcode.com/GitHub_Trending/pac/packages本文以web_benchmarks包内置的 testing 目录运行说明 为主线完整梳理如何在本仓库中运行 Flutter Web 基准测试并深入到 browser.dart、runner.dart、client.dart 等源码还原从 Chrome 定位、应用构建、性能追踪到指标收率的完整链路。读完本文你既能照搬命令跑通 testing 目录下的全部基准测试也能理解 web_benchmarks 的客户端-服务器协作模型与指标计算原理为在自己的 Flutter Web 应用中编写与接入基准测试打下基础。一、testing 目录与 web_benchmarks 框架概览web_benchmarks是 Flutter 团队维护的 Flutter Web 基准测试工具包当前仅支持在 Chrome 中运行基准详见 包级 README。仓库中的 testing 目录 是一个完整的基准测试示例工程test_app一个可运行的 Flutter Web 示例应用含lib/main.dart、lib/home_page.dart、lib/about_page.dart其benchmark子目录下存放基准测试用例web_benchmarks_test.dart核心测试文件驱动真实 Chrome 运行滚动、翻页、点击等基准其余为测试基础设施benchmark/test_infra/。testing 目录下的基准采用客户端-服务器client-server模型这一点与integration_test包的思路类似一端是在浏览器内与被测应用一起运行的客户端代码另一端是负责构建产物、托管静态资源、并通过 Chrome DevTools 协议提取性能追踪数据的服务器详见 包级 README 及 server.dart 的serveWebBenchmark文档注释。后续章节会先给出官方推荐的运行步骤再逐层剖析其内部机制。二、运行前提让测试能找到 Chrometesting 目录的测试需要真实的 Chrome 浏览器测试框架通过Chrome.launch启动它browser.dart。因此第一步是安装一个测试可以找到的 Chrome。从源码看Chrome 可执行文件的定位逻辑位于_findSystemChromeExecutablebrowser.dart其查找顺序如下平台查找方式任意平台优先读取环境变量CHROME_EXECUTABLE适用于 CI 等 Chrome 位于非标准路径的环境Linux执行which google-chrome找不到则抛出Failed to locate system Chrome installation.macOS固定路径/Applications/Google Chrome.app/Contents/MacOS/Google ChromeWindows依次探测LOCALAPPDATA、PROGRAMFILES、PROGRAMFILES(X86)下的Google\Chrome\Application\chrome.exe此外还有两个环境变量会影响启动行为browser.dartCHROME_NO_SANDBOXtrue追加--no-sandbox启动参数在 Linux 无显示器环境如 CI下配合headless: true使用此时还会追加--use-glangle、--use-angleswiftshader、--enable-unsafe-swiftshader、--disable-gpu-sandbox等软件渲染参数。在本地开发机上通常只需安装好系统 Chrome 即可满足查找条件。三、三步运行 testing 目录测试官方步骤在满足 Chrome 前提后按官方 testing README 依次执行以下命令。第 1 步拉取 test_app 的依赖flutter pub get --directory testing/test_app该命令在testing/test_app目录pubspec.yaml下执行flutter pub get拉取示例应用与基准测试用例所需的依赖。第 2 步拉取 web_benchmarks 包的依赖在 web_benchmarks 包根目录 下执行flutter pub get第 3 步运行测试flutter test testing官方文档给出的参考输出如下节选00:03 0: Can run a web benchmark Launching Chrome. Launching Google Chrome 98.0.4758.102 Waiting for the benchmark to report benchmark profile. [CHROME]: [0215/133233.327761:ERROR:socket_posix.cc(150)] bind() failed: Address already in use (98) [CHROME]: [CHROME]: DevTools listening on ws://[::1]:10000/devtools/browser/4ef82be6-9b68-4fd3-ab90-cd603d25ceb1 Connecting to DevTools: ws://localhost:10000/devtools/page/21E7271507E9BC796B957E075515520F Connected to Chrome tab: (http://localhost:9999/index.html) Launching benchmark scroll Extracted 299 measured frames. Skipped 1 non-measured frames. Launching benchmark page [APP] Testing round 0... [APP] Testing round 1... ... [APP] Testing round 9... Extracted 490 measured frames. Skipped 0 non-measured frames. Launching benchmark tap [APP] Testing round 0... ... Received profile data 00:26 1: All tests passed!对这段输出做几点解读帮助判断运行是否正常bind() failed: Address already in use (98)是开发机端口占用告警属于测试过程中的常见噪音不代表测试失败——框架随后仍成功连接到了 DevToolsws://localhost:10000默认端口约定基准服务器端口9999、Chrome DevTools 调试端口10000均定义于 runner.dartExtracted N measured frames.与Skipped N non-measured frames.由BlinkTraceSummary.fromJson打印browser.dart表示从 Chrome 性能追踪中成功解析出的有效帧数[APP] Testing round 0...系列输出经/print-to-console端点由浏览器端转发打印runner.dart。注意官方文档还提示若上述步骤失效可参考 CI 中web_benchmarks_test步骤当前的实际做法同步更新本文档原始说明链接指向仓库根目录的.cirrus.yml本仓库快照中未包含该文件实际排错可结合 tool/run_tests.dart 的流程核对。四、测试内部到底发生了什么构建、启动、追踪与收率flutter test testing只是入口真正的基准驱动逻辑在 web_benchmarks_test.dart 中它通过serveWebBenchmarkserver.dart编排整个流程。该文件共注册了三个测试用例Can run a web benchmark依次运行appNavigate翻页、appScroll滚动、appTap点击三个基准入口为benchmark/test_infra/client/app_client.dartCan run a web benchmark with an alternate benchmarkPath使用benchmark/test_infra/client/simple_benchmark_path_client.dart并传入自定义benchmarkPath校验初始加载与重载时的expectedUrl指标Can run a web benchmark with wasm使用CompilationOptions.wasm()以 WebAssembly skwasm 方式编译运行校验isWasm指标。每个用例都会对全部基准名 × 全部指标 × 全部统计计算组合做存在性断言并验证totalUiFrame.average指标存在web_benchmarks_test.dart。BenchmarkServer.run()runner.dart的完整流程为校验 flutter 可执行通过ProcessManager.canRun(flutter)检查若不在 PATH 中直接抛异常构建 Web 应用执行flutter build web --profile -t entryPoint并附带--dart-defineFLUTTER_WEB_ENABLE_PROFILINGtruetreeShakeIconsfalse时追加--no-tree-shake-iconsCompilationOptions.wasm()时追加--wasm --no-strip-wasm对应 dart2wasm skwasm而默认CompilationOptions.js()对应 dart2js CanvasKit见 server.dart 文档说明托管静态资源用shelf_static提供build/web目录并对 HTML 响应附加Cross-Origin-Opener-Policy: same-origin与Cross-Origin-Embedder-Policy: require-corp头使页面处于 crossOriginIsolated 状态——skwasm 渲染器依赖 SharedArrayBuffer且该状态能获得更高精度的计时器runner.dart启动 Chrome以 headless 模式 --remote-debugging-port10000启动窗口默认 1024×1024ChromeOptions默认值见 browser.dart随后通过 WebKit Inspection Protocol 连接 DevTools 并找到打开http://localhost:9999/index.html的标签页按序运行基准服务器通过/next-benchmark逐个下发基准名每个基准运行前调用/start-performance-tracingTracing.start类别为blink,blink.user_timing见 browser.dart运行结束后/stop-performance-tracing取回追踪数据并汇总为BenchmarkResults返回。值得注意的是头部ERROR:bind()告警并不会中断流程Chrome 的 stderr 中DevTools listening ...这一行才是连接成功的信号框架会阻塞等待该行出现browser.dart。五、客户端-服务器协作模型与手动回退测试期间浏览器内运行的是 client.dart 提供的runBenchmarks客户端。它以LocalBenchmarkServerClient与服务器通过 REST 接口协作核心端点如下实现见 client.dart 与 runner.dart端点方向作用POST /next-benchmark客户端 → 服务器上报基准名列表领取下一个要运行的基准名POST /start-performance-tracing?label...客户端 → 服务器请求服务器通过 DevTools 协议开启 chrome://tracingPOST /stop-performance-tracing客户端 → 服务器停止追踪并取回原始 trace 数据POST /profile-data客户端 → 服务器上报某个基准的 Profile 数据POST /on-error客户端 → 服务器上报浏览器端异常服务器会中止整个任务POST /print-to-console客户端 → 服务器把浏览器端日志转发到服务器控制台客户端在浏览器中的print与未捕获异常都会经 zone 规范转发给服务器client.dart这就是测试输出中[APP] Testing round 0...的来源。该模型还内置了手动回退manual fallback机制当服务器不可用例如用flutter run直接调试而非走测试框架时/next-benchmark返回 404客户端据此进入手动模式——页面上会渲染一个可点击的基准名列表运行结果直接可视化打印在网页上TimeseriesVisualization会用 canvas 绘制时序柱状图见 client.dart。这使得基准既可以自动化跑也方便人工调试。六、收集哪些指标帧耗时与统计计算基准数据最终以BenchmarkScore(metric, value)形式呈现指标体系定义于 metrics.dartFlutter 帧级指标BenchmarkMetric枚举preroll_frame提交图层/图片前的预处理含变换与裁剪计算、apply_frame向渲染器提交图层与图片信息、draw_framePlatformDispatcher.onDrawFrame回调耗时、flutter_frame.total_time、flutter_frame.build_time、flutter_frame.raster_time分别对应 Flutter EngineFrameTiming的totalSpan、buildDuration、rasterDurationUI 线程整体指标totalUiFrame.average来自 Blink trace 中WebViewImpl::beginFrame脚本执行与updateAllLifecyclePhases样式、布局、绘制、合成两类事件的平均耗时之和browser.dart每个指标的统计计算BenchmarkMetricComputation.values见 metrics.dartaverage、outlierAverage、outlierRatio、noise以及p50、p90、p95三个百分位。统计采样数以kMeasuredSampleCount 100为上限common.dart测试运行时打印的Extracted N measured frames.即来自该解析过程若一个可测帧都解析不出来会抛出 No measured frames found in benchmark tracing data. 并提示可能原因帧泵不够或 Chrome 追踪格式变更同时把原始 trace 写入./chrome-trace.json便于排查browser.dart。七、结果分析计算增量与平均值跑完基准得到 JSON 结果后web_benchmarks还提供离线分析能力见 包级 README 与 analysis.dartcomputeDelta(baseline, test)计算两份基准结果的差值用于对比基线computeAverage(results...)计算多份结果的均值用于多轮合并。仓库 example/analyze_example.dart 给出了完整用法用BenchmarkResults.parse读取 JSON 文件后调用上述函数再把结果toJson()输出。该文件同样被包级 README 以?code-excerpt方式引用是编写分析脚本的直接模板。八、自动化tool/run_tests.dart仓库还提供了可脚本化的测试入口 tool/run_tests.dart其执行逻辑与三步法完全对应在testing/test_app下执行flutter pub getflutter pub get --directory的等价实现在包根目录执行flutter test testing。此外该脚本目前只在 Linux 主机上实际运行其他平台直接跳过并预留了dart run tool/run_tests.dart的调用方式说明适合接入自定义 CI 任务。需要说明的是官方测试还包含包内 test/ 目录 下的单元测试如browser_test.dart、computations_test.dart等另有 more_tests_in_testing_dir_test.dart 将 testing 目录纳入测试范围flutter test testing主要针对端到端基准用例。九、常见问题速查Failed to locate system Chrome installation.Linux 下which google-chrome找不到 Chrome请安装 Chrome 或设置CHROME_EXECUTABLE环境变量指向可执行文件flutter executable is not runnableflutter不在 PATH 中请修正环境Address already in use (98)多为开发机端口占用属噪音若 9999/10000 端口确实被占用导致连接失败可通过serveWebBenchmark的benchmarkServerPort与chromeDebugPort参数调整No measured frames found in benchmark tracing data.按错误提示检查基准是否正常泵帧或确认近期 Chrome 版本是否变更了追踪数据格式必要时核对 browser.dart 中BlinkTraceEvent的解析逻辑调试时原始 trace 会保存在./chrome-trace.json。至此从环境准备、三步运行、内部流程到结果分析web_benchmarks testing 目录的完整运行链路已全部打通后续如需编写自己的 Web 基准可参照 web_benchmarks_test.dart 与 client.dart 的runBenchmarks接口进行扩展。【免费下载链接】packagesA collection of useful packages maintained by the Flutter team项目地址: https://gitcode.com/GitHub_Trending/pac/packages创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考