DEV/flutter_flutter
1
0
Fork 0
mirror of https://github.com/flutter/flutter.git synced 2026-01-09 07:51:35 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add structured warning event for slow wireless debugging on iOS 26+ d… (#176673)

Browse Source 
This PR improves the developer experience when running or debugging
Flutter apps on iOS 26+ devices connected via WiFi. The tool now emits a
structured `app.warning` event (in addition to a console warning) when
it detects wireless debugging on iOS 26 or later. This allows IDEs and
other tools using `--machine` mode to display a prominent warning to
users, encouraging them to use a wired (USB) connection for better
performance.

## Details

- Detects when an iOS device is:
  - Running iOS 26 or later,
  - Connected wirelessly,
  - Debugging is enabled.
- Emits a human-readable warning to the console.
- Emits a structured `app.warning` event with relevant metadata
(category, deviceId, iosVersion, suggestion, etc.) for IDEs and tools
using `--machine` mode.
- No changes to existing workflows for users not matching these
conditions.

*List which issues are fixed by this PR. You must list at least one
issue. An issue is not required if the PR fixes something trivial like a
typo.*
Fixes #176206 

*If you had to change anything in the [flutter/tests] repo, include a
link to the migration guide as per the [breaking change policy].*

## Pre-launch Checklist

- [X] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [X] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [X] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [X] I signed the [CLA].
- [X] I listed at least one issue that this PR fixes in the description
above.
- [] I updated/added relevant documentation (doc comments with `///`).
- [] 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.
- [X] All existing and new tests are passing.

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

**Note**: The Flutter team is currently trialing the use of [Gemini Code
Assist for
GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code).
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.

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview
[Tree Hygiene]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
[test-exempt]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md
[Features we expect every widget to implement]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes
[Discord]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md
[Data Driven Fixes]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md
This commit is contained in:
Elijah Okoroh 2025-10-08 12:06:34 -07:00 committed by GitHub
parent c56e52be07
commit 2586c9c18e
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 123 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
packages/flutter_tools/doc/daemon.md
View File

@ -183,6 +183,18 @@ This is sent once the application launch process is complete and the app is eith
This is sent when output is logged for a running application. The `params` field will be a map with the fields `appId` and `log`. The `log` field is a string with the output text. If the output indicates an error, an `error` boolean field will be present, and set to `true`.
#### app.warning
This is sent when a warning is issued for a running application that an editor may wish to handle specifically. The `params` field will be a map with the following fields:
- `warningId`: A unique string identifying the warning type, suitable for client-side suppression.
- `warning`: A string containing the warning message to be displayed to the user.
- `category`: A string used to categorize the warning (for example, `ios-wireless-performance`).
- `deviceId`: The ID of the device this warning is relevant to.
- `deviceOsVersion`: An optional string representing the OS version of the device.
- `actionable`: A boolean indicating if the warning includes a suggested action for the user.
- `url`: An optional string containing a URL with more information about the warning.
#### app.progress
This is sent when an operation starts and again when it stops. When an operation starts, the event contains the fields `id`, an opaque identifier, and `message` containing text describing the operation. When that same operation ends, the event contains the same `id` field value as when the operation started, along with a `finished` bool field with the value true, but no `message` field.

31
packages/flutter_tools/lib/src/ios/devices.dart
View File

@ -494,6 +494,8 @@ class IOSDevice extends Device {
);
}
warnIfSlowWirelessDebugging(debuggingOptions);
if (!prebuiltApplication) {
_logger.printTrace('Building ${package.name} for $id');
@ -774,6 +776,35 @@ class IOSDevice extends Device {
}
}
@visibleForTesting
void warnIfSlowWirelessDebugging(DebuggingOptions debuggingOptions) {
// The minimum iOS version where wireless debugging is known to be slow.
const minSlowWirelessDebugIOSVersion = 26;
final Version? sdkVersion = this.sdkVersion;
if (!isWirelesslyConnected ||
!debuggingOptions.debuggingEnabled ||
sdkVersion == null ||
sdkVersion.major < minSlowWirelessDebugIOSVersion) {
return;
}
final warningMessage =
'Wireless debugging on iOS ${sdkVersion.major} may be slower than expected. '
'For better performance, consider using a wired (USB) connection.';
_logger.printWarning(warningMessage);
_logger.sendEvent('app.warning', <String, Object?>{
'warningId': 'ios-wireless-slow',
'warning': warningMessage,
'category': 'ios-wireless-performance',
'deviceId': id,
'deviceOsVersion': sdkVersion.major,
'actionable': true,
});
}
void _printInstallError(Directory bundle) {
_logger.printError('Could not run ${bundle.path} on $id.');
_logger.printError('Try launching Xcode and selecting "Product > Run" to fix the problem:');

80
packages/flutter_tools/test/general.shard/ios/ios_device_start_prebuilt_test.dart
View File

@ -1289,6 +1289,86 @@ void main() {
},
);
group('IOSDevice warnIfSlowWirelessDebugging', () {
testWithoutContext('prints warning for slow wireless debugging on iOS 26+', () async {
final logger = BufferLogger.test();
final IOSDevice device = setUpIOSDevice(
sdkVersion: '26.0.0',
logger: logger,
interfaceType: DeviceConnectionInterface.wireless,
);
expect(device.isWirelesslyConnected, isTrue);
device.warnIfSlowWirelessDebugging(DebuggingOptions.enabled(BuildInfo.debug));
const warningMessage =
'Wireless debugging on iOS 26 may be slower than expected. '
'For better performance, consider using a wired (USB) connection.';
expect(logger.warningText, contains(warningMessage));
final event = json.decode(logger.eventText) as Map<String, dynamic>;
expect(event['name'], 'app.warning');
final args = event['args'] as Map<String, dynamic>;
expect(
args,
equals(<String, Object?>{
'warningId': 'ios-wireless-slow',
'warning': warningMessage,
'category': 'ios-wireless-performance',
'deviceId': '123',
'deviceOsVersion': 26,
'actionable': true,
}),
);
});
testWithoutContext(
'does not print slow wireless debugging warning on iOS less than 26',
() async {
final logger = BufferLogger.test();
final IOSDevice device = setUpIOSDevice(
sdkVersion: '25.0',
logger: logger,
interfaceType: DeviceConnectionInterface.wireless,
);
device.warnIfSlowWirelessDebugging(DebuggingOptions.enabled(BuildInfo.debug));
expect(logger.warningText, isEmpty);
expect(logger.eventText, isEmpty);
},
);
testWithoutContext(
'does not print slow wireless debugging warning for wired device',
() async {
final logger = BufferLogger.test();
final IOSDevice device = setUpIOSDevice(sdkVersion: '26.0', logger: logger);
device.warnIfSlowWirelessDebugging(DebuggingOptions.enabled(BuildInfo.debug));
expect(logger.warningText, isEmpty);
expect(logger.eventText, isEmpty);
},
);
testWithoutContext(
'does not print slow wireless debugging warning for release mode',
() async {
final logger = BufferLogger.test();
final IOSDevice device = setUpIOSDevice(
sdkVersion: '26.0',
logger: logger,
interfaceType: DeviceConnectionInterface.wireless,
);
device.warnIfSlowWirelessDebugging(DebuggingOptions.disabled(BuildInfo.release));
expect(logger.warningText, isEmpty);
expect(logger.eventText, isEmpty);
},
);
});
group('IOSDevice.startApp attaches in debug mode via device logging', () {
late FakeMDnsVmServiceDiscovery mdnsDiscovery;
setUp(() {