Add real WebDriver pointer actions to package:integration_test on the web - #195207

Adds a first-class way for Flutter web integration tests to drive the real browser mouse through WebDriver: clicks, hovers, drags, and arbitrary pointer action sequences with any mouse button.

WidgetTester.tap, WidgetTester.drag and binding.handlePointerEvent inject synthetic events straight into the framework. They skip the browser's own DOM hit testing and event dispatch, which is what decides whether a pointer event lands on Flutter content or on a platform view (<iframe>, map, video) underneath it. So features that depend on browser hit testing, such as pointer handling over platform views, couldn't be checked end to end. Until now the only workaround was to misuse binding.takeScreenshot as an RPC and drive the mouse from inside the host's onScreenshot callback.

New API

On IntegrationTestWidgetsFlutterBinding:

• Future<void> webDriverPointerActions(List<WebDriverPointerAction> actions, {FlutterView? view}) performs actions in order as one real browser pointer sequence and completes once the browser has dispatched every event in it.
• Future<void> webDriverClick(Offset position, {FlutterView? view}) is a convenience wrapper that moves to position and presses and releases the primary button.

In package:integration_test/common.dart (which integration_test.dart does not re-export, so tests import it directly):

• sealed class WebDriverPointerAction, created with WebDriverPointerAction.move(x, y, {Duration duration}), .down({WebDriverMouseButton button}), .up({WebDriverMouseButton button}) and .pause(Duration duration). The concrete classes are WebDriverPointerMove, WebDriverPointerDown, WebDriverPointerUp and WebDriverPointerPause, with toJson/fromJson, value equality and readable toString.
• enum WebDriverMouseButton { primary, middle, secondary }, whose w3cButton is the W3C button index (0, 1, 2), not a Flutter kPrimaryButton-style bit flag.
• WebDriverCommandType.pointerActions and WebDriverCommand.pointerActions(actions) in the web command protocol.
• CallbackManager.pointerActions(List<WebDriverPointerAction> actions), which completes with an UnsupportedError by default.

For example, a drag split across two calls so the test can assert on the intermediate state:

final Offset start = tester.getCenter(find.byKey(dragHandleKey));
await binding.webDriverPointerActions(<WebDriverPointerAction>[
  WebDriverPointerAction.move(start.dx, start.dy),
  const WebDriverPointerAction.down(),
  WebDriverPointerAction.move(start.dx + 100, start.dy, duration: const Duration(milliseconds: 300)),
]);
// ...assert mid-drag...
await binding.webDriverPointerActions(<WebDriverPointerAction>[
  const WebDriverPointerAction.up(),
]);

How it works

• Move positions are logical positions in the target view (for example from tester.getCenter). webDriverPointerActions converts them to viewport CSS pixels by adding the view host element's getBoundingClientRect() origin, so full-page, embedded and multi-view apps all work. The command travels over the same handshake as screenshot.
• integrationDriver (in integration_test_driver_extended.dart) sends the whole sequence as a single W3C perform-actions request for one mouse input source and replies only after WebDriver has performed it. Tests can assert right after the await with no fixed sleeps, and no onScreenshot callback is needed.
• ChromeDriver performs a timed pointerMove as a single mousemove at the end. To make the browser see intermediate events during drags and hovers, the driver splits each timed move into straight-line steps of about 16 ms, starting from the previous move's position (remembered across calls within one integrationDriver run) and capped at one step per pixel. Positions are rounded to whole CSS pixels.
• Pressed buttons stay pressed across calls until released with up.
• Invalid input fails fast in the browser: an empty sequence, non-finite move coordinates, or negative durations throw ArgumentError before anything is sent, and calling without a view when there is no implicit view throws StateError. Off the web, both methods throw UnsupportedError.
• If the driver isn't a WebFlutterDriver, the host fails the in-browser call and throws a StateError. If WebDriver throws (for example, coordinates out of bounds), the host releases pressed buttons, fails the in-browser call, and rethrows the original error, so the test fails at once instead of hanging.
• Neither method changes binding.shouldPropagateDevicePointerEvents. Real browser events reach the test binding as device events, so a test that asserts on Flutter widget gestures has to opt in with binding.shouldPropagateDevicePointerEvents = true. Platform view DOM listeners get the native events either way.

Tests

• New web e2e webdriver_pointer_actions_integration, registered in run_web_tests.dart for CanvasKit and --wasm in profile mode. It checks that a real click reaches a same-origin <iframe> platform view (which tester.tap can't do), that a click reaches a Flutter button only once device pointer events are opted in, that position conversion still works when the view's host element is offset in the page, that a timed drag produces intermediate pointer moves, that buttons stay pressed across calls for a split drag, and that moving without a button hovers.
• New unit tests in packages/integration_test/test/webdriver_command_test.dart cover action serialization, equality and fromJson validation, the pointerActions command, the CallbackManager default, input validation, and the off-web UnsupportedError.
• New unit tests in packages/integration_test/test/integration_driver_pointer_actions_test.dart cover the W3C request integrationDriver builds (rounding, timed-move subdivision across requests, pauses and buttons) and its error handling for non-web drivers, WebDriver failures and malformed action JSON.

Compatibility

CallbackManager.pointerActions has a default body, so classes that extend CallbackManager keep compiling. A class that implements it would need to add pointerActions. The binding's callbackManager can't be swapped out, though, so outside code shouldn't have a real implementation. common.dart is not re-exported from integration_test.dart, so no new names enter the scope of existing tests.

Part of #179806

Pre-launch Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I read the AI contribution guidelines and understand my responsibilities, or I am not using AI tools.
• I read the Tree Hygiene wiki page, which explains my responsibilities.
• I read and followed the Flutter Style Guide, including Features we expect every widget to implement.
• I signed the CLA.
• I listed at least one issue that this PR fixes in the description above.
• I updated/added relevant in-code documentation (doc comments with ///).
• If this PR introduces a new feature or capability, I created and linked a website documentation issue or PR in flutter/website (or verified none is needed).
• I added new tests to check the change I am making, or this PR is test-exempt.
• I followed the breaking change policy and added Data Driven Fixes where supported.
• All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel on Discord.

If this change needs to override an active code freeze, provide a comment explaining why. The code freeze workflow can be overridden by code reviewers. See pinned issues for any active code freezes with guidance.

Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. Comments from the gemini-code-assist bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.