fake_api [nfc]: Clarify prepared exception is at HTTP layer

And leave a couple of TODO comments in the one test file that was
accidentally preparing exceptions here that won't turn out in the
intended way.  The next commit will provide a clean way for these
tests to do what they intend instead.

Author: gnprice

test/api/core_test.dart

@@ -504,7 +504,7 @@ Future<T> tryRequest<T extends Object?>({
   fromJson ??= (((Map<String, dynamic> x) => x) as T Function(Map<String, dynamic>));
   return FakeApiConnection.with_((connection) {
     connection.prepare(
-      exception: exception, httpStatus: httpStatus, json: json, body: body);
+      httpException: exception, httpStatus: httpStatus, json: json, body: body);
     return connection.get(kExampleRouteName, fromJson!, 'example/route', {});
   });
 }

test/api/fake_api.dart

@@ -209,28 +209,31 @@ class FakeApiConnection extends ApiConnection {
 
   List<http.BaseRequest> takeRequests() => client.takeRequests();
 
-  /// Prepare the response for the next request.
+  /// Prepare the HTTP response for the next request.
   ///
-  /// If `exception` is null, the next request will produce an [http.Response]
+  /// If `httpException` is null, the next request will produce an [http.Response]
   /// with the given `httpStatus`, defaulting to 200.  The body of the response
   /// will be `body` if non-null, or `jsonEncode(json)` if `json` is non-null,
   /// or else ''.  The `body` and `json` parameters must not both be non-null.
   ///
-  /// If `exception` is non-null, then `httpStatus`, `body`, and `json` must
-  /// all be null, and the next request will throw the given exception.
+  /// If `httpException` is non-null, then
+  /// `httpStatus`, `body`, and `json` must all be null, and the next request
+  /// will throw the given exception within the HTTP client layer,
+  /// causing the API request to throw a [NetworkException]
+  /// wrapping the given exception.
   ///
   /// In either case, the next request will complete a duration of `delay`
   /// after being started.
   void prepare({
-    Object? exception,
+    Object? httpException,
     int? httpStatus,
     Map<String, dynamic>? json,
     String? body,
     Duration delay = Duration.zero,
   }) {
     assert(isOpen);
     client.prepare(
-      exception: exception,
+      exception: httpException,
       httpStatus: httpStatus, json: json, body: body,
       delay: delay,
     );

test/api/fake_api_test.dart

@@ -25,6 +25,15 @@ void main() {
         ..asString.contains('FakeApiConnection.prepare'));
   });
 
+  test('prepare HTTP exception -> get NetworkException', () async {
+    final connection = FakeApiConnection();
+    final exception = Exception('oops');
+    connection.prepare(httpException: exception);
+    await check(connection.get('aRoute', (json) => json, '/', null))
+      .throws((it) => it.isA<NetworkException>()
+        ..cause.identicalTo(exception));
+  });
+
   test('delay success', () => awaitFakeAsync((async) async {
     final connection = FakeApiConnection();
     connection.prepare(delay: const Duration(seconds: 2),
@@ -44,7 +53,7 @@ void main() {
   test('delay exception', () => awaitFakeAsync((async) async {
     final connection = FakeApiConnection();
     connection.prepare(delay: const Duration(seconds: 2),
-      exception: Exception("oops"));
+      httpException: Exception("oops"));
 
     Object? error;
     unawaited(connection.get('aRoute', (json) => null, '/', null)

test/model/actions_test.dart

@@ -103,7 +103,7 @@ void main() {
       assert(unregisterDelay > TestGlobalStore.removeAccountDuration);
       final exception = eg.apiExceptionUnauthorized(routeName: 'removeEtcEtcToken');
       final newConnection = separateConnection()
-        ..prepare(delay: unregisterDelay, exception: exception);
+        ..prepare(delay: unregisterDelay, httpException: exception); // TODO this isn't an HTTP exception
 
       final future = logOutAccount(testBinding.globalStore, eg.selfAccount.id);
       // Unregister-token request and account removal dispatched together
@@ -165,7 +165,7 @@ void main() {
 
       final exception = eg.apiExceptionUnauthorized(routeName: 'removeEtcEtcToken');
       final newConnection = separateConnection()
-        ..prepare(exception: exception);
+        ..prepare(httpException: exception); // TODO this isn't an HTTP exception
       final future = unregisterToken(testBinding.globalStore, eg.selfAccount.id);
       async.elapse(Duration.zero);
       await future;

test/model/store_test.dart

@@ -473,7 +473,7 @@ void main() {
 
       // Try to load, inducing an error in the request.
       globalStore.useCachedApiConnections = true;
-      connection.prepare(exception: Exception('failed'));
+      connection.prepare(httpException: Exception('failed'));
       final future = UpdateMachine.load(globalStore, eg.selfAccount.id);
       bool complete = false;
       unawaited(future.whenComplete(() => complete = true));
@@ -541,7 +541,7 @@ void main() {
       check(store.debugServerEmojiData).isNull();
 
       // Try to fetch, inducing an error in the request.
-      connection.prepare(exception: Exception('failed'));
+      connection.prepare(httpException: Exception('failed'));
       final future = updateMachine.fetchEmojiData(emojiDataUrl);
       bool complete = false;
       unawaited(future.whenComplete(() => complete = true));
@@ -712,11 +712,11 @@ void main() {
     }
 
     void prepareNetworkExceptionSocketException() {
-      connection.prepare(exception: const SocketException('failed'));
+      connection.prepare(httpException: const SocketException('failed'));
     }
 
     void prepareNetworkException() {
-      connection.prepare(exception: Exception("failed"));
+      connection.prepare(httpException: Exception("failed"));
     }
 
     void prepareServer5xxException() {

test/widgets/action_sheet_test.dart

@@ -545,7 +545,7 @@ void main() {
         await prepare(topic: 'zulip');
         await showFromRecipientHeader(tester, message: message);
         connection.takeRequests();
-        connection.prepare(exception: http.ClientException('Oops'));
+        connection.prepare(httpException: http.ClientException('Oops'));
         await tester.tap(findButtonForLabel('Mark as resolved'));
         await tester.pumpAndSettle();
         checkRequest(message.id, '✔ zulip');
@@ -559,7 +559,7 @@ void main() {
         await prepare(topic: '✔ zulip');
         await showFromRecipientHeader(tester, message: message);
         connection.takeRequests();
-        connection.prepare(exception: http.ClientException('Oops'));
+        connection.prepare(httpException: http.ClientException('Oops'));
         await tester.tap(findButtonForLabel('Mark as unresolved'));
         await tester.pumpAndSettle();
         checkRequest(message.id, 'zulip');
@@ -1016,7 +1016,7 @@ void main() {
           final message = eg.streamMessage(flags: [MessageFlag.read]);
           await setupToMessageActionSheet(tester, message: message, narrow: TopicNarrow.ofMessage(message));
 
-          connection.prepare(exception: http.ClientException('Oops'));
+          connection.prepare(httpException: http.ClientException('Oops'));
           final zulipLocalizations = GlobalLocalizations.zulipLocalizations;
 
           await tester.ensureVisible(find.byIcon(Icons.mark_chat_unread_outlined, skipOffstage: false));

test/widgets/actions_test.dart

@@ -329,7 +329,7 @@ void main() {
 
     testWidgets('catch-all api errors', (tester) async {
       await prepare(tester);
-      connection.prepare(exception: http.ClientException('Oops'));
+      connection.prepare(httpException: http.ClientException('Oops'));
       final didPass = invokeUpdateMessageFlagsStartingFromAnchor();
       await tester.pump(Duration.zero);
       checkErrorDialog(tester,

test/widgets/message_list_test.dart

@@ -694,7 +694,7 @@ void main() {
           narrow: narrow, messages: [message], unreadMsgs: unreadMsgs);
         check(isMarkAsReadButtonVisible(tester)).isTrue();
 
-        connection.prepare(exception: http.ClientException('Oops'));
+        connection.prepare(httpException: http.ClientException('Oops'));
         await tester.tap(find.byType(MarkAsReadWidget));
         await tester.pumpAndSettle();
         checkErrorDialog(tester,