ai-tests 2.0.2 → 2.1.3

package/src/assertions.js

@@ -0,0 +1,383 @@
+/**
+ * Assertion utilities powered by Chai
+ *
+ * Exposes expect, should, and assert APIs via RPC.
+ * Uses Chai under the hood for battle-tested assertions.
+ */
+import * as chai from 'chai';
+import { RpcTarget } from 'cloudflare:workers';
+// Initialize chai's should
+chai.should();
+/**
+ * Wrapper around Chai's expect that extends RpcTarget
+ * This allows the assertion chain to work over RPC with promise pipelining
+ */
+export class Assertion extends RpcTarget {
+    // Using 'any' to avoid complex type gymnastics with Chai's chainable types
+    // (Deep, Nested, etc. don't match Chai.Assertion directly)
+    assertion;
+    constructor(value, message) {
+        super();
+        this.assertion = chai.expect(value, message);
+    }
+    // Chainable language chains
+    get to() { return this; }
+    get be() { return this; }
+    get been() { return this; }
+    get is() { return this; }
+    get that() { return this; }
+    get which() { return this; }
+    get and() { return this; }
+    get has() { return this; }
+    get have() { return this; }
+    get with() { return this; }
+    get at() { return this; }
+    get of() { return this; }
+    get same() { return this; }
+    get but() { return this; }
+    get does() { return this; }
+    get still() { return this; }
+    get also() { return this; }
+    // Negation
+    get not() {
+        this.assertion = this.assertion.not;
+        return this;
+    }
+    // Deep flag
+    get deep() {
+        this.assertion = this.assertion.deep;
+        return this;
+    }
+    // Nested flag
+    get nested() {
+        this.assertion = this.assertion.nested;
+        return this;
+    }
+    // Own flag
+    get own() {
+        this.assertion = this.assertion.own;
+        return this;
+    }
+    // Ordered flag
+    get ordered() {
+        this.assertion = this.assertion.ordered;
+        return this;
+    }
+    // Any flag
+    get any() {
+        this.assertion = this.assertion.any;
+        return this;
+    }
+    // All flag
+    get all() {
+        this.assertion = this.assertion.all;
+        return this;
+    }
+    // Length chain
+    get length() {
+        this.assertion = this.assertion.length;
+        return this;
+    }
+    // Type assertions
+    get ok() { this.assertion.ok; return this; }
+    get true() { this.assertion.true; return this; }
+    get false() { this.assertion.false; return this; }
+    get null() { this.assertion.null; return this; }
+    get undefined() { this.assertion.undefined; return this; }
+    get NaN() { this.assertion.NaN; return this; }
+    get exist() { this.assertion.exist; return this; }
+    get empty() { this.assertion.empty; return this; }
+    get arguments() { this.assertion.arguments; return this; }
+    // Value assertions
+    equal(value, message) {
+        this.assertion.equal(value, message);
+        return this;
+    }
+    equals(value, message) {
+        return this.equal(value, message);
+    }
+    eq(value, message) {
+        return this.equal(value, message);
+    }
+    eql(value, message) {
+        this.assertion.eql(value, message);
+        return this;
+    }
+    eqls(value, message) {
+        return this.eql(value, message);
+    }
+    above(value, message) {
+        this.assertion.above(value, message);
+        return this;
+    }
+    gt(value, message) {
+        return this.above(value, message);
+    }
+    greaterThan(value, message) {
+        return this.above(value, message);
+    }
+    least(value, message) {
+        this.assertion.least(value, message);
+        return this;
+    }
+    gte(value, message) {
+        return this.least(value, message);
+    }
+    greaterThanOrEqual(value, message) {
+        return this.least(value, message);
+    }
+    below(value, message) {
+        this.assertion.below(value, message);
+        return this;
+    }
+    lt(value, message) {
+        return this.below(value, message);
+    }
+    lessThan(value, message) {
+        return this.below(value, message);
+    }
+    most(value, message) {
+        this.assertion.most(value, message);
+        return this;
+    }
+    lte(value, message) {
+        return this.most(value, message);
+    }
+    lessThanOrEqual(value, message) {
+        return this.most(value, message);
+    }
+    within(start, finish, message) {
+        this.assertion.within(start, finish, message);
+        return this;
+    }
+    instanceof(constructor, message) {
+        this.assertion.instanceof(constructor, message);
+        return this;
+    }
+    instanceOf(constructor, message) {
+        return this.instanceof(constructor, message);
+    }
+    property(name, value, message) {
+        if (arguments.length > 1) {
+            this.assertion.property(name, value, message);
+        }
+        else {
+            this.assertion.property(name);
+        }
+        return this;
+    }
+    ownProperty(name, message) {
+        this.assertion.ownProperty(name, message);
+        return this;
+    }
+    haveOwnProperty(name, message) {
+        return this.ownProperty(name, message);
+    }
+    ownPropertyDescriptor(name, descriptor, message) {
+        this.assertion.ownPropertyDescriptor(name, descriptor, message);
+        return this;
+    }
+    lengthOf(n, message) {
+        this.assertion.lengthOf(n, message);
+        return this;
+    }
+    match(re, message) {
+        this.assertion.match(re, message);
+        return this;
+    }
+    matches(re, message) {
+        return this.match(re, message);
+    }
+    string(str, message) {
+        this.assertion.string(str, message);
+        return this;
+    }
+    keys(...keys) {
+        this.assertion.keys(...keys);
+        return this;
+    }
+    key(...keys) {
+        return this.keys(...keys);
+    }
+    throw(errorLike, errMsgMatcher, message) {
+        this.assertion.throw(errorLike, errMsgMatcher, message);
+        return this;
+    }
+    throws(errorLike, errMsgMatcher, message) {
+        return this.throw(errorLike, errMsgMatcher, message);
+    }
+    Throw(errorLike, errMsgMatcher, message) {
+        return this.throw(errorLike, errMsgMatcher, message);
+    }
+    respondTo(method, message) {
+        this.assertion.respondTo(method, message);
+        return this;
+    }
+    respondsTo(method, message) {
+        return this.respondTo(method, message);
+    }
+    satisfy(matcher, message) {
+        this.assertion.satisfy(matcher, message);
+        return this;
+    }
+    satisfies(matcher, message) {
+        return this.satisfy(matcher, message);
+    }
+    closeTo(expected, delta, message) {
+        this.assertion.closeTo(expected, delta, message);
+        return this;
+    }
+    approximately(expected, delta, message) {
+        return this.closeTo(expected, delta, message);
+    }
+    members(set, message) {
+        this.assertion.members(set, message);
+        return this;
+    }
+    oneOf(list, message) {
+        this.assertion.oneOf(list, message);
+        return this;
+    }
+    include(value, message) {
+        this.assertion.include(value, message);
+        return this;
+    }
+    includes(value, message) {
+        return this.include(value, message);
+    }
+    contain(value, message) {
+        return this.include(value, message);
+    }
+    contains(value, message) {
+        return this.include(value, message);
+    }
+    a(type, message) {
+        this.assertion.a(type, message);
+        return this;
+    }
+    an(type, message) {
+        return this.a(type, message);
+    }
+    // Vitest-compatible aliases
+    toBe(value) {
+        this.assertion.equal(value);
+        return this;
+    }
+    toEqual(value) {
+        this.assertion.deep.equal(value);
+        return this;
+    }
+    toStrictEqual(value) {
+        this.assertion.deep.equal(value);
+        return this;
+    }
+    toBeTruthy() {
+        this.assertion.ok;
+        return this;
+    }
+    toBeFalsy() {
+        this.assertion.not.ok;
+        return this;
+    }
+    toBeNull() {
+        this.assertion.null;
+        return this;
+    }
+    toBeUndefined() {
+        this.assertion.undefined;
+        return this;
+    }
+    toBeDefined() {
+        this.assertion.not.undefined;
+        return this;
+    }
+    toBeNaN() {
+        this.assertion.NaN;
+        return this;
+    }
+    toContain(value) {
+        this.assertion.include(value);
+        return this;
+    }
+    toHaveLength(length) {
+        this.assertion.lengthOf(length);
+        return this;
+    }
+    toHaveProperty(path, value) {
+        if (arguments.length > 1) {
+            this.assertion.nested.property(path, value);
+        }
+        else {
+            this.assertion.nested.property(path);
+        }
+        return this;
+    }
+    toMatch(pattern) {
+        if (typeof pattern === 'string') {
+            this.assertion.include(pattern);
+        }
+        else {
+            this.assertion.match(pattern);
+        }
+        return this;
+    }
+    toMatchObject(obj) {
+        this.assertion.deep.include(obj);
+        return this;
+    }
+    toThrow(expected) {
+        if (expected) {
+            this.assertion.throw(expected);
+        }
+        else {
+            this.assertion.throw();
+        }
+        return this;
+    }
+    toBeGreaterThan(n) {
+        this.assertion.above(n);
+        return this;
+    }
+    toBeLessThan(n) {
+        this.assertion.below(n);
+        return this;
+    }
+    toBeGreaterThanOrEqual(n) {
+        this.assertion.least(n);
+        return this;
+    }
+    toBeLessThanOrEqual(n) {
+        this.assertion.most(n);
+        return this;
+    }
+    toBeCloseTo(n, digits = 2) {
+        const delta = Math.pow(10, -digits) / 2;
+        this.assertion.closeTo(n, delta);
+        return this;
+    }
+    toBeInstanceOf(cls) {
+        this.assertion.instanceof(cls);
+        return this;
+    }
+    toBeTypeOf(type) {
+        this.assertion.a(type);
+        return this;
+    }
+}
+/**
+ * Assert API - TDD style assertions
+ */
+export const assert = chai.assert;
+/**
+ * Create an expect assertion
+ */
+export function expect(value, message) {
+    return new Assertion(value, message);
+}
+/**
+ * Create a should-style assertion
+ * Since we can't modify Object.prototype over RPC, this takes a value
+ */
+export function should(value) {
+    return new Assertion(value);
+}

package/src/assertions.ts

@@ -11,14 +11,65 @@ import { RpcTarget } from 'cloudflare:workers'
 // Initialize chai's should
 chai.should()
 
+/**
+ * Type for constructor functions that can be used with instanceof assertions.
+ * Matches any class or function that can construct instances.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Constructor<T = unknown> = new (...args: any[]) => T
+
+/**
+ * Type for error-like values that can be used with throw assertions.
+ * Chai's throw() accepts:
+ * - Error constructor (e.g., TypeError, RangeError)
+ * - Error instance (e.g., new Error('message'))
+ * - String for message matching
+ * - RegExp for pattern matching
+ */
+type ThrowableMatch = string | RegExp | Error | Constructor<Error>
+
+/**
+ * Internal type for Chai assertion chain.
+ *
+ * @remarks
+ * **Why we use Chai.Assertion here:**
+ *
+ * Chai's fluent API uses a chainable pattern where each flag (.not, .deep, .nested, etc.)
+ * returns a different TypeScript interface:
+ * - Chai.Assertion: Base type from expect()
+ * - Chai.Deep: Returned after .deep (has subset of properties)
+ * - Chai.Nested, Chai.Own, etc.: Other flag-specific types
+ *
+ * These types form a complex hierarchy where not all methods exist on all types.
+ * For example, Chai.Deep has .equal() but not .ok, while Chai.KeyFilter has
+ * .keys() but not .equal().
+ *
+ * Our wrapper class stores the current assertion state and calls methods on it.
+ * At runtime, all these methods exist because Chai's actual implementation always
+ * has them - the type restrictions are for API guidance, not runtime behavior.
+ *
+ * We use Chai.Assertion (the most complete type) because:
+ * 1. It has all the methods we need to call
+ * 2. The assignment from flag types to Chai.Assertion is unsound in strict TS,
+ *    but at runtime these objects have all the methods we need
+ * 3. We wrap the result in our own Assertion class, so the internal type
+ *    doesn't leak to consumers
+ *
+ * The type assertions in the flag getters (.deep, .nested, etc.) are intentional
+ * and documented. They bridge Chai's complex type hierarchy to our simpler wrapper.
+ */
+type ChaiAssertionChain = Chai.Assertion
+
 /**
  * Wrapper around Chai's expect that extends RpcTarget
  * This allows the assertion chain to work over RPC with promise pipelining
  */
 export class Assertion extends RpcTarget {
-  // Using 'any' to avoid complex type gymnastics with Chai's chainable types
-  // (Deep, Nested, etc. don't match Chai.Assertion directly)
-  private assertion: any
+  /**
+   * Internal Chai assertion chain.
+   * @see ChaiAssertionChain for explanation of the type choice.
+   */
+  private assertion: ChaiAssertionChain
 
   constructor(value: unknown, message?: string) {
     super()
@@ -44,51 +95,79 @@ export class Assertion extends RpcTarget {
   get still() { return this }
   get also() { return this }
 
-  // Negation
+  /**
+   * Negation flag - inverts the assertion.
+   * @remarks Type cast needed: Chai's .not returns Chai.Assertion, which matches our type.
+   */
   get not(): Assertion {
     this.assertion = this.assertion.not
     return this
   }
 
-  // Deep flag
+  /**
+   * Deep flag - enables deep equality comparisons.
+   * @remarks Type cast needed: Chai's .deep returns Chai.Deep, but at runtime
+   * it has all the methods we need. We cast to maintain our wrapper's type.
+   */
   get deep(): Assertion {
-    this.assertion = this.assertion.deep
+    this.assertion = this.assertion.deep as ChaiAssertionChain
     return this
   }
 
-  // Nested flag
+  /**
+   * Nested flag - enables nested property access with dot notation.
+   * @remarks Type cast needed: Chai's .nested returns Chai.Nested, cast to our chain type.
+   */
   get nested(): Assertion {
-    this.assertion = this.assertion.nested
+    this.assertion = this.assertion.nested as ChaiAssertionChain
     return this
   }
 
-  // Own flag
+  /**
+   * Own flag - only checks own properties, not inherited.
+   * @remarks Type cast needed: Chai's .own returns Chai.Own, cast to our chain type.
+   */
   get own(): Assertion {
-    this.assertion = this.assertion.own
+    this.assertion = this.assertion.own as ChaiAssertionChain
     return this
   }
 
-  // Ordered flag
+  /**
+   * Ordered flag - requires members to be in order.
+   * @remarks Type cast needed: Chai's .ordered returns Chai.Ordered, cast to our chain type.
+   */
   get ordered(): Assertion {
-    this.assertion = this.assertion.ordered
+    this.assertion = this.assertion.ordered as ChaiAssertionChain
     return this
   }
 
-  // Any flag
+  /**
+   * Any flag - requires at least one key match.
+   * @remarks Type cast needed: Chai's .any returns Chai.KeyFilter, cast to our chain type.
+   */
   get any(): Assertion {
-    this.assertion = this.assertion.any
+    this.assertion = this.assertion.any as ChaiAssertionChain
     return this
   }
 
-  // All flag
+  /**
+   * All flag - requires all keys to match.
+   * @remarks Type cast needed: Chai's .all returns Chai.KeyFilter, cast to our chain type.
+   */
   get all(): Assertion {
-    this.assertion = this.assertion.all
+    this.assertion = this.assertion.all as ChaiAssertionChain
     return this
   }
 
-  // Length chain
+  /**
+   * Length chain - for asserting on length property.
+   * @remarks Type cast needed: Chai's .length returns Chai.Length which is quite different
+   * from Chai.Assertion (it's also callable). We cast through unknown because Length
+   * doesn't directly overlap with Assertion in TypeScript's structural type system,
+   * but at runtime the object has all methods we need.
+   */
   get length(): Assertion {
-    this.assertion = this.assertion.length
+    this.assertion = this.assertion.length as unknown as ChaiAssertionChain
     return this
   }
 
@@ -183,12 +262,12 @@ export class Assertion extends RpcTarget {
     return this
   }
 
-  instanceof(constructor: unknown, message?: string) {
-    this.assertion.instanceof(constructor as any, message)
+  instanceof(constructor: Constructor, message?: string) {
+    this.assertion.instanceof(constructor, message)
     return this
   }
 
-  instanceOf(constructor: unknown, message?: string) {
+  instanceOf(constructor: Constructor, message?: string) {
     return this.instanceof(constructor, message)
   }
 
@@ -211,7 +290,11 @@ export class Assertion extends RpcTarget {
   }
 
   ownPropertyDescriptor(name: string, descriptor?: PropertyDescriptor, message?: string) {
-    this.assertion.ownPropertyDescriptor(name, descriptor, message)
+    if (descriptor !== undefined) {
+      this.assertion.ownPropertyDescriptor(name, descriptor, message)
+    } else {
+      this.assertion.ownPropertyDescriptor(name, message)
+    }
     return this
   }
 
@@ -243,16 +326,37 @@ export class Assertion extends RpcTarget {
     return this.keys(...keys)
   }
 
-  throw(errorLike?: unknown, errMsgMatcher?: string | RegExp, message?: string) {
-    this.assertion.throw(errorLike as any, errMsgMatcher, message)
+  /**
+   * Asserts that the function throws an error.
+   *
+   * @param errorLike - Error constructor, instance, string, or RegExp to match
+   * @param errMsgMatcher - String or RegExp to match error message (when errorLike is constructor/instance)
+   * @param message - Custom assertion message
+   *
+   * @remarks
+   * Chai's throw() has two overloads that TypeScript can't resolve with our union type.
+   * We use runtime type checking to call the appropriate overload, then use a type
+   * assertion to satisfy TypeScript. This is safe because Chai accepts all these
+   * combinations at runtime.
+   */
+  throw(errorLike?: ThrowableMatch, errMsgMatcher?: string | RegExp, message?: string) {
+    if (errorLike === undefined) {
+      this.assertion.throw()
+    } else if (typeof errorLike === 'string' || errorLike instanceof RegExp) {
+      // First overload: (expected?: string | RegExp, message?: string)
+      this.assertion.throw(errorLike, errMsgMatcher as string | undefined)
+    } else {
+      // Second overload: (constructor: Error | Function, expected?: string | RegExp, message?: string)
+      this.assertion.throw(errorLike as Error | Function, errMsgMatcher, message)
+    }
     return this
   }
 
-  throws(errorLike?: unknown, errMsgMatcher?: string | RegExp, message?: string) {
+  throws(errorLike?: ThrowableMatch, errMsgMatcher?: string | RegExp, message?: string) {
     return this.throw(errorLike, errMsgMatcher, message)
   }
 
-  Throw(errorLike?: unknown, errMsgMatcher?: string | RegExp, message?: string) {
+  Throw(errorLike?: ThrowableMatch, errMsgMatcher?: string | RegExp, message?: string) {
     return this.throw(errorLike, errMsgMatcher, message)
   }
 
@@ -398,11 +502,18 @@ export class Assertion extends RpcTarget {
     return this
   }
 
-  toThrow(expected?: string | RegExp | Error) {
-    if (expected) {
-      this.assertion.throw(expected as any)
-    } else {
+  /**
+   * Vitest-compatible: Asserts that the function throws.
+   * @remarks Uses same runtime type checking as throw() to handle Chai's overloads.
+   */
+  toThrow(expected?: ThrowableMatch) {
+    if (expected === undefined) {
       this.assertion.throw()
+    } else if (typeof expected === 'string' || expected instanceof RegExp) {
+      this.assertion.throw(expected)
+    } else {
+      // Error instance or constructor
+      this.assertion.throw(expected as Error | Function)
     }
     return this
   }
@@ -433,8 +544,8 @@ export class Assertion extends RpcTarget {
     return this
   }
 
-  toBeInstanceOf(cls: unknown) {
-    this.assertion.instanceof(cls as any)
+  toBeInstanceOf(cls: Constructor) {
+    this.assertion.instanceof(cls)
     return this
   }