Skip to content

Commit 42d685b

Browse files
authored
[flutter_tools] Intercept prohibited hot reloads in widget preview and trigger hot restart (flutter#193447)
When hot reload fails due to unsupported changes (such as class hierarchy modifications, global initializer changes, or file additions/deletions) in `flutter widget-preview`, automatically fall back to a hot restart instead of leaving the previewer in a failed reload state. ### Changes - **`ResidentWebRunner`**: Attach `updateFSReport` to the failed `OperationResult` when `_updateDevFS` fails so callers can inspect `UpdateFSReport.hotReloadRejected`. - **`WidgetPreviewStartCommand`**: Introduce `handleReload()` (invoked inside `_triggerReload` for `.hotReload` requests so the fallback remains serialized with other reload and restart requests, and add a `@visibleForTesting` `widgetPreviewApp` setter), which checks if `restart()` returned an `OperationResult` with `UpdateFSReport(hotReloadRejected: true)`. When rejected, log a status message (`kHotReloadRejectedMessage`) and invoke `restart(fullRestart: true)`. Fixes flutter#192697 ## 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. - [x] I updated/added relevant documentation (doc comments with `///`). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing. <!-- 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/ [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
1 parent b94e204 commit 42d685b

4 files changed

Lines changed: 151 additions & 7 deletions

File tree

‎packages/flutter_tools/lib/src/commands/widget_preview.dart‎

Lines changed: 28 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ import '../cache.dart';
2525
import '../context/tool_context.dart';
2626
import '../convert.dart';
2727
import '../dart/analysis.dart';
28+
import '../devfs.dart';
2829
import '../device.dart';
2930
import '../features.dart';
3031
import '../isolated/resident_web_runner.dart';
@@ -134,7 +135,8 @@ abstract base class WidgetPreviewSubCommandBase extends FlutterCommand {
134135
/// The type of reload operation queued to run once [WidgetPreviewStartCommand._reloadMutex]
135136
/// is available.
136137
enum _PendingReload {
137-
/// Perform a hot reload (`restart(fullRestart: false)`).
138+
/// Perform a hot reload via [WidgetPreviewStartCommand.handleReload], which
139+
/// falls back to a hot restart if the reload is rejected.
138140
hotReload,
139141

140142
/// Perform a full hot restart (`restart(fullRestart: true)`).
@@ -211,6 +213,10 @@ final class WidgetPreviewStartCommand extends WidgetPreviewSubCommandBase with C
211213
'Failed to locate browser. Make sure you are using an up-to-date Chrome or Edge. '
212214
'Otherwise, consider running with --$kWebServer instead.';
213215

216+
@visibleForTesting
217+
static const kHotReloadRejectedMessage =
218+
'Hot reload rejected due to unsupported changes. Performing hot restart instead.';
219+
214220
@override
215221
Future<Set<DevelopmentArtifact>> get requiredArtifacts async => const <DevelopmentArtifact>{
216222
// Ensure the Flutter Web SDK is installed.
@@ -311,6 +317,9 @@ final class WidgetPreviewStartCommand extends WidgetPreviewSubCommandBase with C
311317
@visibleForTesting
312318
ResidentRunner? get widgetPreviewApp => _widgetPreviewApp;
313319

320+
@visibleForTesting
321+
set widgetPreviewApp(ResidentRunner? value) => _widgetPreviewApp = value;
322+
314323
/// Serializes initial preview scaffold startup and subsequent hot reload / hot
315324
/// restart operations so reloads cannot execute before the debug connection is
316325
/// established or overlap with an in-flight reload.
@@ -493,6 +502,18 @@ final class WidgetPreviewStartCommand extends WidgetPreviewSubCommandBase with C
493502
}
494503
}
495504

505+
/// Hot reloads the previewer, falling back to a hot restart if the reload is
506+
/// rejected due to unsupported changes.
507+
@visibleForTesting
508+
Future<OperationResult?> handleReload() async {
509+
final OperationResult? result = await _widgetPreviewApp?.restart();
510+
if (result case OperationResult(updateFSReport: UpdateFSReport(hotReloadRejected: true))) {
511+
logger.printStatus(kHotReloadRejectedMessage);
512+
return _widgetPreviewApp?.restart(fullRestart: true);
513+
}
514+
return result;
515+
}
516+
496517
Future<void> _triggerReload(_PendingReload requested) async {
497518
// Record the requested reload type. If a task is already queued waiting for
498519
// [_reloadMutex], coalesce this request into the pending one (upgrading a
@@ -515,7 +536,12 @@ final class WidgetPreviewStartCommand extends WidgetPreviewSubCommandBase with C
515536
return;
516537
}
517538
try {
518-
await _widgetPreviewApp?.restart(fullRestart: pending == .hotRestart);
539+
switch (pending) {
540+
case .hotReload:
541+
await handleReload();
542+
case .hotRestart:
543+
await _widgetPreviewApp?.restart(fullRestart: true);
544+
}
519545
} on Object catch (e, st) {
520546
logger.printTrace('Error during widget preview reload: $e\n$st');
521547
}

‎packages/flutter_tools/lib/src/isolated/resident_web_runner.dart‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -525,7 +525,7 @@ class ResidentWebRunner extends ResidentRunner {
525525
),
526526
);
527527
}
528-
return OperationResult(1, 'Failed to recompile application.');
528+
return OperationResult(1, 'Failed to recompile application.', updateFSReport: report);
529529
}
530530
} else {
531531
report = null;

‎packages/flutter_tools/test/commands.shard/permeable/widget_preview/widget_preview_test.dart‎

Lines changed: 121 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -156,8 +156,9 @@ class FakeCustomBrowserDevice extends Fake implements ChromiumDevice {
156156
}
157157

158158
class FakeResidentRunner extends Fake implements ResidentRunner {
159-
FakeResidentRunner({this.waitForAppToFinishCompleter});
159+
FakeResidentRunner({this.onRestart, this.waitForAppToFinishCompleter});
160160

161+
final OperationResult Function(bool fullRestart)? onRestart;
161162
final Completer<int>? waitForAppToFinishCompleter;
162163
int restartCount = 0;
163164
int concurrentRestarts = 0;
@@ -196,7 +197,7 @@ class FakeResidentRunner extends Fake implements ResidentRunner {
196197
await currentRestartCompleter!.future;
197198
}
198199
concurrentRestarts--;
199-
return OperationResult.ok;
200+
return onRestart?.call(fullRestart) ?? OperationResult.ok;
200201
}
201202

202203
@override
@@ -1134,7 +1135,19 @@ List<_i1.WidgetPreview> previews() => [
11341135
'serializes, coalesces, and gates reloads across previewer lifecycle',
11351136
() async {
11361137
final Directory rootProject = await createRootProject();
1138+
var rejectNextHotReload = false;
11371139
final fakeResidentRunner = FakeResidentRunner(
1140+
onRestart: (bool fullRestart) {
1141+
if (!fullRestart && rejectNextHotReload) {
1142+
rejectNextHotReload = false;
1143+
return OperationResult(
1144+
1,
1145+
'Failed to recompile application.',
1146+
updateFSReport: UpdateFSReport(hotReloadRejected: true),
1147+
);
1148+
}
1149+
return OperationResult.ok;
1150+
},
11381151
waitForAppToFinishCompleter: Completer<int>(),
11391152
);
11401153

@@ -1238,13 +1251,35 @@ List<_i1.WidgetPreview> previews() => [
12381251
expect(fakeResidentRunner.maxConcurrentRestarts, 1);
12391252
expect(fakeResidentRunner.fullRestartRequests, <bool>[false, false, false, false, true]);
12401253

1241-
// 4. Ignore reload requests after the previewer has finished.
1254+
// 4. A rejected hot reload falls back to a hot restart under the mutex,
1255+
// before any reload queued while the rejected reload was in flight.
1256+
rejectNextHotReload = true;
1257+
final rejectedReloadCompleter = Completer<OperationResult>();
1258+
fakeResidentRunner.currentRestartCompleter = rejectedReloadCompleter;
1259+
1260+
triggerChange();
1261+
await pumpEventQueue();
1262+
triggerChange();
1263+
1264+
fakeResidentRunner.currentRestartCompleter = null;
1265+
rejectedReloadCompleter.complete(OperationResult.ok);
1266+
await pumpEventQueue();
1267+
1268+
expect(fakeResidentRunner.restartCount, 8);
1269+
expect(fakeResidentRunner.maxConcurrentRestarts, 1);
1270+
expect(fakeResidentRunner.fullRestartRequests.skip(5), <bool>[false, true, false]);
1271+
expect(
1272+
asLogger<BufferLogger>(logger).statusText,
1273+
contains(WidgetPreviewStartCommand.kHotReloadRejectedMessage),
1274+
);
1275+
1276+
// 5. Ignore reload requests after the previewer has finished.
12421277
fakeResidentRunner.waitForAppToFinishCompleter!.complete(0);
12431278
await runFuture;
12441279

12451280
triggerChange();
12461281
await pumpEventQueue();
1247-
expect(fakeResidentRunner.restartCount, 5);
1282+
expect(fakeResidentRunner.restartCount, 8);
12481283
},
12491284
overrides: <Type, Generator>{
12501285
Analytics: () => fakeAnalytics,
@@ -1261,5 +1296,87 @@ List<_i1.WidgetPreview> previews() => [
12611296
),
12621297
},
12631298
);
1299+
1300+
WidgetPreviewStartCommand createStartCommand(FakeResidentRunner runner) {
1301+
final command = WidgetPreviewCommand(
1302+
toolContext: FakeToolContext(
1303+
fs: fs,
1304+
logger: logger,
1305+
processManager: loggingProcessManager,
1306+
platform: platform,
1307+
artifacts: Artifacts.test(),
1308+
),
1309+
dtdServicesOverride: fakeDtdServices,
1310+
);
1311+
return (command.subcommands['start']! as WidgetPreviewStartCommand)
1312+
..widgetPreviewApp = runner;
1313+
}
1314+
1315+
testWithoutContext('triggers hot restart if hot reload is rejected', () async {
1316+
final fakeResidentRunner = FakeResidentRunner(
1317+
onRestart: (bool fullRestart) {
1318+
if (!fullRestart) {
1319+
return OperationResult(
1320+
1,
1321+
'Failed to recompile application.',
1322+
updateFSReport: UpdateFSReport(hotReloadRejected: true),
1323+
);
1324+
}
1325+
return OperationResult.ok;
1326+
},
1327+
);
1328+
final WidgetPreviewStartCommand startCommand = createStartCommand(fakeResidentRunner);
1329+
1330+
final OperationResult? result = await startCommand.handleReload();
1331+
1332+
final BufferLogger bufferLogger = asLogger<BufferLogger>(logger);
1333+
expect(fakeResidentRunner.fullRestartRequests, <bool>[false, true]);
1334+
expect(result?.isOk, isTrue);
1335+
expect(
1336+
bufferLogger.statusText,
1337+
contains(WidgetPreviewStartCommand.kHotReloadRejectedMessage),
1338+
);
1339+
});
1340+
1341+
testWithoutContext(
1342+
'does not trigger hot restart if hot reload fails for other reasons',
1343+
() async {
1344+
final fakeResidentRunner = FakeResidentRunner(
1345+
onRestart: (bool fullRestart) {
1346+
return OperationResult(
1347+
1,
1348+
'Failed to recompile application.',
1349+
updateFSReport: UpdateFSReport(),
1350+
);
1351+
},
1352+
);
1353+
final WidgetPreviewStartCommand startCommand = createStartCommand(fakeResidentRunner);
1354+
1355+
final OperationResult? result = await startCommand.handleReload();
1356+
1357+
final BufferLogger bufferLogger = asLogger<BufferLogger>(logger);
1358+
expect(fakeResidentRunner.fullRestartRequests, <bool>[false]);
1359+
expect(result?.isOk, isFalse);
1360+
expect(
1361+
bufferLogger.statusText,
1362+
isNot(contains(WidgetPreviewStartCommand.kHotReloadRejectedMessage)),
1363+
);
1364+
},
1365+
);
1366+
1367+
testWithoutContext('does not trigger hot restart if hot reload succeeds', () async {
1368+
final fakeResidentRunner = FakeResidentRunner();
1369+
final WidgetPreviewStartCommand startCommand = createStartCommand(fakeResidentRunner);
1370+
1371+
final OperationResult? result = await startCommand.handleReload();
1372+
1373+
final BufferLogger bufferLogger = asLogger<BufferLogger>(logger);
1374+
expect(fakeResidentRunner.fullRestartRequests, <bool>[false]);
1375+
expect(result?.isOk, isTrue);
1376+
expect(
1377+
bufferLogger.statusText,
1378+
isNot(contains(WidgetPreviewStartCommand.kHotReloadRejectedMessage)),
1379+
);
1380+
});
12641381
});
12651382
}

‎packages/flutter_tools/test/general.shard/resident_web_runner_test.dart‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1138,6 +1138,7 @@ name: my_app
11381138
final OperationResult result = await residentWebRunner.restart();
11391139

11401140
expect(result.code, 1);
1141+
expect(result.updateFSReport?.hotReloadRejected, isTrue);
11411142
expect(webDevFS.mainUri.toString(), contains('entrypoint.dart'));
11421143

11431144
expect(

0 commit comments

Comments
 (0)