⚡ Testing Async Code: Promises and Callbacks

🎯 Introduction

Welcome to the async testing laboratory of TypeScript! ⚡ If testing synchronous code were like examining a photograph where everything is captured in a single moment, then testing asynchronous code would be like directing a complex movie scene where actions happen over time, actors enter and exit at different moments, and you need to coordinate everything perfectly to capture the story as it unfolds - except in our case, we’re ensuring our async operations work correctly across all timing scenarios!

Testing asynchronous code presents unique challenges: timing issues, race conditions, callback hell, and the need to wait for operations to complete. In TypeScript, we have the additional benefit of type safety for our async operations, but we still need to test that our promises resolve correctly, our callbacks are called with the right parameters, and our error handling works as expected.

By the end of this tutorial, you’ll be a master of async testing in TypeScript, capable of testing everything from simple promise chains to complex async workflows involving multiple services, timeouts, and error conditions. You’ll learn to handle timing issues, mock async dependencies, and create reliable test suites that give you confidence in your async code. Let’s dive into the world of bulletproof async testing! 🌟

📚 Understanding Async Testing Fundamentals

🤔 Why Async Testing Is Different

Async testing requires special handling because operations don’t complete immediately, and we need to wait for results while handling potential errors and timeouts.

// 🌟 Setting up comprehensive async testing environment

// Types for our async testing examples
interface ApiResponse<T> {
  data: T;
  status: number;
  message: string;
  timestamp: Date;
}

interface User {
  id: string;
  name: string;
  email: string;
  isActive: boolean;
  createdAt: Date;
}

interface ValidationError {
  field: string;
  message: string;
  code: string;
}

interface DatabaseConnection {
  connect(): Promise<void>;
  disconnect(): Promise<void>;
  query<T>(sql: string, params?: any[]): Promise<T[]>;
  transaction<T>(callback: (tx: Transaction) => Promise<T>): Promise<T>;
}

interface Transaction {
  query<T>(sql: string, params?: any[]): Promise<T[]>;
  commit(): Promise<void>;
  rollback(): Promise<void>;
}

interface EmailService {
  sendEmail(to: string, subject: string, body: string): Promise<void>;
  validateEmail(email: string): Promise<boolean>;
}

interface CacheService {
  get<T>(key: string): Promise<T | null>;
  set<T>(key: string, value: T, ttl?: number): Promise<void>;
  delete(key: string): Promise<boolean>;
  clear(): Promise<void>;
}

// Service that performs async operations
class UserService {
  constructor(
    private db: DatabaseConnection,
    private emailService: EmailService,
    private cache: CacheService
  ) {}

  // Promise-based async method
  async createUser(userData: Omit<User, 'id' | 'createdAt'>): Promise<User> {
    // Validate email first
    const isValidEmail = await this.emailService.validateEmail(userData.email);
    if (!isValidEmail) {
      throw new Error('Invalid email address');
    }

    // Check if user exists
    const existingUsers = await this.db.query<User>(
      'SELECT * FROM users WHERE email = ?',
      [userData.email]
    );

    if (existingUsers.length > 0) {
      throw new Error('User already exists');
    }

    // Create user
    const user: User = {
      id: this.generateId(),
      ...userData,
      createdAt: new Date()
    };

    await this.db.query(
      'INSERT INTO users (id, name, email, isActive, createdAt) VALUES (?, ?, ?, ?, ?)',
      [user.id, user.name, user.email, user.isActive, user.createdAt]
    );

    // Cache the user
    await this.cache.set(`user:${user.id}`, user, 3600);

    // Send welcome email (don't wait for it)
    this.emailService.sendEmail(
      user.email,
      'Welcome!',
      `Welcome ${user.name}!`
    ).catch(error => {
      console.error('Failed to send welcome email:', error);
    });

    return user;
  }

  // Callback-based async method (legacy style)
  getUserById(id: string, callback: (error: Error | null, user?: User) => void): void {
    // Simulate async operation with setTimeout
    setTimeout(async () => {
      try {
        // Check cache first
        const cachedUser = await this.cache.get<User>(`user:${id}`);
        if (cachedUser) {
          callback(null, cachedUser);
          return;
        }

        // Query database
        const users = await this.db.query<User>(
          'SELECT * FROM users WHERE id = ?',
          [id]
        );

        if (users.length === 0) {
          callback(new Error('User not found'));
          return;
        }

        const user = users[0];
        
        // Cache for next time
        await this.cache.set(`user:${user.id}`, user, 3600);
        
        callback(null, user);
      } catch (error) {
        callback(error as Error);
      }
    }, 100);
  }

  // Promise-based method with timeout
  async getUserWithTimeout(id: string, timeoutMs: number = 5000): Promise<User> {
    return new Promise((resolve, reject) => {
      const timeout = setTimeout(() => {
        reject(new Error('Operation timed out'));
      }, timeoutMs);

      this.getUserById(id, (error, user) => {
        clearTimeout(timeout);
        if (error) {
          reject(error);
        } else if (user) {
          resolve(user);
        } else {
          reject(new Error('Unknown error'));
        }
      });
    });
  }

  // Complex async workflow with multiple steps
  async processUserRegistration(userData: Omit<User, 'id' | 'createdAt'>): Promise<{
    user: User;
    emailSent: boolean;
    cacheUpdated: boolean;
  }> {
    let user: User;
    let emailSent = false;
    let cacheUpdated = false;

    // Use transaction for database operations
    await this.db.transaction(async (tx) => {
      // Create user
      user = {
        id: this.generateId(),
        ...userData,
        createdAt: new Date()
      };

      await tx.query(
        'INSERT INTO users (id, name, email, isActive, createdAt) VALUES (?, ?, ?, ?, ?)',
        [user.id, user.name, user.email, user.isActive, user.createdAt]
      );

      // Log registration
      await tx.query(
        'INSERT INTO user_activity (user_id, action, timestamp) VALUES (?, ?, ?)',
        [user.id, 'registration', new Date()]
      );
    });

    // Parallel operations after transaction
    const [cacheResult, emailResult] = await Promise.allSettled([
      this.cache.set(`user:${user!.id}`, user!, 3600),
      this.emailService.sendEmail(
        user!.email,
        'Welcome!',
        `Welcome ${user!.name}!`
      )
    ]);

    cacheUpdated = cacheResult.status === 'fulfilled';
    emailSent = emailResult.status === 'fulfilled';

    return {
      user: user!,
      emailSent,
      cacheUpdated
    };
  }

  private generateId(): string {
    return Math.random().toString(36).substr(2, 9);
  }
}

// Utility class for handling async operations
class AsyncOperationManager {
  private operations: Map<string, Promise<any>> = new Map();

  // Register an async operation
  registerOperation<T>(key: string, operation: Promise<T>): Promise<T> {
    this.operations.set(key, operation);
    
    // Clean up when done
    operation.finally(() => {
      this.operations.delete(key);
    });

    return operation;
  }

  // Wait for all operations to complete
  async waitForAll(): Promise<void> {
    await Promise.allSettled(Array.from(this.operations.values()));
  }

  // Cancel all pending operations (if they support cancellation)
  cancelAll(): void {
    this.operations.clear();
  }

  // Get status of operations
  getStatus(): {
    pending: number;
    keys: string[];
  } {
    return {
      pending: this.operations.size,
      keys: Array.from(this.operations.keys())
    };
  }
}

// API client for external service calls
class ApiClient {
  constructor(private baseUrl: string) {}

  async get<T>(endpoint: string): Promise<ApiResponse<T>> {
    const response = await fetch(`${this.baseUrl}${endpoint}`);
    const data = await response.json();
    
    return {
      data,
      status: response.status,
      message: response.statusText,
      timestamp: new Date()
    };
  }

  async post<T, R>(endpoint: string, data: T): Promise<ApiResponse<R>> {
    const response = await fetch(`${this.baseUrl}${endpoint}`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(data)
    });
    
    const responseData = await response.json();
    
    return {
      data: responseData,
      status: response.status,
      message: response.statusText,
      timestamp: new Date()
    };
  }

  // Method with retry logic
  async getWithRetry<T>(
    endpoint: string, 
    maxRetries: number = 3,
    delay: number = 1000
  ): Promise<ApiResponse<T>> {
    let lastError: Error;

    for (let attempt = 0; attempt <= maxRetries; attempt++) {
      try {
        return await this.get<T>(endpoint);
      } catch (error) {
        lastError = error as Error;
        
        if (attempt === maxRetries) {
          throw lastError;
        }

        // Wait before retry
        await new Promise(resolve => setTimeout(resolve, delay * (attempt + 1)));
      }
    }

    throw lastError!;
  }
}

🧪 Testing Promise-Based Async Code

✅ Basic Promise Testing

The most straightforward way to test promises is using async/await in your test functions.

// 🌟 Comprehensive promise testing patterns

describe('UserService - Promise Testing', () => {
  let userService: UserService;
  let mockDb: jest.Mocked<DatabaseConnection>;
  let mockEmailService: jest.Mocked<EmailService>;
  let mockCache: jest.Mocked<CacheService>;

  beforeEach(() => {
    // Create mocks
    mockDb = {
      connect: jest.fn(),
      disconnect: jest.fn(),
      query: jest.fn(),
      transaction: jest.fn()
    };

    mockEmailService = {
      sendEmail: jest.fn(),
      validateEmail: jest.fn()
    };

    mockCache = {
      get: jest.fn(),
      set: jest.fn(),
      delete: jest.fn(),
      clear: jest.fn()
    };

    userService = new UserService(mockDb, mockEmailService, mockCache);
  });

  // ✅ Test successful promise resolution
  describe('createUser', () => {
    it('should create user successfully when all validations pass', async () => {
      // Arrange
      const userData = {
        name: 'John Doe',
        email: '[email protected]',
        isActive: true
      };

      mockEmailService.validateEmail.mockResolvedValue(true);
      mockDb.query
        .mockResolvedValueOnce([]) // No existing users
        .mockResolvedValueOnce([]); // Insert successful
      mockCache.set.mockResolvedValue();
      mockEmailService.sendEmail.mockResolvedValue();

      // Act
      const result = await userService.createUser(userData);

      // Assert
      expect(result).toMatchObject({
        name: userData.name,
        email: userData.email,
        isActive: userData.isActive
      });
      expect(result.id).toBeDefined();
      expect(result.createdAt).toBeInstanceOf(Date);

      // Verify all async operations were called
      expect(mockEmailService.validateEmail).toHaveBeenCalledWith(userData.email);
      expect(mockDb.query).toHaveBeenCalledTimes(2);
      expect(mockCache.set).toHaveBeenCalledWith(
        `user:${result.id}`,
        result,
        3600
      );
    });

    // ✅ Test promise rejection with validation error
    it('should reject when email validation fails', async () => {
      // Arrange
      const userData = {
        name: 'John Doe',
        email: 'invalid-email',
        isActive: true
      };

      mockEmailService.validateEmail.mockResolvedValue(false);

      // Act & Assert
      await expect(userService.createUser(userData))
        .rejects
        .toThrow('Invalid email address');

      // Verify no database operations occurred
      expect(mockDb.query).not.toHaveBeenCalled();
      expect(mockCache.set).not.toHaveBeenCalled();
    });

    // ✅ Test promise rejection with database error
    it('should reject when database operation fails', async () => {
      // Arrange
      const userData = {
        name: 'John Doe',
        email: '[email protected]',
        isActive: true
      };

      mockEmailService.validateEmail.mockResolvedValue(true);
      mockDb.query.mockRejectedValue(new Error('Database connection failed'));

      // Act & Assert
      await expect(userService.createUser(userData))
        .rejects
        .toThrow('Database connection failed');

      // Verify email service was called but cache was not
      expect(mockEmailService.validateEmail).toHaveBeenCalled();
      expect(mockCache.set).not.toHaveBeenCalled();
    });

    // ✅ Test promise rejection with existing user
    it('should reject when user already exists', async () => {
      // Arrange
      const userData = {
        name: 'John Doe',
        email: '[email protected]',
        isActive: true
      };

      const existingUser = {
        id: 'existing-id',
        ...userData,
        createdAt: new Date()
      };

      mockEmailService.validateEmail.mockResolvedValue(true);
      mockDb.query.mockResolvedValue([existingUser]);

      // Act & Assert
      await expect(userService.createUser(userData))
        .rejects
        .toThrow('User already exists');

      // Verify database was queried but no insert occurred
      expect(mockDb.query).toHaveBeenCalledTimes(1);
      expect(mockCache.set).not.toHaveBeenCalled();
    });
  });

  // ✅ Testing complex async workflows
  describe('processUserRegistration', () => {
    it('should handle complex registration workflow', async () => {
      // Arrange
      const userData = {
        name: 'Jane Doe',
        email: '[email protected]',
        isActive: true
      };

      const mockTransaction = {
        query: jest.fn().mockResolvedValue([]),
        commit: jest.fn(),
        rollback: jest.fn()
      };

      mockDb.transaction.mockImplementation(async (callback) => {
        return await callback(mockTransaction);
      });

      mockCache.set.mockResolvedValue();
      mockEmailService.sendEmail.mockResolvedValue();

      // Act
      const result = await userService.processUserRegistration(userData);

      // Assert
      expect(result.user).toMatchObject({
        name: userData.name,
        email: userData.email,
        isActive: userData.isActive
      });
      expect(result.emailSent).toBe(true);
      expect(result.cacheUpdated).toBe(true);

      // Verify transaction operations
      expect(mockTransaction.query).toHaveBeenCalledTimes(2);
      expect(mockCache.set).toHaveBeenCalled();
      expect(mockEmailService.sendEmail).toHaveBeenCalled();
    });

    it('should handle partial failures gracefully', async () => {
      // Arrange
      const userData = {
        name: 'Jane Doe',
        email: '[email protected]',
        isActive: true
      };

      const mockTransaction = {
        query: jest.fn().mockResolvedValue([]),
        commit: jest.fn(),
        rollback: jest.fn()
      };

      mockDb.transaction.mockImplementation(async (callback) => {
        return await callback(mockTransaction);
      });

      // Cache succeeds, email fails
      mockCache.set.mockResolvedValue();
      mockEmailService.sendEmail.mockRejectedValue(new Error('Email service down'));

      // Act
      const result = await userService.processUserRegistration(userData);

      // Assert
      expect(result.user).toBeDefined();
      expect(result.emailSent).toBe(false); // Email failed
      expect(result.cacheUpdated).toBe(true); // Cache succeeded
    });
  });
});

// Advanced promise testing patterns
describe('Advanced Promise Testing', () => {
  // ✅ Testing promise timing and order
  it('should handle promise execution order correctly', async () => {
    const executionOrder: string[] = [];
    
    const promise1 = new Promise<void>(resolve => {
      setTimeout(() => {
        executionOrder.push('promise1');
        resolve();
      }, 100);
    });

    const promise2 = new Promise<void>(resolve => {
      setTimeout(() => {
        executionOrder.push('promise2');
        resolve();
      }, 50);
    });

    const promise3 = new Promise<void>(resolve => {
      setTimeout(() => {
        executionOrder.push('promise3');
        resolve();
      }, 150);
    });

    // Wait for all promises
    await Promise.all([promise1, promise2, promise3]);

    // Verify execution order (shortest timeout first)
    expect(executionOrder).toEqual(['promise2', 'promise1', 'promise3']);
  });

  // ✅ Testing Promise.allSettled behavior
  it('should handle mixed success and failure with allSettled', async () => {
    const promises = [
      Promise.resolve('success1'),
      Promise.reject(new Error('error1')),
      Promise.resolve('success2'),
      Promise.reject(new Error('error2'))
    ];

    const results = await Promise.allSettled(promises);

    expect(results).toHaveLength(4);
    expect(results[0].status).toBe('fulfilled');
    expect(results[1].status).toBe('rejected');
    expect(results[2].status).toBe('fulfilled');
    expect(results[3].status).toBe('rejected');

    // Type-safe access to results
    if (results[0].status === 'fulfilled') {
      expect(results[0].value).toBe('success1');
    }

    if (results[1].status === 'rejected') {
      expect(results[1].reason).toBeInstanceOf(Error);
      expect(results[1].reason.message).toBe('error1');
    }
  });

  // ✅ Testing promise race conditions
  it('should handle promise race correctly', async () => {
    const fastPromise = new Promise<string>(resolve => {
      setTimeout(() => resolve('fast'), 50);
    });

    const slowPromise = new Promise<string>(resolve => {
      setTimeout(() => resolve('slow'), 200);
    });

    const result = await Promise.race([slowPromise, fastPromise]);
    expect(result).toBe('fast');
  });
});

🔄 Testing Callback-Based Async Code

📞 Handling Legacy Callback Patterns

Many legacy APIs use callbacks instead of promises. Here’s how to test them effectively.

// 🌟 Comprehensive callback testing patterns

describe('UserService - Callback Testing', () => {
  let userService: UserService;
  let mockDb: jest.Mocked<DatabaseConnection>;
  let mockEmailService: jest.Mocked<EmailService>;
  let mockCache: jest.Mocked<CacheService>;

  beforeEach(() => {
    mockDb = {
      connect: jest.fn(),
      disconnect: jest.fn(),
      query: jest.fn(),
      transaction: jest.fn()
    };

    mockEmailService = {
      sendEmail: jest.fn(),
      validateEmail: jest.fn()
    };

    mockCache = {
      get: jest.fn(),
      set: jest.fn(),
      delete: jest.fn(),
      clear: jest.fn()
    };

    userService = new UserService(mockDb, mockEmailService, mockCache);
  });

  // ✅ Test successful callback execution
  describe('getUserById (callback)', () => {
    it('should call callback with user when found in cache', (done) => {
      // Arrange
      const userId = 'test-user-id';
      const cachedUser: User = {
        id: userId,
        name: 'John Doe',
        email: '[email protected]',
        isActive: true,
        createdAt: new Date()
      };

      mockCache.get.mockResolvedValue(cachedUser);

      // Act
      userService.getUserById(userId, (error, user) => {
        try {
          // Assert
          expect(error).toBeNull();
          expect(user).toEqual(cachedUser);
          expect(mockCache.get).toHaveBeenCalledWith(`user:${userId}`);
          
          // Don't expect database query since cache hit
          expect(mockDb.query).not.toHaveBeenCalled();
          
          done();
        } catch (err) {
          done(err);
        }
      });
    });

    it('should call callback with user when found in database', (done) => {
      // Arrange
      const userId = 'test-user-id';
      const dbUser: User = {
        id: userId,
        name: 'Jane Doe',
        email: '[email protected]',
        isActive: true,
        createdAt: new Date()
      };

      mockCache.get.mockResolvedValue(null); // Cache miss
      mockDb.query.mockResolvedValue([dbUser]);
      mockCache.set.mockResolvedValue();

      // Act
      userService.getUserById(userId, (error, user) => {
        try {
          // Assert
          expect(error).toBeNull();
          expect(user).toEqual(dbUser);
          expect(mockCache.get).toHaveBeenCalledWith(`user:${userId}`);
          expect(mockDb.query).toHaveBeenCalledWith(
            'SELECT * FROM users WHERE id = ?',
            [userId]
          );
          expect(mockCache.set).toHaveBeenCalledWith(`user:${userId}`, dbUser, 3600);
          
          done();
        } catch (err) {
          done(err);
        }
      });
    });

    it('should call callback with error when user not found', (done) => {
      // Arrange
      const userId = 'nonexistent-user';

      mockCache.get.mockResolvedValue(null);
      mockDb.query.mockResolvedValue([]); // No users found

      // Act
      userService.getUserById(userId, (error, user) => {
        try {
          // Assert
          expect(error).toBeInstanceOf(Error);
          expect(error?.message).toBe('User not found');
          expect(user).toBeUndefined();
          
          done();
        } catch (err) {
          done(err);
        }
      });
    });

    it('should call callback with error when database fails', (done) => {
      // Arrange
      const userId = 'test-user-id';
      const dbError = new Error('Database connection failed');

      mockCache.get.mockResolvedValue(null);
      mockDb.query.mockRejectedValue(dbError);

      // Act
      userService.getUserById(userId, (error, user) => {
        try {
          // Assert
          expect(error).toBe(dbError);
          expect(user).toBeUndefined();
          
          done();
        } catch (err) {
          done(err);
        }
      });
    });
  });

  // ✅ Converting callback tests to promise-based tests
  describe('getUserById (promisified)', () => {
    // Helper function to promisify callback-based method
    const getUserByIdPromise = (id: string): Promise<User> => {
      return new Promise((resolve, reject) => {
        userService.getUserById(id, (error, user) => {
          if (error) {
            reject(error);
          } else if (user) {
            resolve(user);
          } else {
            reject(new Error('Unknown error'));
          }
        });
      });
    };

    it('should resolve with user when found', async () => {
      // Arrange
      const userId = 'test-user-id';
      const user: User = {
        id: userId,
        name: 'John Doe',
        email: '[email protected]',
        isActive: true,
        createdAt: new Date()
      };

      mockCache.get.mockResolvedValue(user);

      // Act & Assert
      await expect(getUserByIdPromise(userId)).resolves.toEqual(user);
    });

    it('should reject when user not found', async () => {
      // Arrange
      const userId = 'nonexistent-user';

      mockCache.get.mockResolvedValue(null);
      mockDb.query.mockResolvedValue([]);

      // Act & Assert
      await expect(getUserByIdPromise(userId))
        .rejects
        .toThrow('User not found');
    });
  });

  // ✅ Testing callback timeouts
  describe('getUserWithTimeout', () => {
    it('should resolve within timeout', async () => {
      // Arrange
      const userId = 'test-user-id';
      const user: User = {
        id: userId,
        name: 'John Doe',
        email: '[email protected]',
        isActive: true,
        createdAt: new Date()
      };

      mockCache.get.mockResolvedValue(user);

      // Act & Assert
      await expect(userService.getUserWithTimeout(userId, 1000))
        .resolves
        .toEqual(user);
    });

    it('should reject when operation times out', async () => {
      // Arrange
      const userId = 'test-user-id';
      
      // Make cache operation take longer than timeout
      mockCache.get.mockImplementation(() => 
        new Promise(resolve => setTimeout(() => resolve(null), 200))
      );
      mockDb.query.mockImplementation(() =>
        new Promise(resolve => setTimeout(() => resolve([]), 200))
      );

      // Act & Assert
      await expect(userService.getUserWithTimeout(userId, 100))
        .rejects
        .toThrow('Operation timed out');
    });
  });
});

// Advanced callback testing patterns
describe('Advanced Callback Testing', () => {
  // ✅ Testing multiple callback invocations
  it('should handle multiple callback calls correctly', (done) => {
    let callCount = 0;
    const expectedCalls = 3;

    const callback = (result: string) => {
      callCount++;
      expect(result).toBe(`result-${callCount}`);
      
      if (callCount === expectedCalls) {
        done();
      }
    };

    // Simulate multiple async operations
    for (let i = 1; i <= expectedCalls; i++) {
      setTimeout(() => {
        callback(`result-${i}`);
      }, i * 10);
    }
  });

  // ✅ Testing callback error handling
  it('should handle callback errors gracefully', (done) => {
    const errors: Error[] = [];
    
    const errorCallback = (error: Error | null, result?: string) => {
      if (error) {
        errors.push(error);
      }
      
      if (errors.length === 2) {
        expect(errors).toHaveLength(2);
        expect(errors[0].message).toBe('First error');
        expect(errors[1].message).toBe('Second error');
        done();
      }
    };

    // Simulate multiple error scenarios
    setTimeout(() => {
      errorCallback(new Error('First error'));
    }, 10);

    setTimeout(() => {
      errorCallback(new Error('Second error'));
    }, 20);
  });

  // ✅ Testing callback with custom matchers
  it('should use custom matchers for callback validation', (done) => {
    const customCallback = (data: { timestamp: Date; value: number }) => {
      try {
        expect(data).toEqual({
          timestamp: expect.any(Date),
          value: expect.any(Number)
        });
        
        expect(data.timestamp.getTime()).toBeCloseTo(Date.now(), -2);
        expect(data.value).toBeGreaterThan(0);
        
        done();
      } catch (error) {
        done(error);
      }
    };

    setTimeout(() => {
      customCallback({
        timestamp: new Date(),
        value: Math.random() * 100
      });
    }, 50);
  });
});

⏰ Testing Timing and Race Conditions

🏃‍♂️ Handling Time-Sensitive Operations

Time-sensitive operations require special testing techniques to ensure reliability and avoid flaky tests.

// 🌟 Comprehensive timing and race condition testing

describe('Timing and Race Condition Testing', () => {
  // ✅ Testing with fake timers
  describe('Timer-based operations', () => {
    beforeEach(() => {
      jest.useFakeTimers();
    });

    afterEach(() => {
      jest.useRealTimers();
    });

    it('should execute delayed operation after specified time', () => {
      // Arrange
      const callback = jest.fn();
      const delay = 1000;

      // Act
      setTimeout(callback, delay);

      // Assert - callback should not be called yet
      expect(callback).not.toHaveBeenCalled();

      // Fast-forward time
      jest.advanceTimersByTime(delay);

      // Assert - callback should now be called
      expect(callback).toHaveBeenCalledTimes(1);
    });

    it('should handle multiple timers correctly', () => {
      // Arrange
      const callbacks = {
        fast: jest.fn(),
        medium: jest.fn(),
        slow: jest.fn()
      };

      // Act - set up multiple timers
      setTimeout(callbacks.fast, 100);
      setTimeout(callbacks.medium, 500);
      setTimeout(callbacks.slow, 1000);

      // Assert - no callbacks called yet
      expect(callbacks.fast).not.toHaveBeenCalled();
      expect(callbacks.medium).not.toHaveBeenCalled();
      expect(callbacks.slow).not.toHaveBeenCalled();

      // Fast-forward to 100ms
      jest.advanceTimersByTime(100);
      expect(callbacks.fast).toHaveBeenCalledTimes(1);
      expect(callbacks.medium).not.toHaveBeenCalled();
      expect(callbacks.slow).not.toHaveBeenCalled();

      // Fast-forward to 500ms total
      jest.advanceTimersByTime(400);
      expect(callbacks.fast).toHaveBeenCalledTimes(1);
      expect(callbacks.medium).toHaveBeenCalledTimes(1);
      expect(callbacks.slow).not.toHaveBeenCalled();

      // Fast-forward to 1000ms total
      jest.advanceTimersByTime(500);
      expect(callbacks.fast).toHaveBeenCalledTimes(1);
      expect(callbacks.medium).toHaveBeenCalledTimes(1);
      expect(callbacks.slow).toHaveBeenCalledTimes(1);
    });

    it('should handle interval operations', () => {
      // Arrange
      const callback = jest.fn();
      const interval = 250;

      // Act
      const intervalId = setInterval(callback, interval);

      // Assert - advance time and check calls
      jest.advanceTimersByTime(interval);
      expect(callback).toHaveBeenCalledTimes(1);

      jest.advanceTimersByTime(interval);
      expect(callback).toHaveBeenCalledTimes(2);

      jest.advanceTimersByTime(interval);
      expect(callback).toHaveBeenCalledTimes(3);

      // Clean up
      clearInterval(intervalId);
    });
  });

  // ✅ Testing debounce and throttle functions
  describe('Debounce and Throttle', () => {
    // Simple debounce implementation for testing
    function debounce<T extends (...args: any[]) => any>(
      func: T,
      wait: number
    ): T {
      let timeout: NodeJS.Timeout;
      
      return ((...args: Parameters<T>) => {
        clearTimeout(timeout);
        timeout = setTimeout(() => func(...args), wait);
      }) as T;
    }

    // Simple throttle implementation for testing
    function throttle<T extends (...args: any[]) => any>(
      func: T,
      wait: number
    ): T {
      let lastTime = 0;
      
      return ((...args: Parameters<T>) => {
        const now = Date.now();
        if (now - lastTime >= wait) {
          lastTime = now;
          return func(...args);
        }
      }) as T;
    }

    beforeEach(() => {
      jest.useFakeTimers();
    });

    afterEach(() => {
      jest.useRealTimers();
    });

    it('should debounce function calls correctly', () => {
      // Arrange
      const originalFunc = jest.fn();
      const debouncedFunc = debounce(originalFunc, 100);

      // Act - call multiple times rapidly
      debouncedFunc('call1');
      debouncedFunc('call2');
      debouncedFunc('call3');

      // Assert - no calls yet
      expect(originalFunc).not.toHaveBeenCalled();

      // Fast-forward time
      jest.advanceTimersByTime(100);

      // Assert - only last call should be executed
      expect(originalFunc).toHaveBeenCalledTimes(1);
      expect(originalFunc).toHaveBeenCalledWith('call3');
    });

    it('should throttle function calls correctly', () => {
      // Arrange
      const originalFunc = jest.fn();
      const throttledFunc = throttle(originalFunc, 100);

      // Mock Date.now
      let currentTime = 0;
      jest.spyOn(Date, 'now').mockImplementation(() => currentTime);

      // Act & Assert
      throttledFunc('call1');
      expect(originalFunc).toHaveBeenCalledTimes(1);
      expect(originalFunc).toHaveBeenCalledWith('call1');

      // Call again immediately - should be ignored
      throttledFunc('call2');
      expect(originalFunc).toHaveBeenCalledTimes(1);

      // Advance time and call again
      currentTime += 100;
      throttledFunc('call3');
      expect(originalFunc).toHaveBeenCalledTimes(2);
      expect(originalFunc).toHaveBeenCalledWith('call3');
    });
  });

  // ✅ Testing race conditions
  describe('Race Conditions', () => {
    it('should handle concurrent async operations correctly', async () => {
      // Arrange
      const results: string[] = [];
      const delays = [100, 50, 150, 75];

      const createAsyncOperation = (id: string, delay: number) => {
        return new Promise<void>(resolve => {
          setTimeout(() => {
            results.push(id);
            resolve();
          }, delay);
        });
      };

      // Act - start all operations concurrently
      const operations = delays.map((delay, index) => 
        createAsyncOperation(`op${index + 1}`, delay)
      );

      await Promise.all(operations);

      // Assert - results should be in order of completion (by delay)
      expect(results).toEqual(['op2', 'op4', 'op1', 'op3']);
    });

    it('should handle resource contention correctly', async () => {
      // Arrange
      let sharedResource = 0;
      const operations: Promise<number>[] = [];

      const incrementResource = async (increment: number, delay: number): Promise<number> => {
        // Simulate async operation
        await new Promise(resolve => setTimeout(resolve, delay));
        
        // Critical section - potential race condition
        const currentValue = sharedResource;
        await new Promise(resolve => setTimeout(resolve, 10)); // Simulate processing time
        sharedResource = currentValue + increment;
        
        return sharedResource;
      };

      // Act - start multiple operations that modify shared resource
      for (let i = 1; i <= 5; i++) {
        operations.push(incrementResource(i, Math.random() * 50));
      }

      const results = await Promise.all(operations);

      // Assert - verify final state
      expect(sharedResource).toBeGreaterThan(0);
      expect(results).toHaveLength(5);
      
      // Each result should reflect the state at the time of completion
      results.forEach(result => {
        expect(result).toBeGreaterThan(0);
      });
    });

    it('should handle async resource cleanup correctly', async () => {
      // Arrange
      const resources: string[] = [];
      const cleanupOrder: string[] = [];

      const createResource = async (id: string): Promise<() => Promise<void>> => {
        resources.push(id);
        
        // Return cleanup function
        return async () => {
          await new Promise(resolve => setTimeout(resolve, Math.random() * 50));
          cleanupOrder.push(id);
          const index = resources.indexOf(id);
          if (index > -1) {
            resources.splice(index, 1);
          }
        };
      };

      // Act - create resources and cleanup functions
      const cleanup1 = await createResource('resource1');
      const cleanup2 = await createResource('resource2');
      const cleanup3 = await createResource('resource3');

      expect(resources).toEqual(['resource1', 'resource2', 'resource3']);

      // Clean up concurrently
      await Promise.all([cleanup1(), cleanup2(), cleanup3()]);

      // Assert - all resources cleaned up
      expect(resources).toEqual([]);
      expect(cleanupOrder).toHaveLength(3);
      expect(cleanupOrder).toEqual(expect.arrayContaining(['resource1', 'resource2', 'resource3']));
    });
  });
});

// Real-world async testing scenarios
describe('Real-World Async Testing', () => {
  let apiClient: ApiClient;

  beforeEach(() => {
    apiClient = new ApiClient('https://api.example.com');
    
    // Mock fetch globally
    global.fetch = jest.fn();
  });

  afterEach(() => {
    jest.resetAllMocks();
  });

  // ✅ Testing API retry logic
  describe('API Retry Logic', () => {
    it('should retry failed requests and eventually succeed', async () => {
      // Arrange
      const mockFetch = global.fetch as jest.MockedFunction<typeof fetch>;
      
      // First two calls fail, third succeeds
      mockFetch
        .mockRejectedValueOnce(new Error('Network error'))
        .mockRejectedValueOnce(new Error('Service unavailable'))
        .mockResolvedValueOnce({
          ok: true,
          status: 200,
          statusText: 'OK',
          json: () => Promise.resolve({ id: 1, name: 'Test User' })
        } as Response);

      // Act
      const result = await apiClient.getWithRetry<{ id: number; name: string }>('/users/1');

      // Assert
      expect(result.status).toBe(200);
      expect(result.data).toEqual({ id: 1, name: 'Test User' });
      expect(mockFetch).toHaveBeenCalledTimes(3);
    });

    it('should fail after maximum retries', async () => {
      // Arrange
      const mockFetch = global.fetch as jest.MockedFunction<typeof fetch>;
      
      // All calls fail
      mockFetch.mockRejectedValue(new Error('Persistent error'));

      // Act & Assert
      await expect(apiClient.getWithRetry('/users/1', 2))
        .rejects
        .toThrow('Persistent error');

      expect(mockFetch).toHaveBeenCalledTimes(3); // Initial + 2 retries
    });
  });

  // ✅ Testing concurrent operations
  describe('Concurrent Operations', () => {
    it('should handle multiple concurrent API calls', async () => {
      // Arrange
      const mockFetch = global.fetch as jest.MockedFunction<typeof fetch>;
      
      const users = [
        { id: 1, name: 'User 1' },
        { id: 2, name: 'User 2' },
        { id: 3, name: 'User 3' }
      ];

      mockFetch.mockImplementation((url) => {
        const userId = url.toString().split('/').pop();
        const user = users.find(u => u.id.toString() === userId);
        
        return Promise.resolve({
          ok: true,
          status: 200,
          statusText: 'OK',
          json: () => Promise.resolve(user)
        } as Response);
      });

      // Act - make concurrent requests
      const requests = users.map(user => 
        apiClient.get<typeof user>(`/users/${user.id}`)
      );

      const results = await Promise.all(requests);

      // Assert
      expect(results).toHaveLength(3);
      results.forEach((result, index) => {
        expect(result.status).toBe(200);
        expect(result.data).toEqual(users[index]);
      });

      expect(mockFetch).toHaveBeenCalledTimes(3);
    });

    it('should handle mixed success and failure in concurrent operations', async () => {
      // Arrange
      const mockFetch = global.fetch as jest.MockedFunction<typeof fetch>;
      
      mockFetch
        .mockResolvedValueOnce({
          ok: true,
          status: 200,
          statusText: 'OK',
          json: () => Promise.resolve({ id: 1, name: 'User 1' })
        } as Response)
        .mockRejectedValueOnce(new Error('Not found'))
        .mockResolvedValueOnce({
          ok: true,
          status: 200,
          statusText: 'OK',
          json: () => Promise.resolve({ id: 3, name: 'User 3' })
        } as Response);

      // Act
      const requests = [
        apiClient.get('/users/1'),
        apiClient.get('/users/2'),
        apiClient.get('/users/3')
      ];

      const results = await Promise.allSettled(requests);

      // Assert
      expect(results).toHaveLength(3);
      expect(results[0].status).toBe('fulfilled');
      expect(results[1].status).toBe('rejected');
      expect(results[2].status).toBe('fulfilled');

      if (results[0].status === 'fulfilled') {
        expect(results[0].value.data).toEqual({ id: 1, name: 'User 1' });
      }

      if (results[1].status === 'rejected') {
        expect(results[1].reason).toBeInstanceOf(Error);
        expect(results[1].reason.message).toBe('Not found');
      }

      if (results[2].status === 'fulfilled') {
        expect(results[2].value.data).toEqual({ id: 3, name: 'User 3' });
      }
    });
  });
});

🎭 Mocking Async Dependencies

🔧 Advanced Async Mocking Patterns

Mocking async dependencies requires careful handling of timing, promises, and side effects.

// 🌟 Comprehensive async mocking patterns

describe('Advanced Async Mocking', () => {
  // ✅ Mocking async functions with different behaviors
  describe('Async Function Mocking', () => {
    interface WeatherService {
      getCurrentWeather(city: string): Promise<{
        temperature: number;
        humidity: number;
        description: string;
      }>;
      getWeatherForecast(city: string, days: number): Promise<Array<{
        date: string;
        temperature: number;
        description: string;
      }>>;
    }

    let mockWeatherService: jest.Mocked<WeatherService>;

    beforeEach(() => {
      mockWeatherService = {
        getCurrentWeather: jest.fn(),
        getWeatherForecast: jest.fn()
      };
    });

    it('should mock successful async operations', async () => {
      // Arrange
      const expectedWeather = {
        temperature: 25,
        humidity: 60,
        description: 'Sunny'
      };

      mockWeatherService.getCurrentWeather.mockResolvedValue(expectedWeather);

      // Act
      const result = await mockWeatherService.getCurrentWeather('London');

      // Assert
      expect(result).toEqual(expectedWeather);
      expect(mockWeatherService.getCurrentWeather).toHaveBeenCalledWith('London');
    });

    it('should mock async operations with delays', async () => {
      // Arrange
      const expectedWeather = {
        temperature: 20,
        humidity: 70,
        description: 'Cloudy'
      };

      mockWeatherService.getCurrentWeather.mockImplementation((city) => {
        return new Promise(resolve => {
          setTimeout(() => {
            resolve(expectedWeather);
          }, 100);
        });
      });

      // Act
      const startTime = Date.now();
      const result = await mockWeatherService.getCurrentWeather('Paris');
      const endTime = Date.now();

      // Assert
      expect(result).toEqual(expectedWeather);
      expect(endTime - startTime).toBeGreaterThanOrEqual(100);
    });

    it('should mock async operations with conditional behavior', async () => {
      // Arrange
      mockWeatherService.getCurrentWeather.mockImplementation(async (city) => {
        if (city === 'InvalidCity') {
          throw new Error('City not found');
        }
        
        if (city === 'London') {
          return {
            temperature: 18,
            humidity: 65,
            description: 'Rainy'
          };
        }
        
        return {
          temperature: 25,
          humidity: 50,
          description: 'Sunny'
        };
      });

      // Act & Assert
      await expect(mockWeatherService.getCurrentWeather('InvalidCity'))
        .rejects
        .toThrow('City not found');

      const londonWeather = await mockWeatherService.getCurrentWeather('London');
      expect(londonWeather.description).toBe('Rainy');

      const defaultWeather = await mockWeatherService.getCurrentWeather('Tokyo');
      expect(defaultWeather.description).toBe('Sunny');
    });

    it('should mock async operations with sequence of responses', async () => {
      // Arrange - different responses for multiple calls
      mockWeatherService.getCurrentWeather
        .mockResolvedValueOnce({
          temperature: 20,
          humidity: 60,
          description: 'Morning clouds'
        })
        .mockResolvedValueOnce({
          temperature: 25,
          humidity: 55,
          description: 'Afternoon sun'
        })
        .mockResolvedValueOnce({
          temperature: 18,
          humidity: 70,
          description: 'Evening rain'
        });

      // Act
      const morning = await mockWeatherService.getCurrentWeather('London');
      const afternoon = await mockWeatherService.getCurrentWeather('London');
      const evening = await mockWeatherService.getCurrentWeather('London');

      // Assert
      expect(morning.description).toBe('Morning clouds');
      expect(afternoon.description).toBe('Afternoon sun');
      expect(evening.description).toBe('Evening rain');
    });
  });

  // ✅ Mocking external API calls
  describe('External API Mocking', () => {
    class ExternalApiService {
      async fetchUserData(userId: string): Promise<{
        id: string;
        name: string;
        email: string;
      }> {
        const response = await fetch(`https://api.example.com/users/${userId}`);
        if (!response.ok) {
          throw new Error(`HTTP ${response.status}: ${response.statusText}`);
        }
        return response.json();
      }

      async createUser(userData: {
        name: string;
        email: string;
      }): Promise<{
        id: string;
        name: string;
        email: string;
        createdAt: string;
      }> {
        const response = await fetch('https://api.example.com/users', {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json'
          },
          body: JSON.stringify(userData)
        });

        if (!response.ok) {
          throw new Error(`HTTP ${response.status}: ${response.statusText}`);
        }
        
        return response.json();
      }
    }

    let apiService: ExternalApiService;
    let mockFetch: jest.MockedFunction<typeof fetch>;

    beforeEach(() => {
      apiService = new ExternalApiService();
      mockFetch = jest.fn();
      global.fetch = mockFetch;
    });

    afterEach(() => {
      jest.resetAllMocks();
    });

    it('should mock successful API response', async () => {
      // Arrange
      const expectedUser = {
        id: 'user-123',
        name: 'John Doe',
        email: '[email protected]'
      };

      mockFetch.mockResolvedValue({
        ok: true,
        status: 200,
        statusText: 'OK',
        json: () => Promise.resolve(expectedUser)
      } as Response);

      // Act
      const result = await apiService.fetchUserData('user-123');

      // Assert
      expect(result).toEqual(expectedUser);
      expect(mockFetch).toHaveBeenCalledWith('https://api.example.com/users/user-123');
    });

    it('should mock API error responses', async () => {
      // Arrange
      mockFetch.mockResolvedValue({
        ok: false,
        status: 404,
        statusText: 'Not Found'
      } as Response);

      // Act & Assert
      await expect(apiService.fetchUserData('nonexistent'))
        .rejects
        .toThrow('HTTP 404: Not Found');

      expect(mockFetch).toHaveBeenCalledWith('https://api.example.com/users/nonexistent');
    });

    it('should mock POST requests with request body validation', async () => {
      // Arrange
      const userData = {
        name: 'Jane Doe',
        email: '[email protected]'
      };

      const expectedResponse = {
        id: 'user-456',
        ...userData,
        createdAt: '2023-01-01T00:00:00Z'
      };

      mockFetch.mockResolvedValue({
        ok: true,
        status: 201,
        statusText: 'Created',
        json: () => Promise.resolve(expectedResponse)
      } as Response);

      // Act
      const result = await apiService.createUser(userData);

      // Assert
      expect(result).toEqual(expectedResponse);
      expect(mockFetch).toHaveBeenCalledWith(
        'https://api.example.com/users',
        {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json'
          },
          body: JSON.stringify(userData)
        }
      );
    });

    it('should mock network errors', async () => {
      // Arrange
      mockFetch.mockRejectedValue(new Error('Network error'));

      // Act & Assert
      await expect(apiService.fetchUserData('user-123'))
        .rejects
        .toThrow('Network error');
    });
  });

  // ✅ Mocking async operations with cleanup
  describe('Async Operations with Cleanup', () => {
    class ResourceManager {
      private resources: Map<string, any> = new Map();

      async acquireResource(id: string): Promise<{
        id: string;
        data: any;
        release: () => Promise<void>;
      }> {
        // Simulate async resource acquisition
        await new Promise(resolve => setTimeout(resolve, 50));

        const resource = {
          id,
          data: `resource-data-${id}`,
          acquired: new Date()
        };

        this.resources.set(id, resource);

        return {
          id,
          data: resource.data,
          release: async () => {
            await new Promise(resolve => setTimeout(resolve, 25));
            this.resources.delete(id);
          }
        };
      }

      getActiveResources(): string[] {
        return Array.from(this.resources.keys());
      }
    }

    let resourceManager: ResourceManager;
    let mockSetTimeout: jest.SpyInstance;
    let mockClearTimeout: jest.SpyInstance;

    beforeEach(() => {
      resourceManager = new ResourceManager();
      
      // Mock timers for controlled testing
      jest.useFakeTimers();
      mockSetTimeout = jest.spyOn(global, 'setTimeout');
      mockClearTimeout = jest.spyOn(global, 'clearTimeout');
    });

    afterEach(() => {
      jest.useRealTimers();
      jest.restoreAllMocks();
    });

    it('should handle resource acquisition and cleanup', async () => {
      // Act
      const resourcePromise = resourceManager.acquireResource('test-resource');
      
      // Fast-forward timers to complete acquisition
      jest.advanceTimersByTime(50);
      
      const resource = await resourcePromise;

      // Assert
      expect(resource.id).toBe('test-resource');
      expect(resource.data).toBe('resource-data-test-resource');
      expect(resourceManager.getActiveResources()).toContain('test-resource');

      // Act - release resource
      const releasePromise = resource.release();
      
      // Fast-forward timers to complete release
      jest.advanceTimersByTime(25);
      
      await releasePromise;

      // Assert
      expect(resourceManager.getActiveResources()).not.toContain('test-resource');
    });

    it('should handle multiple resources concurrently', async () => {
      // Act - acquire multiple resources
      const resource1Promise = resourceManager.acquireResource('resource-1');
      const resource2Promise = resourceManager.acquireResource('resource-2');
      const resource3Promise = resourceManager.acquireResource('resource-3');

      // Fast-forward timers
      jest.advanceTimersByTime(50);

      const [resource1, resource2, resource3] = await Promise.all([
        resource1Promise,
        resource2Promise,
        resource3Promise
      ]);

      // Assert
      expect(resourceManager.getActiveResources()).toEqual(
        expect.arrayContaining(['resource-1', 'resource-2', 'resource-3'])
      );

      // Act - release all resources concurrently
      const releasePromises = [
        resource1.release(),
        resource2.release(),
        resource3.release()
      ];

      jest.advanceTimersByTime(25);

      await Promise.all(releasePromises);

      // Assert
      expect(resourceManager.getActiveResources()).toEqual([]);
    });
  });
});

// Performance testing for async operations
describe('Async Performance Testing', () => {
  it('should measure async operation performance', async () => {
    // Arrange
    const operations = Array.from({ length: 100 }, (_, i) => i);
    
    const asyncOperation = async (value: number): Promise<number> => {
      // Simulate variable processing time
      await new Promise(resolve => setTimeout(resolve, Math.random() * 10));
      return value * 2;
    };

    // Act
    const startTime = Date.now();
    
    // Test sequential processing
    const sequentialResults: number[] = [];
    for (const op of operations) {
      sequentialResults.push(await asyncOperation(op));
    }
    
    const sequentialTime = Date.now() - startTime;

    // Test parallel processing
    const parallelStartTime = Date.now();
    const parallelResults = await Promise.all(
      operations.map(op => asyncOperation(op))
    );
    const parallelTime = Date.now() - parallelStartTime;

    // Assert
    expect(sequentialResults).toEqual(parallelResults);
    expect(parallelTime).toBeLessThan(sequentialTime);
    
    // Performance should be significantly better for parallel execution
    expect(parallelTime).toBeLessThan(sequentialTime * 0.5);
  }, 10000); // Extended timeout for performance test

  it('should handle async operation batching', async () => {
    // Arrange
    const batchSize = 5;
    const totalOperations = 20;
    const operations = Array.from({ length: totalOperations }, (_, i) => i);

    const batchProcessor = async (batch: number[]): Promise<number[]> => {
      // Simulate batch processing
      await new Promise(resolve => setTimeout(resolve, 50));
      return batch.map(n => n * 2);
    };

    // Act
    const batches: number[][] = [];
    for (let i = 0; i < operations.length; i += batchSize) {
      batches.push(operations.slice(i, i + batchSize));
    }

    const results = await Promise.all(
      batches.map(batch => batchProcessor(batch))
    );

    const flatResults = results.flat();

    // Assert
    expect(flatResults).toHaveLength(totalOperations);
    expect(flatResults).toEqual(operations.map(n => n * 2));
    expect(batches).toHaveLength(Math.ceil(totalOperations / batchSize));
  });
});