as-test 1.1.10 → 1.3.0

package/assembly/src/expectation.ts

@@ -57,6 +57,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 +109,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 +142,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 +152,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 +168,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 +192,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 +216,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 +240,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 +264,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 +278,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 +292,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 +306,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 +320,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 +334,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 +348,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 +372,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 +386,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 +406,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 +424,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 +468,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 +483,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>()) {
@@ -429,24 +496,25 @@ export class Expectation<T> extends Tests {
         JSON.stringify<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);
@@ -454,38 +522,75 @@ export class Expectation<T> extends Tests {
     const actual = JSON.stringify<T>(this._left);
     const res = snapshotAssert(key, actual);
     this._resolve(res.ok, "toMatchSnapshot", actual, res.expected, message);
+    return this;
   }
 
   /**
-   * Delegates throw assertions to try-as when available.
-   * If try-as is unavailable, this matcher is disabled and warns once.
+   * Invokes the wrapped function inside a try/catch and asserts it threw.
+   * Requires the try-as feature (`--enable try-as`).
+   *
+   *   expect((): void => { throw new Error("boom"); }).toThrow();
+   *
+   * The value passed to `expect()` must be a `() => void` callback — calling
+   * `.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) {
         sendWarning(
-          'toThrow() is disabled because try-as is not installed. Install and import "try-as" to enable it.',
+          "toThrow() requires the try-as feature. Enable with --enable try-as.",
         );
         warnedToThrowDisabled = true;
       }
       this._resolve(true, "toThrow", q("disabled"), q("disabled"), message);
-      return;
+      return this;
+    }
+
+    if (!isFunction<T>()) {
+      this._resolve(
+        false,
+        "toThrow",
+        q("non-function"),
+        q("() => void"),
+        message.length
+          ? message
+          : "toThrow() requires a function: expect((): void => { ... }).toThrow()",
+      );
+      return this;
     }
 
+    // try-as rewrites the throw inside the callback to bump
+    // __ExceptionState.Failures and return early from the arrow. We never
+    // wrap the call in try/catch here because try-as's source linker does not
+    // follow chained method calls (`expect(...).toThrow()`) and so it would
+    // not rewrite a `try` placed in this method body. Compare the failure
+    // counter before/after instead and consume any failure we observed.
+    // @ts-ignore: __ExceptionState is provided by the try-as transform
+    const beforeFailures = __ExceptionState.Failures;
+    // @ts-ignore: guarded by isFunction<T>() above
+    (this._left as () => void)();
     // @ts-ignore
-    const passed = __ExceptionState.Failures > 0;
-    if (passed) {
+    const threw = __ExceptionState.Failures > beforeFailures;
+    if (threw) {
       // @ts-ignore
-      __ExceptionState.Failures--;
+      __ExceptionState.Failures = beforeFailures;
     }
-    this._resolve(passed, "toThrow", q("throws"), q("throws"), message);
+    this._resolve(
+      threw,
+      "toThrow",
+      q(threw ? "threw" : "did not throw"),
+      q("throws"),
+      message,
+    );
+    return this;
   }
 
   /**
    * Tests for equality
    */
-  toBe(equals: T, message: string = ""): void {
+  toBe(equals: T, message: string = ""): Expectation<T> {
     const passed = this._left === equals;
 
     this._resolve(
@@ -495,12 +600,13 @@ export class Expectation<T> extends Tests {
       JSON.stringify<T>(equals),
       message,
     );
+    return this;
   }
 
   /**
    * Tests for deep equality
    */
-  toEqual(equals: T, message: string = ""): void {
+  toEqual(equals: T, message: string = ""): Expectation<T> {
     const passed = valueEquals<T>(this._left, equals, false);
     this._resolve(
       passed,
@@ -509,12 +615,13 @@ export class Expectation<T> extends Tests {
       JSON.stringify<T>(equals),
       message,
     );
+    return this;
   }
 
   /**
    * Tests for strict deep equality
    */
-  toStrictEqual(equals: T, message: string = ""): void {
+  toStrictEqual(equals: T, message: string = ""): Expectation<T> {
     const passed = valueEquals<T>(this._left, equals, true);
     this._resolve(
       passed,
@@ -523,6 +630,7 @@ export class Expectation<T> extends Tests {
       JSON.stringify<T>(equals),
       message,
     );
+    return this;
   }
 }
 

package/assembly/src/mode.ts

@@ -0,0 +1,55 @@
+// The current mode name is patched at build time by as-test's transform
+// (transform/src/index.ts) using the AS_TEST_MODE_NAME env var that
+// build-core.ts injects per-mode build. When unset, defaults to "default".
+export const AS_TEST_MODE_NAME: string = "default";
+
+function modeMatches(matchers: string[], current: string): bool {
+  if (matchers.length == 0) return false;
+  let sawPositive = false;
+  let positiveHit = false;
+  for (let i = 0; i < matchers.length; i++) {
+    const m = matchers[i];
+    if (m.length == 0) continue;
+    if (m.charCodeAt(0) == 33 /* '!' */) {
+      if (m.substring(1) == current) return false;
+    } else {
+      sawPositive = true;
+      if (m == current) positiveHit = true;
+    }
+  }
+  return sawPositive ? positiveHit : true;
+}
+
+/**
+ * Gate a block of suite/test registrations on the current execution mode.
+ *
+ * The current mode is the name under `modes.<name>` in `as-test.config.json`
+ * (or `"default"` when running the base config). Comparisons are by exact
+ * string match.
+ *
+ * Matcher semantics:
+ *  - `["a"]` runs when the current mode equals `"a"`.
+ *  - `["a", "b"]` runs when the current mode is in `{a, b}` (positive OR).
+ *  - `["!a"]` runs when the current mode is NOT `"a"`.
+ *  - `["!a", "!b"]` runs when the current mode is neither `{a, b}` (AND).
+ *  - Mixed `["a", "!b"]` runs when any positive matches AND no negative does.
+ *  - `[]` and empty entries are skipped (no-op).
+ *
+ * @example
+ * ```ts
+ * mode(["simd"], () => {
+ *   describe("vectorised path", () => { ... });
+ * });
+ *
+ * mode(["simd", "swar"], () => {
+ *   describe("fast paths", () => { ... });
+ * });
+ *
+ * mode(["!naive"], () => {
+ *   describe("anything but naive", () => { ... });
+ * });
+ * ```
+ */
+export function mode(matchers: string[], fn: () => void): void {
+  if (modeMatches(matchers, AS_TEST_MODE_NAME)) fn();
+}