Test Assertions

/**
 * Assert success (always passes)
 * @param message - Optional assertion message
 */
pass(message?: string): void;

/**
 * Assert failure (always fails)
 * @param message - Optional assertion message
 */
fail(message?: string): void;

/**
 * Assert truthy value
 * @param value - Value to test for truthiness
 * @param message - Optional assertion message (default: "expected truthy value")
 */
ok(value: any, message?: string): void;

/**
 * Assert falsy value
 * @param value - Value to test for falsiness
 * @param message - Optional assertion message (default: "expected falsy value")
 */
absent(value: any, message?: string): void;

test("basic assertions", (t) => {
  t.pass("explicit pass");
  t.fail("explicit fail");
  
  t.ok(true, "boolean true is truthy");
  t.ok(1, "number 1 is truthy");
  t.ok("hello", "non-empty string is truthy");
  
  t.absent(false, "boolean false is falsy");
  t.absent(0, "number 0 is falsy");
  t.absent("", "empty string is falsy");
  t.absent(null, "null is falsy");
  t.absent(undefined, "undefined is falsy");
});

/**
 * Assert strict equality (===)
 * @param actual - Actual value
 * @param expected - Expected value
 * @param message - Optional assertion message (default: "should be equal")
 */
is(actual: any, expected: any, message?: string): void;

/**
 * Assert coercive equality (==)
 * @param actual - Actual value
 * @param expected - Expected value
 * @param message - Optional assertion message
 */
is.coercively(actual: any, expected: any, message?: string): void;

/**
 * Assert strict inequality (!==)
 * @param actual - Actual value
 * @param expected - Expected value
 * @param message - Optional assertion message (default: "should not be equal")
 */
not(actual: any, expected: any, message?: string): void;

/**
 * Assert coercive inequality (!=)
 * @param actual - Actual value
 * @param expected - Expected value
 * @param message - Optional assertion message
 */
not.coercively(actual: any, expected: any, message?: string): void;

test("equality assertions", (t) => {
  // Strict equality
  t.is(42, 42, "numbers are strictly equal");
  t.is("hello", "hello", "strings are strictly equal");
  
  const obj = {};
  t.is(obj, obj, "same object reference");
  
  // Coercive equality
  t.is.coercively(42, "42", "number equals string coercively");
  t.is.coercively(true, 1, "boolean true equals 1 coercively");
  
  // Strict inequality
  t.not(42, 43, "different numbers");
  t.not("hello", "world", "different strings");
  t.not({}, {}, "different object instances");
  
  // Coercive inequality
  t.not.coercively(42, "43", "different values even coercively");
});

/**
 * Assert deep equality (strict mode)
 * @param actual - Actual value
 * @param expected - Expected value
 * @param message - Optional assertion message (default: "should deep equal")
 */
alike(actual: any, expected: any, message?: string): void;

/**
 * Assert deep equality (coercive mode)
 * @param actual - Actual value
 * @param expected - Expected value
 * @param message - Optional assertion message
 */
alike.coercively(actual: any, expected: any, message?: string): void;

/**
 * Assert deep inequality (strict mode)
 * @param actual - Actual value
 * @param expected - Expected value
 * @param message - Optional assertion message (default: "should not deep equal")
 */
unlike(actual: any, expected: any, message?: string): void;

/**
 * Assert deep inequality (coercive mode)
 * @param actual - Actual value
 * @param expected - Expected value
 * @param message - Optional assertion message
 */
unlike.coercively(actual: any, expected: any, message?: string): void;

test("deep comparison assertions", (t) => {
  // Deep equality
  t.alike([1, 2, 3], [1, 2, 3], "arrays are deeply equal");
  t.alike({ a: 1, b: 2 }, { a: 1, b: 2 }, "objects are deeply equal");
  t.alike(
    { users: [{ name: "Alice" }, { name: "Bob" }] },
    { users: [{ name: "Alice" }, { name: "Bob" }] },
    "nested structures are deeply equal"
  );
  
  // Coercive deep equality
  t.alike.coercively(
    { count: 42 },
    { count: "42" },
    "objects with coercive value equality"
  );
  
  // Deep inequality
  t.unlike([1, 2, 3], [1, 2, 4], "arrays with different values");
  t.unlike({ a: 1 }, { a: 1, b: 2 }, "objects with different properties");
  
  // Coercive deep inequality
  t.unlike.coercively(
    { count: 42 },
    { count: "43" },
    "different values even coercively"
  );
});

/**
 * Assert value matches stored snapshot
 * @param actual - Value to compare against snapshot
 * @param message - Optional assertion message (default: "should match snapshot")
 */
snapshot(actual: any, message?: string): void;

test("snapshot assertions", (t) => {
  const data = {
    users: [
      { id: 1, name: "Alice", active: true },
      { id: 2, name: "Bob", active: false }
    ],
    metadata: { version: "1.0", created: "2023-01-01" }
  };
  
  // First run creates snapshot, subsequent runs compare against it
  t.snapshot(data, "user data structure");
  
  // Arrays work too
  t.snapshot([1, 2, 3, 4], "number sequence");
  
  // Typed arrays are converted to Uint8Array
  const buffer = Buffer.from("hello");
  t.snapshot(buffer, "buffer content");
});

test("error details example", (t) => {
  // This will fail and show detailed comparison
  t.is({ a: 1, b: 2 }, { a: 1, b: 3 }, "objects should match");
  
  // Output includes:
  // - Expected vs actual values
  // - Diff highlighting
  // - Stack trace (if source option enabled)
  // - File location and line number
});