How do you measure a Flutter checkout screen's scrolling performance with integration_test's traceAction, and why run it with flutter drive --profile?

## What you are measuring A **performance integration test** runs a real interaction - scrolling the checkout's list of items and delivery options - on a device, records what the engine did during it, and saves the numbers so you can compare runs. `integration_test` provides two tools on its binding: | Method | Records | Stored under | Typical use | |---|---|---|---| | `traceAction(action, {streams, retainPriorEvents, reportKey})` | the VM timeline during `action` | `reportKey`, default `timeline` | detailed build and raster timings, summarised on the host | | `watchPerformance(action, {reportKey})` | `FrameTiming` callbacks plus GC counts | `reportKey`, default `performance` | a quick frame-time summary without a timeline | Both write into the binding's **`reportData`**, which is sent to the host only when a **driver script** is running - that is why performance tests use `flutter drive`. ## Step 1: the on-device test - Keep the binding: `final binding = IntegrationTestWidgetsFlutterBinding.ensureInitialized();` - Build the checkout screen with realistic data (enough rows to scroll). - Wrap only the interaction you want to measure in `traceAction`. - Give every call a distinct `reportKey`; a second call with the same key overwrites the first. ## Step 2: the driver on the host The default `integrationDriver()` just writes all `reportData` into `integration_response_data.json`. For a readable result, pass a `responseDataCallback` that: 1. reads `data['checkout_scroll']` and rebuilds a `Timeline` with `Timeline.fromJson` from `package:flutter_driver`; 2. calls `TimelineSummary.summarize(timeline)`; 3. calls `summary.writeTimelineToFile('checkout_scroll', pretty: true, includeSummary: true)`. That produces, in `build/` (the test outputs directory), a `.timeline_summary.json` with aggregate numbers such as average and worst frame build and raster times, and a `.timeline.json` you can open in a trace viewer. ## Step 3: run it in profile mode ``` flutter drive \ --driver=test_driver/perf_driver.dart \ --target=integration_test/checkout_scroll_test.dart \ --profile ``` - **Why `--profile`**: `flutter drive` builds in debug by default. Debug builds run with assertions and without the optimisations of release builds, so frame times are much worse than users see and can point at problems that do not exist. Profile mode keeps release-like performance while leaving the tracing hooks the test needs. - The Flutter performance cookbook adds **`--no-dds`** when running on a mobile device or emulator, because the Dart Development Service would not be reachable from the host. - Measure on a **physical device** when the numbers matter; emulators share the host's CPU and GPU and vary run to run. ## Making the numbers useful - Warm up: scroll once outside `traceAction`, then measure, so first-use shader and image work does not dominate. - Keep data and device fixed between runs; compare trends, not single values. - Store the summary files as CI artefacts and plot the key numbers per commit. - `watchPerformance` waits for frame timings to be flushed (it delays in two-second steps), so it adds seconds to the run; that is expected, not a hang. ## What it does not tell you A timeline shows **that** frames were slow and which phase took the time; finding **why** - an expensive `build`, a `saveLayer`, a large image decode - is DevTools work on the same profile build. The integration test's job is to catch regressions automatically.