Interop 2025 investigation effort - Gamepad API testing

[nondebug]

See also: #175

As part of Interop 2025, we are running an Investigation Effort to improve testability of the Gamepad API.

https://github.com/web-platform-tests/interop-gamepad

Gamepad API currently lacks WPT test coverage for most of the API surface. Automated tests only cover feature policy, not-fully-active state, and IDL.

https://github.com/web-platform-tests/wpt/blob/master/gamepad/feature-policy-gamepad.html
https://github.com/web-platform-tests/wpt/blob/master/gamepad/gamepad-default-feature-policy.https.sub.html
https://github.com/web-platform-tests/wpt/blob/master/gamepad/gamepad-supported-by-feature-policy.html
https://github.com/web-platform-tests/wpt/blob/master/gamepad/not-fully-active.html
https://github.com/web-platform-tests/wpt/blob/master/gamepad/idlharness.window.js

There are a handful of manual tests that require the tester to connect a gamepad:

https://github.com/web-platform-tests/wpt/blob/master/gamepad/events-manual.html
https://github.com/web-platform-tests/wpt/blob/master/gamepad/gamepad-dual-rumble-effect-manual.https.html
https://github.com/web-platform-tests/wpt/blob/master/gamepad/gamepad-trigger-rumble-effect-manual.https.html
https://github.com/web-platform-tests/wpt/blob/master/gamepad/getgamepads-polling-manual.html
https://github.com/web-platform-tests/wpt/blob/master/gamepad/idlharness-manual.html
https://github.com/web-platform-tests/wpt/blob/master/gamepad/timestamp-manual.html

The goal of this effort is to expand test coverage to include automated tests that exercise parts of the API that rely on simulating device behaviors (connection, disconnection, button/axis/touchpad state change, vibration).

[msub2]

Would you consider a similar approach to the WebXR Test API?

[sadym-chromium]

There is an example of specifying device simulations as a WebDriver BiDi extensiton: https://webbluetoothcg.github.io/web-bluetooth/#bluetooth-simulateAdapter-command. The connect/disconnect events can be specified in the same manner. This would allow for ergonomic testing in WPT, like in this example.

[nondebug]

Would you consider a similar approach to the WebXR Test API?

@msub2 I'm not sure how much we can reuse from the WebXR test API since it's not a WebDriver API. Some areas where I think this API should not follow WebXR:

• WebXR sets each button input separately (updateButtonState) which doesn't match how gamepad inputs are typically read by the browser. A typical gamepad sends all button and axis inputs as a single packet, and the browser updates all input fields at the same time. If we set each input separately, we lose the ability to simulate multiple inputs changing in the same input frame. This doesn't matter too much right now but might become more important if we extend the API to support input events.
• We should try to use the existing WebDriver BiDi API for simulating inputs: input.performActions. We can define Gamepad API specific actions for connecting/disconnecting gamepads and updating input state.

There is an example of specifying device simulations as a WebDriver BiDi extension

Let's figure out if we need a FakeGamepad object. If we don't need it then it's simpler to define actions for gamepad connections/disconnections instead of a simulateConnectedGamepad API.

I think it's likely that we do need a FakeGamepad object since there are cases where the gamepad is connected but not visible to the site (for instance, if a gamepad user gesture has not been received).

[sadym-chromium]

Proposed WebDriver BiDi API:

Connect gamepad

{
  method: "emulation.simulateDevice",
  params: {
    type: "gamepad",
    context: text,
    gamepad: {
      id: string,
      index: number,
      mapping: "" / "standard" / "xr-standard",
      effects: [ ("dual-rumble", "trigger-rumble") ]
    }
  }
}
Returns
{
  deviceId: UUID,
}

Disconnect gamepad

{
  method: "emulation.disableSimulation",
  params: {
    deviceId: UUID,
  }
}
Returns {}

Input emulation

Extend WebDriver BiDi input.performActions:

input.GamepadSourceActions = {
  type: "gamepad",
  id: text,
  actions: [*input.WheelSourceAction]
}

input.GamepadSourceAction = (
  input.PauseAction /
  input.GamepadAxisAction /
  input.GamepadButtonAction /
  input.GamepadTouchAction
)

[nondebug]

Gamepad spec maintainers met on March 13 and discussed the investigation effort, notes are here.

@sadym-chromium this looks like a good starting point, I think the overall shape is what we want (methods to connect/disconnect simulated gamepads, input actions to update input state).

There are two transformations performed on gamepad inputs before returning them to script, if possible I'd like to make both of these behaviors testable:

• Reordering buttons and axes
• Normalizing button and axis input values

The reordering step is trivial (and doesn't need to be tested) when reading inputs from a high-level API like XInput that already assigns a specific meaning to each button and axis. However, for generic HID gamepads the remapping step can be somewhat complex and it would be valuable to have tests to verify that the same HID gamepad is mapped consistently in different browsers. To make this testable, we need a way to provide the information that would normally be deduced from the report descriptor. We also need a way to provide the updated input values in the same logical form that the gamepad would provide them.

To test the normalization step we need the logical input value, its minimum and maximum bounds, and whether the input should be mapped as a button or an axis.

Simulating a HID gamepad would satisfy both of these, but not all platforms support HID. The test API should be allowed to omit support for simulated HID gamepads if the underlying operating system doesn't support HID. I think it would be useful to have a second simulated gamepad type to represent a non-HID gamepad. This simulated gamepad would skip the reordering step and instead require the user to define buttons and axes (with logical bounds) in the same order they should be returned in Gamepad API. The normalization step would be performed as usual.

I think it would also be useful to have a third type of simulated gamepad that skips both reordering and normalization. I expect there will be use cases where inputs are recorded through Gamepad API and then played back through a simulated gamepad. To avoid the need to convert from normalized inputs back into logical inputs we should allow tests to provide inputs in the same form they are returned in Gamepad API.

[nondebug]

Closing this issue since the Interop 2025 investigation effort is concluded.