fake_api [nfc]: Add support for simulating delayed connections

There are scenarios where we need to simulate the application's
behavior while waiting for a connection to be established.

This commit introduces the ability to do so by adding a `delay`
parameter to the `prepare` method. This enhancement allows us to
test and observe the application's response during connection
delays, improving our ability to handle such situations gracefully.

Author: Khader-1

test/api/fake_api.dart

@@ -8,19 +8,22 @@ import 'package:zulip/model/store.dart';
 import '../example_data.dart' as eg;
 
 sealed class _PreparedResponse {
+  final Duration? delay;
+
+  _PreparedResponse({this.delay});
 }
 
 class _PreparedException extends _PreparedResponse {
   final Object exception;
 
-  _PreparedException({required this.exception});
+  _PreparedException({required this.exception, super.delay});
 }
 
 class _PreparedSuccess extends _PreparedResponse {
   final int httpStatus;
   final List<int> bytes;
 
-  _PreparedSuccess({required this.httpStatus, required this.bytes});
+  _PreparedSuccess({required this.httpStatus, required this.bytes, super.delay});
 }
 
 /// An [http.Client] that accepts and replays canned responses, for testing.
@@ -46,19 +49,22 @@ class FakeHttpClient extends http.BaseClient {
   /// 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 `delay` is non-null, the response will be delayed by that duration.
+  ///
   /// If `exception` is non-null, then `httpStatus`, `body`, and `json` must
   /// all be null, and the next request will throw the given exception.
   void prepare({
     Object? exception,
     int? httpStatus,
     Map<String, dynamic>? json,
     String? body,
+    Duration? delay,
   }) {
     assert(_nextResponse == null,
       'FakeApiConnection.prepare was called while already expecting a request');
     if (exception != null) {
       assert(httpStatus == null && json == null && body == null);
-      _nextResponse = _PreparedException(exception: exception);
+      _nextResponse = _PreparedException(exception: exception, delay: delay);
     } else {
       assert((json == null) || (body == null));
       final String resolvedBody = switch ((body, json)) {
@@ -69,6 +75,7 @@ class FakeHttpClient extends http.BaseClient {
       _nextResponse = _PreparedSuccess(
         httpStatus: httpStatus ?? 200,
         bytes: utf8.encode(resolvedBody),
+        delay: delay,
       );
     }
   }
@@ -90,11 +97,11 @@ class FakeHttpClient extends http.BaseClient {
     _nextResponse = null;
 
     switch (response) {
-      case _PreparedException(:var exception):
-        return Future(() => throw exception);
-      case _PreparedSuccess(:var bytes, :var httpStatus):
+      case _PreparedException(:var exception, :var delay):
+        return Future.delayed(delay ?? Duration.zero, () => throw exception);
+      case _PreparedSuccess(:var bytes, :var httpStatus, :var delay):
         final byteStream = http.ByteStream.fromBytes(bytes);
-        return Future(() => http.StreamedResponse(
+        return Future.delayed(delay ?? Duration.zero, () => http.StreamedResponse(
           byteStream, httpStatus, request: request));
     }
   }
@@ -201,15 +208,18 @@ class FakeApiConnection extends ApiConnection {
   /// 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 `delay` is non-null, the response will be delayed by that duration.
+  ///
   /// If `exception` is non-null, then `httpStatus`, `body`, and `json` must
   /// all be null, and the next request will throw the given exception.
   void prepare({
     Object? exception,
     int? httpStatus,
     Map<String, dynamic>? json,
     String? body,
+    Duration? delay,
   }) {
     client.prepare(
-      exception: exception, httpStatus: httpStatus, json: json, body: body);
+      exception: exception, httpStatus: httpStatus, json: json, body: body, delay: delay);
   }
 }