as-test 1.2.0 → 1.4.0

package/assembly/src/expectation.ts

@@ -1,15 +1,39 @@
 import { visualize } from "../util/helpers";
 import { Tests } from "./tests";
-import { JSON } from "json-as/assembly";
 import { namedSnapshotKey, nextUnnamedSnapshotKey } from "..";
 import {
   sendAssertionFailure,
   sendWarning,
   snapshotAssert,
 } from "../util/wipc";
-import { OBJECT, TOTAL_OVERHEAD } from "~lib/rt/common";
+import { reflectEquals } from "./reflect";
+import { stringify, escape } from "./stringify";
 
 let warnedToThrowDisabled = false;
+let warnedSafeStringifyMissing = false;
+
+function safeStringify<T>(value: T): string {
+  if (
+    isManaged<T>() &&
+    !warnedSafeStringifyMissing &&
+    changetype<usize>(value) != 0 &&
+    !isString<T>() &&
+    !isArray<T>()
+  ) {
+    // @ts-expect-error: optional user-supplied serializer
+    if (!isDefined(value.toJSON)) {
+      sendWarning(
+        "Class " +
+          nameof<T>() +
+          " has no toJSON(): string method. Report values render as a `<" +
+          nameof<T>() +
+          ">` placeholder. Add toJSON() returning a JSON string to serialize.",
+      );
+      warnedSafeStringifyMissing = true;
+    }
+  }
+  return stringify<T>(value);
+}
 
 export class Expectation<T> extends Tests {
   public verdict: string = "none";
@@ -18,13 +42,11 @@ export class Expectation<T> extends Tests {
 
   private _left: T;
 
-  // @ts-ignore
+  // @ts-expect-error: used internally
   private _right: u64 = 0;
 
-  // @ts-ignore
   private _not: boolean = false;
 
-  // @ts-ignore
   private _skip: boolean = false;
 
   private _message: string = "";
@@ -57,6 +79,41 @@ export class Expectation<T> extends Tests {
     return this;
   }
 
+  /**
+   * Asserts that a custom predicate holds. Accepts either a bool or a
+   * `() => bool` lambda. Useful when the verdict isn't expressible via the
+   * built-in matchers — e.g. delegating to a hand-written comparator.
+   *
+   *   expect(x).where(x > 0 && x < 10);
+   *   expect(actual).where((): bool => deepEqual(GLOBAL_A, GLOBAL_B));
+   *
+   * Chains with other matchers as an independent assertion:
+   *
+   *   expect(7).toBe(7).where((): bool => isFresh());
+   *
+   * Note: AssemblyScript does not implement closures, so the lambda cannot
+   * capture local variables from the enclosing scope. Use the bool form when
+   * the predicate references locals, or refer to module-level values from
+   * inside the lambda.
+   */
+  where<W>(predicate: W, message: string = ""): Expectation<T> {
+    let passed: bool;
+    if (isFunction<W>()) {
+      passed = (predicate as () => bool)();
+    } else {
+      // @ts-ignore: W is a bool-compatible primitive in this branch
+      passed = predicate as bool;
+    }
+    this._resolve(
+      passed,
+      "where",
+      q(passed ? "true" : "false"),
+      q("true"),
+      message,
+    );
+    return this;
+  }
+
   private _resolve(
     passed: bool,
     instr: string,
@@ -74,14 +131,26 @@ export class Expectation<T> extends Tests {
       return;
     }
     const isFail = this._not ? passed : !passed;
-    this.verdict = isFail ? "fail" : "ok";
-    this.instr = instr;
-    this.left = left;
-    this.right = right;
     const resolvedMessage = message.length ? message : this._message;
-    this.message = isFail ? resolvedMessage : "";
+    // When matchers chain, later ones must not overwrite an earlier failure's
+    // recorded state — otherwise a passing matcher after a failed one would
+    // flip the suite's verdict back to "ok". Each matcher still fires its own
+    // IPC failure independently below.
+    if (this.verdict != "fail") {
+      this.verdict = isFail ? "fail" : "ok";
+      this.instr = instr;
+      this.left = left;
+      this.right = right;
+      this.message = isFail ? resolvedMessage : "";
+    }
     if (isFail) {
-      sendAssertionFailure(this._snapshotKey, instr, left, right, this.message);
+      sendAssertionFailure(
+        this._snapshotKey,
+        instr,
+        left,
+        right,
+        resolvedMessage,
+      );
       // @ts-ignore
       if (isDefined(AS_TEST_FUZZ)) {
         // @ts-ignore
@@ -95,7 +164,7 @@ export class Expectation<T> extends Tests {
           // @ts-ignore
           __as_test_fuzz_failure_right = right;
           // @ts-ignore
-          __as_test_fuzz_failure_message = this.message;
+          __as_test_fuzz_failure_message = resolvedMessage;
         }
       }
     }
@@ -105,7 +174,7 @@ export class Expectation<T> extends Tests {
   /**
    * Tests if a == null
    */
-  toBeNull(message: string = ""): void {
+  toBeNull(message: string = ""): Expectation<T> {
     const passed =
       (isNullable<T>() && changetype<usize>(this._left) == 0) ||
       (isInteger<T>() && nameof<T>() == "usize" && this._left == 0);
@@ -121,12 +190,13 @@ export class Expectation<T> extends Tests {
       ),
       message,
     );
+    return this;
   }
 
   /**
    * Tests if a > b
    */
-  toBeGreaterThan(value: T, message: string = ""): void {
+  toBeGreaterThan(value: T, message: string = ""): Expectation<T> {
     if (!isInteger<T>() && !isFloat<T>())
       ERROR("toBeGreaterThan() can only be used on number types!");
 
@@ -144,12 +214,13 @@ export class Expectation<T> extends Tests {
       ),
       message,
     );
+    return this;
   }
 
   /**
    * Tests if a >= b
    */
-  toBeGreaterOrEqualTo(value: T, message: string = ""): void {
+  toBeGreaterOrEqualTo(value: T, message: string = ""): Expectation<T> {
     if (!isInteger<T>() && !isFloat<T>())
       ERROR("toBeGreaterOrEqualTo() can only be used on number types!");
 
@@ -167,12 +238,13 @@ export class Expectation<T> extends Tests {
       ),
       message,
     );
+    return this;
   }
 
   /**
    * Tests if a < b
    */
-  toBeLessThan(value: T, message: string = ""): void {
+  toBeLessThan(value: T, message: string = ""): Expectation<T> {
     if (!isInteger<T>() && !isFloat<T>())
       ERROR("toBeLessThan() can only be used on number types!");
 
@@ -190,12 +262,13 @@ export class Expectation<T> extends Tests {
       ),
       message,
     );
+    return this;
   }
 
   /**
    * Tests if a <= b
    */
-  toBeLessThanOrEqualTo(value: T, message: string = ""): void {
+  toBeLessThanOrEqualTo(value: T, message: string = ""): Expectation<T> {
     if (!isInteger<T>() && !isFloat<T>())
       ERROR("toBeLessThanOrEqualTo() can only be used on number types!");
 
@@ -213,12 +286,13 @@ export class Expectation<T> extends Tests {
       ),
       message,
     );
+    return this;
   }
 
   /**
    * Tests if a is string
    */
-  toBeString(message: string = ""): void {
+  toBeString(message: string = ""): Expectation<T> {
     this._resolve(
       isString<T>(),
       "toBeString",
@@ -226,12 +300,13 @@ export class Expectation<T> extends Tests {
       q("string"),
       message,
     );
+    return this;
   }
 
   /**
    * Tests if a is boolean
    */
-  toBeBoolean(message: string = ""): void {
+  toBeBoolean(message: string = ""): Expectation<T> {
     this._resolve(
       isBoolean<T>(),
       "toBeBoolean",
@@ -239,12 +314,13 @@ export class Expectation<T> extends Tests {
       q("boolean"),
       message,
     );
+    return this;
   }
 
   /**
    * Tests if a is array
    */
-  toBeArray(message: string = ""): void {
+  toBeArray(message: string = ""): Expectation<T> {
     this._resolve(
       isArray<T>(),
       "toBeArray",
@@ -252,12 +328,13 @@ export class Expectation<T> extends Tests {
       q("Array<any>"),
       message,
     );
+    return this;
   }
 
   /**
    * Tests if a is number
    */
-  toBeNumber(message: string = ""): void {
+  toBeNumber(message: string = ""): Expectation<T> {
     this._resolve(
       isFloat<T>() || isInteger<T>(),
       "toBeNumber",
@@ -265,12 +342,13 @@ export class Expectation<T> extends Tests {
       q("number"),
       message,
     );
+    return this;
   }
 
   /**
    * Tests if a is integer
    */
-  toBeInteger(message: string = ""): void {
+  toBeInteger(message: string = ""): Expectation<T> {
     this._resolve(
       isInteger<T>(),
       "toBeInteger",
@@ -278,12 +356,13 @@ export class Expectation<T> extends Tests {
       q("integer"),
       message,
     );
+    return this;
   }
 
   /**
    * Tests if a is float
    */
-  toBeFloat(message: string = ""): void {
+  toBeFloat(message: string = ""): Expectation<T> {
     this._resolve(
       isFloat<T>(),
       "toBeFloat",
@@ -291,21 +370,23 @@ export class Expectation<T> extends Tests {
       q("float"),
       message,
     );
+    return this;
   }
 
   /**
    * Tests if a is finite
    */
-  toBeFinite(message: string = ""): void {
+  toBeFinite(message: string = ""): Expectation<T> {
     // @ts-ignore
     const passed = (isFloat<T>() || isInteger<T>()) && isFinite(this._left);
     this._resolve(passed, "toBeFinite", q("Infinity"), q("Finite"), message);
+    return this;
   }
 
   /**
    * Tests if a value is truthy
    */
-  toBeTruthy(message: string = ""): void {
+  toBeTruthy(message: string = ""): Expectation<T> {
     this._resolve(
       isTruthy<T>(this._left),
       "toBeTruthy",
@@ -313,12 +394,13 @@ export class Expectation<T> extends Tests {
       q("truthy"),
       message,
     );
+    return this;
   }
 
   /**
    * Tests if a value is falsy
    */
-  toBeFalsy(message: string = ""): void {
+  toBeFalsy(message: string = ""): Expectation<T> {
     this._resolve(
       !isTruthy<T>(this._left),
       "toBeFalsy",
@@ -326,12 +408,14 @@ export class Expectation<T> extends Tests {
       q("falsy"),
       message,
     );
+    return this;
   }
 
   /**
    * Tests if a floating-point number is close to expected
    */
-  toBeCloseTo(expected: T, precision: i32 = 2, message: string = ""): void {
+  // prettier-ignore
+  toBeCloseTo(expected: T, precision: i32 = 2, message: string = ""): Expectation<T> {
     if (!isFloat<T>() && !isInteger<T>())
       ERROR("toBeCloseTo() can only be used on number types!");
     const factor = Math.pow(10, precision as f64);
@@ -344,12 +428,13 @@ export class Expectation<T> extends Tests {
       visualize<T>(expected),
       message,
     );
+    return this;
   }
 
   /**
    * Tests if a string contains substring
    */
-  toMatch(value: string, message: string = ""): void {
+  toMatch(value: string, message: string = ""): Expectation<T> {
     if (!isString<T>()) ERROR("toMatch() can only be used on string types!");
     // @ts-ignore
     const passed = this._left.indexOf(value) >= 0;
@@ -361,36 +446,39 @@ export class Expectation<T> extends Tests {
       q(value),
       message,
     );
+    return this;
   }
 
   /**
    * Tests if a string starts with the provided prefix.
    */
-  toStartWith(value: string, message: string = ""): void {
+  toStartWith(value: string, message: string = ""): Expectation<T> {
     if (!isString<T>())
       ERROR("toStartWith() can only be used on string types!");
     // @ts-ignore
     const left = this._left as string;
     const passed = left.indexOf(value) == 0;
     this._resolve(passed, "toStartWith", q(left), q(value), message);
+    return this;
   }
 
   /**
    * Tests if a string ends with the provided suffix.
    */
-  toEndWith(value: string, message: string = ""): void {
+  toEndWith(value: string, message: string = ""): Expectation<T> {
     if (!isString<T>()) ERROR("toEndWith() can only be used on string types!");
     // @ts-ignore
     const left = this._left as string;
     const idx = left.lastIndexOf(value);
     const passed = idx >= 0 && idx + value.length == left.length;
     this._resolve(passed, "toEndWith", q(left), q(value), message);
+    return this;
   }
 
   /**
    * Tests if an array has length x
    */
-  toHaveLength(value: i32, message: string = ""): void {
+  toHaveLength(value: i32, message: string = ""): Expectation<T> {
     // @ts-ignore
     const leftLen = this._left.length as i32;
     // @ts-ignore
@@ -402,13 +490,14 @@ export class Expectation<T> extends Tests {
       value.toString(),
       message,
     );
+    return this;
   }
 
   /**
    * Tests if an array or string contains a value
    */
   // @ts-ignore
-  toContain(value: valueof<T>, message: string = ""): void {
+  toContain(value: valueof<T>, message: string = ""): Expectation<T> {
     if (isString<T>()) {
       // @ts-ignore
       const left = this._left as string;
@@ -416,7 +505,7 @@ export class Expectation<T> extends Tests {
       const needle = value as string;
       const passed = left.indexOf(needle) >= 0;
       this._resolve(passed, "toContain", q(left), q(needle), message);
-      return;
+      return this;
     }
 
     if (isArray<T>()) {
@@ -425,35 +514,37 @@ export class Expectation<T> extends Tests {
       this._resolve(
         passed,
         "toContain",
-        JSON.stringify<T>(this._left),
-        JSON.stringify<valueof<T>>(value),
+        safeStringify<T>(this._left),
+        safeStringify<valueof<T>>(value),
         message,
       );
-      return;
+      return this;
     }
 
     ERROR("toContain() can only be used on string and array types!");
+    return this;
   }
 
   /**
    * Alias for toContain().
    */
   // @ts-ignore
-  toContains(value: valueof<T>, message: string = ""): void {
-    this.toContain(value, message);
+  toContains(value: valueof<T>, message: string = ""): Expectation<T> {
+    return this.toContain(value, message);
   }
 
   /**
    * Tests if serialized value matches stored snapshot.
    */
-  toMatchSnapshot(name: string = "", message: string = ""): void {
+  toMatchSnapshot(name: string = "", message: string = ""): Expectation<T> {
     let key = name.length
       ? namedSnapshotKey(this._snapshotKey, name)
       : nextUnnamedSnapshotKey(this._snapshotKey);
 
-    const actual = JSON.stringify<T>(this._left);
+    const actual = safeStringify<T>(this._left);
     const res = snapshotAssert(key, actual);
     this._resolve(res.ok, "toMatchSnapshot", actual, res.expected, message);
+    return this;
   }
 
   /**
@@ -466,7 +557,7 @@ export class Expectation<T> extends Tests {
    * `.toThrow()` on a non-function value records a failure that explains the
    * usage.
    */
-  toThrow(message: string = ""): void {
+  toThrow(message: string = ""): Expectation<T> {
     // @ts-ignore
     if (!isDefined(AS_TEST_TRY_AS)) {
       if (!warnedToThrowDisabled) {
@@ -476,7 +567,7 @@ export class Expectation<T> extends Tests {
         warnedToThrowDisabled = true;
       }
       this._resolve(true, "toThrow", q("disabled"), q("disabled"), message);
-      return;
+      return this;
     }
 
     if (!isFunction<T>()) {
@@ -489,7 +580,7 @@ export class Expectation<T> extends Tests {
           ? message
           : "toThrow() requires a function: expect((): void => { ... }).toThrow()",
       );
-      return;
+      return this;
     }
 
     // try-as rewrites the throw inside the callback to bump
@@ -515,111 +606,51 @@ export class Expectation<T> extends Tests {
       q("throws"),
       message,
     );
+    return this;
   }
 
   /**
    * Tests for equality
    */
-  toBe(equals: T, message: string = ""): void {
-    const passed = this._left === equals;
-
+  toBe(equals: T, message: string = ""): Expectation<T> {
+    // Deep structural equality for managed values; `===` semantics for
+    // primitives and strings (reflectEquals does the dispatch).
+    // `toEqual` is kept below as a Jest-familiarity alias.
+    const passed = reflectEquals<T>(this._left, equals, [], false);
     this._resolve(
       passed,
       "toBe",
-      JSON.stringify<T>(this._left),
-      JSON.stringify<T>(equals),
+      safeStringify<T>(this._left),
+      safeStringify<T>(equals),
       message,
     );
+    return this;
   }
 
   /**
-   * Tests for deep equality
+   * Alias of `toBe` retained for Jest familiarity.
    */
-  toEqual(equals: T, message: string = ""): void {
-    const passed = valueEquals<T>(this._left, equals, false);
-    this._resolve(
-      passed,
-      "toEqual",
-      JSON.stringify<T>(this._left),
-      JSON.stringify<T>(equals),
-      message,
-    );
+  toEqual(equals: T, message: string = ""): Expectation<T> {
+    return this.toBe(equals, message);
   }
 
   /**
-   * Tests for strict deep equality
+   * Like `toBe` but also requires the runtime type (rtId) of the
+   * operands to match for managed values.
    */
-  toStrictEqual(equals: T, message: string = ""): void {
-    const passed = valueEquals<T>(this._left, equals, true);
+  toStrictEqual(equals: T, message: string = ""): Expectation<T> {
+    const passed = reflectEquals<T>(this._left, equals, [], true);
     this._resolve(
       passed,
       "toStrictEqual",
-      JSON.stringify<T>(this._left),
-      JSON.stringify<T>(equals),
+      safeStringify<T>(this._left),
+      safeStringify<T>(equals),
       message,
     );
+    return this;
   }
 }
 
-function arrayEquals<T>(a: T[], b: T[], strict: bool): boolean {
-  if (a.length != b.length) return false;
-  for (let i = 0; i < a.length; i++) {
-    if (!valueEquals<T>(unchecked(a[i]), unchecked(b[i]), strict)) {
-      return false;
-    }
-  }
-  return true;
-}
-
-function valueEquals<T>(left: T, right: T, strict: bool): bool {
-  if (isBoolean<T>() || isString<T>() || isInteger<T>() || isFloat<T>()) {
-    return left === right;
-  }
-
-  if (isNullable<T>()) {
-    const leftPtr = changetype<usize>(left);
-    const rightPtr = changetype<usize>(right);
-    if (leftPtr == 0 || rightPtr == 0) return leftPtr == rightPtr;
-  }
-
-  if (isArray<T>()) {
-    return arrayEquals<valueof<T>>(
-      changetype<valueof<T>[]>(left),
-      changetype<valueof<T>[]>(right),
-      strict,
-    );
-  }
-
-  if (isManaged<T>()) {
-    return managedEquals<T>(left, right, strict);
-  }
-
-  abort(
-    `Unsupported equality matcher for ${nameof<T>()}. Use toBe() for identity or compare fields explicitly.`,
-  );
-  return false;
-}
-
-export function __as_test_deep_equal<T>(left: T, right: T, strict: bool): bool {
-  return valueEquals<T>(left, right, strict);
-}
-
-function managedEquals<T>(left: T, right: T, strict: bool): bool {
-  const leftPtr = changetype<usize>(left);
-  const rightPtr = changetype<usize>(right);
-  if (leftPtr == rightPtr) return true;
-  if (leftPtr == 0 || rightPtr == 0) return false;
-
-  if (strict) {
-    const leftObject = changetype<OBJECT>(leftPtr - TOTAL_OVERHEAD);
-    const rightObject = changetype<OBJECT>(rightPtr - TOTAL_OVERHEAD);
-    if (leftObject.rtId != rightObject.rtId) return false;
-  }
-
-  // @ts-ignore
-  return left.__as_test_equals(right, strict);
-}
-
 function isTruthy<T>(value: T): bool {
   if (isBoolean<T>()) {
     return value as bool;
@@ -641,5 +672,5 @@ function isTruthy<T>(value: T): bool {
 }
 
 function q(value: string): string {
-  return JSON.stringify<string>(value);
+  return escape(value);
 }