fake_api [nfc]: Check for confusion in httpException use

Author: gnprice

test/api/fake_api.dart

@@ -241,6 +241,24 @@ class FakeApiConnection extends ApiConnection {
   }) {
     assert(isOpen);
 
+    // The doc on [http.BaseClient.send] goes further than the following
+    // condition, suggesting that any exception thrown there should be an
+    // [http.ClientException].  But from the upstream implementation, in the
+    // actual live app, we already get TlsException and SocketException,
+    // without them getting wrapped in http.ClientException as that specifies.
+    // So naturally our tests need to simulate those too.
+    if (httpException is ApiRequestException) {
+      throw FlutterError.fromParts([
+        ErrorSummary('FakeApiConnection.prepare was passed an ApiRequestException.'),
+        ErrorDescription(
+          'The `httpException` parameter to FakeApiConnection.prepare describes '
+          'an exception for the underlying HTTP request to throw.  '
+          'In the actual app, that will never be a Zulip-specific exception '
+          'like an ApiRequestException.'),
+        ErrorHint('Try using the `apiException` parameter instead.')
+      ]);
+    }
+
     if (apiException != null) {
       assert(httpException == null
         && httpStatus == null && json == null && body == null);

test/api/fake_api_test.dart

@@ -5,6 +5,7 @@ import 'package:test/scaffolding.dart';
 import 'package:zulip/api/exception.dart';
 
 import '../fake_async.dart';
+import '../stdlib_checks.dart';
 import 'exception_checks.dart';
 import 'fake_api.dart';
 
@@ -34,6 +35,15 @@ void main() {
         ..cause.identicalTo(exception));
   });
 
+  test('error message on prepare API exception as "HTTP exception"', () async {
+    final connection = FakeApiConnection();
+    final exception = ZulipApiException(routeName: 'someRoute',
+      httpStatus: 456, code: 'SOME_ERROR',
+      data: {'foo': ['bar']}, message: 'Something failed');
+    check(() => connection.prepare(httpException: exception))
+      .throws<Error>().asString.contains('apiException');
+  });
+
   test('prepare API exception', () async {
     final connection = FakeApiConnection();
     final exception = ZulipApiException(routeName: 'someRoute',

test/stdlib_checks.dart

@@ -25,6 +25,10 @@ extension NullableMapChecks<K, V> on Subject<Map<K, V>?> {
   }
 }
 
+extension ErrorChecks on Subject<Error> {
+  Subject<String> get asString => has((x) => x.toString(), 'toString'); // TODO(checks): what's a good convention for this?
+}
+
 /// Convert [object] to a pure JSON-like value.
 ///
 /// The result is similar to `jsonDecode(jsonEncode(object))`, but without