Expectations and Matchers

/**
 * Create an expectation for synchronous testing
 * @param actual - The actual value to test
 * @returns Expectation object with matcher methods
 */
function expect(actual: any): Expectation;

/**
 * Create an expectation for asynchronous testing (promises)
 * @param actual - The promise or async function to test
 * @returns AsyncExpectation object with async matcher methods
 */
function expectAsync(actual: Promise<any> | (() => Promise<any>)): AsyncExpectation;

// Synchronous expectations
expect(5).toBe(5);
expect([1, 2, 3]).toContain(2);
expect('hello world').toMatch(/world/);

// Asynchronous expectations
await expectAsync(fetchData()).toBeResolved();
await expectAsync(failingPromise()).toBeRejectedWith('Error message');

interface Expectation {
  /**
   * Strict equality comparison using ===
   * @param expected - Expected value
   */
  toBe(expected: any): boolean;
  
  /**
   * Negated toBe matcher
   * @param expected - Value that should not match
   */
  not.toBe(expected: any): boolean;
  
  /**
   * Deep equality comparison for objects and arrays
   * @param expected - Expected value or structure
   */
  toEqual(expected: any): boolean;
  
  /**
   * Negated toEqual matcher
   * @param expected - Value that should not equal
   */
  not.toEqual(expected: any): boolean;
}

// Identity comparison
expect(obj1).toBe(obj1); // same reference
expect(5).toBe(5);
expect('hello').not.toBe('world');

// Value comparison
expect({a: 1}).toEqual({a: 1}); // different objects, same structure
expect([1, 2, 3]).toEqual([1, 2, 3]);
expect({a: 1}).not.toEqual({a: 2});

interface Expectation {
  /** Test if value is truthy */
  toBeTruthy(): boolean;
  
  /** Test if value is falsy */
  toBeFalsy(): boolean;
  
  /** Test if value is exactly true */
  toBeTrue(): boolean;
  
  /** Test if value is exactly false */
  toBeFalse(): boolean;
  
  /** Test if value is not undefined */
  toBeDefined(): boolean;
  
  /** Test if value is undefined */
  toBeUndefined(): boolean;
  
  /** Test if value is null */
  toBeNull(): boolean;
}

expect(true).toBeTruthy();
expect(1).toBeTruthy();
expect('hello').toBeTruthy();

expect(false).toBeFalsy();
expect(0).toBeFalsy();
expect('').toBeFalsy();

expect(true).toBeTrue();
expect(false).toBeFalse();

expect(someValue).toBeDefined();
expect(undefined).toBeUndefined();
expect(null).toBeNull();

interface Expectation {
  /**
   * Test floating point approximation
   * @param expected - Expected numeric value
   * @param precision - Optional decimal places for precision (default: 2)
   */
  toBeCloseTo(expected: number, precision?: number): boolean;
  
  /** Test if value is greater than expected */
  toBeGreaterThan(expected: number): boolean;
  
  /** Test if value is greater than or equal to expected */
  toBeGreaterThanOrEqual(expected: number): boolean;
  
  /** Test if value is less than expected */
  toBeLessThan(expected: number): boolean;
  
  /** Test if value is less than or equal to expected */
  toBeLessThanOrEqual(expected: number): boolean;
  
  /** Test if value is NaN */
  toBeNaN(): boolean;
  
  /** Test if value is positive infinity */
  toBePositiveInfinity(): boolean;
  
  /** Test if value is negative infinity */
  toBeNegativeInfinity(): boolean;
}

expect(3.14159).toBeCloseTo(3.14, 2);
expect(0.1 + 0.2).toBeCloseTo(0.3);

expect(10).toBeGreaterThan(5);
expect(10).toBeGreaterThanOrEqual(10);
expect(5).toBeLessThan(10);
expect(5).toBeLessThanOrEqual(5);

expect(NaN).toBeNaN();
expect(Infinity).toBePositiveInfinity();
expect(-Infinity).toBeNegativeInfinity();

interface Expectation {
  /**
   * Test if value is an instance of expected constructor
   * @param expected - Constructor function
   */
  toBeInstanceOf(expected: Function): boolean;
}

expect(new Date()).toBeInstanceOf(Date);
expect([]).toBeInstanceOf(Array);
expect(/regex/).toBeInstanceOf(RegExp);
expect(new Error()).toBeInstanceOf(Error);

class CustomClass {}
const instance = new CustomClass();
expect(instance).toBeInstanceOf(CustomClass);

interface Expectation {
  /**
   * Test if array or string contains expected element/substring
   * @param expected - Element or substring to find
   */
  toContain(expected: any): boolean;
  
  /**
   * Test if object has a size/length property with expected value
   * @param expected - Expected size/length
   */
  toHaveSize(expected: number): boolean;
}

// Array containment
expect([1, 2, 3]).toContain(2);
expect(['apple', 'banana']).toContain('banana');

// String containment
expect('hello world').toContain('world');
expect('jasmine testing').toContain('test');

// Size testing
expect([1, 2, 3]).toHaveSize(3);
expect('hello').toHaveSize(5);
expect(new Set([1, 2, 3])).toHaveSize(3);

interface Expectation {
  /**
   * Test if string matches regular expression or contains substring
   * @param expected - RegExp pattern or string to match
   */
  toMatch(expected: string | RegExp): boolean;
}

expect('hello world').toMatch(/world/);
expect('abc123').toMatch(/\d+/);
expect('user@example.com').toMatch(/\S+@\S+\.\S+/);

// String matching
expect('hello world').toMatch('world');
expect('jasmine').toMatch('mine');

interface Expectation {
  /**
   * Test if function throws any exception
   * @param expected - Optional expected error message or type
   */
  toThrow(expected?: any): boolean;
  
  /**
   * Test if function throws a specific error
   * @param expected - Expected error message, type, or instance
   */
  toThrowError(expected?: string | RegExp | Error | Function): boolean;
  
  /**
   * Test if function throws error matching predicate
   * @param predicate - Function to test the thrown error
   */
  toThrowMatching(predicate: (error: any) => boolean): boolean;
}

// Test that function throws
expect(() => {
  throw new Error('Something went wrong');
}).toThrow();

// Test specific error message
expect(() => {
  throw new Error('Invalid input');
}).toThrowError('Invalid input');

// Test error type
expect(() => {
  throw new TypeError('Wrong type');
}).toThrowError(TypeError);

// Test with predicate
expect(() => {
  throw new Error('Server error: 500');
}).toThrowMatching(error => error.message.includes('500'));

interface Expectation {
  /** Test if spy was called at least once */
  toHaveBeenCalled(): boolean;
  
  /**
   * Test if spy was called specific number of times
   * @param expected - Expected call count
   */
  toHaveBeenCalledTimes(expected: number): boolean;
  
  /**
   * Test if spy was called with specific arguments
   * @param ...args - Expected arguments
   */
  toHaveBeenCalledWith(...args: any[]): boolean;
  
  /**
   * Test if spy was called exactly once with specific arguments
   * @param ...args - Expected arguments
   */
  toHaveBeenCalledOnceWith(...args: any[]): boolean;
  
  /**
   * Test if spy was called before another spy
   * @param otherSpy - The other spy to compare against
   */
  toHaveBeenCalledBefore(otherSpy: Spy): boolean;
  
  /** Test if spy has any interactions (calls or property access) */
  toHaveSpyInteractions(): boolean;
}

const spy = jasmine.createSpy('testSpy');
const obj = { method: jasmine.createSpy('method') };

spy('arg1', 'arg2');
obj.method(123);

expect(spy).toHaveBeenCalled();
expect(spy).toHaveBeenCalledTimes(1);
expect(spy).toHaveBeenCalledWith('arg1', 'arg2');
expect(spy).toHaveBeenCalledOnceWith('arg1', 'arg2');

expect(obj.method).toHaveBeenCalledWith(123);
expect(spy).toHaveBeenCalledBefore(obj.method);

interface Expectation {
  /**
   * Test if DOM element has specific CSS class
   * @param className - CSS class name to check
   */
  toHaveClass(className: string): boolean;
}

const element = document.createElement('div');
element.className = 'active selected';

expect(element).toHaveClass('active');
expect(element).toHaveClass('selected');
expect(element).not.toHaveClass('disabled');

interface Expectation {
  /** Always fails - useful for testing custom matchers */
  nothing(): boolean;
}

interface AsyncExpectation {
  /** Test if promise is in pending state */
  toBePending(): Promise<boolean>;
  
  /** Test if promise resolved (fulfilled) */
  toBeResolved(): Promise<boolean>;
  
  /** Test if promise was rejected */
  toBeRejected(): Promise<boolean>;
  
  /**
   * Test if promise resolved to specific value
   * @param expected - Expected resolved value
   */
  toBeResolvedTo(expected: any): Promise<boolean>;
  
  /**
   * Test if promise was rejected with specific value
   * @param expected - Expected rejection value
   */
  toBeRejectedWith(expected: any): Promise<boolean>;
  
  /**
   * Test if promise was rejected with specific error
   * @param expected - Expected error type, message, or instance
   */
  toBeRejectedWithError(expected?: string | RegExp | Error | Function): Promise<boolean>;
}

// Test promise resolution
await expectAsync(Promise.resolve(42)).toBeResolved();
await expectAsync(Promise.resolve(42)).toBeResolvedTo(42);

// Test promise rejection
await expectAsync(Promise.reject('error')).toBeRejected();
await expectAsync(Promise.reject('error')).toBeRejectedWith('error');

// Test promise errors
await expectAsync(
  Promise.reject(new TypeError('Wrong type'))
).toBeRejectedWithError(TypeError);

// Test pending promises
const pendingPromise = new Promise(() => {}); // never resolves
await expectAsync(pendingPromise).toBePending();

interface Expectation {
  not: Expectation;
  // All matcher methods return boolean
}

interface AsyncExpectation {
  not: AsyncExpectation;
  // All async matcher methods return Promise<boolean>
}

interface ExpectationResult {
  matcherName: string;
  message: string;
  stack: string;
  passed: boolean;
  expected?: any;
  actual?: any;
}