Assertions

/**
 * Assert that a value is truthy
 * @param {any} result - Value to test
 * @param {string} [message] - Optional assertion message
 */
assert.ok(result, message)

/**
 * Assert that a value is falsy
 * @param {any} result - Value to test
 * @param {string} [message] - Optional assertion message
 */
assert.notOk(result, message)

/**
 * Assert that a value is strictly true
 * @param {any} result - Value to test
 * @param {string} [message] - Optional assertion message
 */
assert.true(result, message)

/**
 * Assert that a value is strictly false
 * @param {any} result - Value to test
 * @param {string} [message] - Optional assertion message
 */
assert.false(result, message)

QUnit.test("truth assertions", function(assert) {
  assert.ok(1, "1 is truthy");
  assert.ok("hello", "non-empty string is truthy");
  assert.notOk(0, "0 is falsy");
  assert.notOk("", "empty string is falsy");
  
  assert.true(true, "boolean true");
  assert.false(false, "boolean false");
});

/**
 * Loose equality comparison using ==
 * @param {any} actual - Actual value
 * @param {any} expected - Expected value
 * @param {string} [message] - Optional assertion message
 */
assert.equal(actual, expected, message)

/**
 * Loose inequality comparison using !=
 * @param {any} actual - Actual value
 * @param {any} expected - Expected value
 * @param {string} [message] - Optional assertion message
 */
assert.notEqual(actual, expected, message)

/**
 * Strict equality comparison using ===
 * @param {any} actual - Actual value
 * @param {any} expected - Expected value
 * @param {string} [message] - Optional assertion message
 */
assert.strictEqual(actual, expected, message)

/**
 * Strict inequality comparison using !==
 * @param {any} actual - Actual value
 * @param {any} expected - Expected value
 * @param {string} [message] - Optional assertion message
 */
assert.notStrictEqual(actual, expected, message)

/**
 * Deep equality comparison (recursive)
 * @param {any} actual - Actual value
 * @param {any} expected - Expected value
 * @param {string} [message] - Optional assertion message
 */
assert.deepEqual(actual, expected, message)

/**
 * Deep inequality comparison (recursive)
 * @param {any} actual - Actual value
 * @param {any} expected - Expected value
 * @param {string} [message] - Optional assertion message
 */
assert.notDeepEqual(actual, expected, message)

QUnit.test("equality assertions", function(assert) {
  assert.equal("1", 1, "loose equality allows type coercion");
  assert.notEqual("1", 2, "loose inequality");
  
  assert.strictEqual("hello", "hello", "strings are strictly equal");
  assert.notStrictEqual("1", 1, "different types are not strictly equal");
  
  assert.deepEqual([1, 2, 3], [1, 2, 3], "arrays with same content");
  assert.deepEqual({a: 1, b: 2}, {a: 1, b: 2}, "objects with same properties");
  assert.notDeepEqual([1, 2], [1, 2, 3], "arrays with different content");
});

/**
 * Compare enumerable properties of objects
 * @param {any} actual - Actual object
 * @param {any} expected - Expected object
 * @param {string} [message] - Optional assertion message
 */
assert.propEqual(actual, expected, message)

/**
 * Assert enumerable properties are not equal
 * @param {any} actual - Actual object
 * @param {any} expected - Expected object
 * @param {string} [message] - Optional assertion message
 */
assert.notPropEqual(actual, expected, message)

/**
 * Assert that object contains expected properties (subset)
 * @param {any} actual - Actual object
 * @param {any} expected - Expected subset of properties
 * @param {string} [message] - Optional assertion message
 */
assert.propContains(actual, expected, message)

/**
 * Assert that object does not contain expected properties (subset)
 * @param {any} actual - Actual object
 * @param {any} expected - Properties that should not be present
 * @param {string} [message] - Optional assertion message
 */
assert.notPropContains(actual, expected, message)

QUnit.test("property assertions", function(assert) {
  const user = { name: "Alice", age: 30, email: "alice@example.com" };
  
  assert.propEqual(user, { name: "Alice", age: 30, email: "alice@example.com" });
  assert.propContains(user, { name: "Alice", age: 30 });
  assert.notPropContains(user, { role: "admin" });
});

/**
 * Assert that a function throws an exception
 * @param {Function} block - Function that should throw
 * @param {any} [expected] - Expected exception (optional)
 * @param {string} [message] - Optional assertion message
 */
assert.throws(block, expected, message)

/**
 * Alias for throws()
 * @param {Function} block - Function that should throw
 * @param {any} [expected] - Expected exception (optional)
 * @param {string} [message] - Optional assertion message
 */
assert.raises(block, expected, message)

/**
 * Assert that a promise rejects
 * @param {Promise} promise - Promise that should reject
 * @param {any} [expected] - Expected rejection value (optional)
 * @param {string} [message] - Optional assertion message
 * @returns {Promise<void>}
 */
assert.rejects(promise, expected, message)

QUnit.test("exception assertions", function(assert) {
  assert.throws(() => {
    throw new Error("Something went wrong");
  }, Error, "function throws Error");
  
  assert.throws(() => {
    JSON.parse("invalid json");
  }, "JSON.parse throws on invalid input");
  
  // Testing promise rejection
  assert.rejects(
    fetch("/nonexistent-endpoint"),
    "fetch should reject for 404"
  );
});

/**
 * Assert that values are within specified delta
 * @param {number} actual - Actual numeric value
 * @param {number} expected - Expected numeric value
 * @param {number} delta - Maximum allowed difference
 * @param {string} [message] - Optional assertion message
 */
assert.closeTo(actual, expected, delta, message)

QUnit.test("numeric assertions", function(assert) {
  assert.closeTo(0.1 + 0.2, 0.3, 0.0001, "floating point addition");
  assert.closeTo(Math.PI, 3.14159, 0.00001, "PI approximation");
});

/**
 * Set expected number of assertions for this test
 * @param {number} [count] - Expected assertion count (returns current if omitted)
 * @returns {number|void} Current expected count when called without arguments
 */
assert.expect(count)

/**
 * Create async control for pausing test execution
 * @param {number} [count=1] - Number of async calls expected
 * @returns {Function} Function to call when async operation completes
 */
assert.async(count)

/**
 * Set timeout for current test
 * @param {number} duration - Timeout in milliseconds
 */
assert.timeout(duration)

QUnit.test("async test", function(assert) {
  assert.expect(2);
  const done = assert.async();
  
  setTimeout(() => {
    assert.ok(true, "first assertion");
    assert.ok(true, "second assertion");
    done();
  }, 100);
});

QUnit.test("long running test", function(assert) {
  assert.timeout(5000); // 5 second timeout
  
  const done = assert.async();
  longRunningOperation(() => {
    assert.ok(true, "operation completed");
    done();
  });
});

/**
 * Record a step in test execution
 * @param {string} message - Step description
 */
assert.step(message)

/**
 * Verify that recorded steps match expected sequence
 * @param {string[]} steps - Array of expected step messages
 * @param {string} [message] - Optional assertion message
 */
assert.verifySteps(steps, message)

QUnit.test("step verification", function(assert) {
  function processOrder(order) {
    assert.step("validate order");
    if (order.valid) {
      assert.step("calculate total");
      assert.step("charge payment");
      assert.step("send confirmation");
    }
  }
  
  processOrder({ valid: true, items: [...] });
  
  assert.verifySteps([
    "validate order",
    "calculate total", 
    "charge payment",
    "send confirmation"
  ], "order processing steps executed in correct order");
});

/**
 * Manually push assertion result
 * @param {Object} resultInfo - Assertion result object
 * @param {boolean} resultInfo.result - Whether assertion passed
 * @param {any} [resultInfo.actual] - Actual value
 * @param {any} [resultInfo.expected] - Expected value
 * @param {string} [resultInfo.message] - Assertion message
 * @param {boolean} [resultInfo.negative] - Whether this is a negative assertion
 * @param {string} [resultInfo.source] - Error source information
 */
assert.pushResult(resultInfo)

/**
 * Alias for pushResult (legacy)
 * @param {boolean} result - Test result
 * @param {any} actual - Actual value
 * @param {any} expected - Expected value
 * @param {string} message - Assertion message
 * @param {boolean} [negative] - Whether this is a negative assertion
 */
assert.push(result, actual, expected, message, negative)

QUnit.test("custom assertion", function(assert) {
  function customAssertion(value, message) {
    const result = value > 0 && value < 100;
    assert.pushResult({
      result: result,
      actual: value,
      expected: "number between 0 and 100",
      message: message || "value is in valid range"
    });
  }
  
  customAssertion(50, "50 is in range");
  customAssertion(150, "150 is out of range"); // This will fail
});

/**
 * @typedef {Object} AssertionResult
 * @property {boolean} result - Whether assertion passed
 * @property {any} [actual] - Actual value
 * @property {any} [expected] - Expected value
 * @property {string} [message] - Assertion message
 * @property {string} [source] - Error details if assertion failed
 * @property {boolean} [negative] - Whether this is a negative assertion
 */

/**
 * The assert object contains all assertion methods and is passed
 * as the first parameter to test callbacks.
 * @typedef {Object} Assert
 * @property {Object} test - Current test context
 */