@gjsify/unit 0.0.3 → 0.1.0

package/README.md

@@ -1,96 +1,73 @@
 # @gjsify/unit
 
-A BDD-style testing framework for Gjs, Deno and Node.js, forked from [gjsunit](https://github.com/philipphoffmann/gjsunit).
+Lightweight testing framework for GJS and Node.js. Provides describe, it, expect with cross-platform support.
 
-## What it is
-unit is a BDD-style testing framework for the gjs Javascript binding for Gnome 4x which can be used to write Gnome 4x applications and extensions. It's syntax is totally stolen from [Jasmine](http://jasmine.github.io/) ;-).
+Part of the [gjsify](https://github.com/gjsify/gjsify) project — Node.js and Web APIs for GJS (GNOME JavaScript).
 
-## How to use it
-
-First you need to install the package together with `@gjsify/cli`:
-
-```bash
-yarn install @gjsify/cli @gjsify/unit -D
-```
-
-After that you can build and run your tests:
+## Installation
 
 ```bash
-gjsify build test-runner.ts --platform gjs --outfile test.gjs.js
-gjs -m test.gjs.js
+npm install @gjsify/unit
+# or
+yarn add @gjsify/unit
 ```
 
-## Writing test suites
-
-In your test directory you can have as many subdirectories and test files as you wish. unit will just run all of them.
-A test suite could look like this:
-
-```js
-// my-module.spec.ts
+## Usage
 
+```typescript
 import { describe, it, expect } from '@gjsify/unit';
-import MyModule from './my-module.js';
 
 export default async () => {
-
-	await describe('MyModule', async () => {
-		await it('should say hello', async () => {
-			var module = new MyModule();
-
-			expect(module.hello()).toEqual('hello');
-			expect(module.hello()).not.toEqual('hi');
-		});
-	});
-
-}
+  await describe('MyModule', async () => {
+    await it('should do something', async () => {
+      expect(42).toBe(42);
+      expect('hello').not.toEqual('world');
+    });
+  });
+};
 ```
 
-```js
-// test-runner.ts
+### Running tests
 
-import { run } from '@gjsify/unit';
-import myTestSuite from './my-module.spec.ts';
+```bash
+# Build and run on GJS
+gjsify build test-runner.ts --platform gjs --outfile test.gjs.js
+gjs -m test.gjs.js
 
-run({myTestSuite});
+# Run on Node.js
+node test-runner.mjs
 ```
 
+### Available matchers
 
-Your test files must expose a function. This is the function you will call in your test runner. In your test suite you can use `describe` and `it` to cluster your test suite. You can then use `expect` to capture the value you want to express expectations on. The available methods for expressing expectations are:
-- `toBe(value)` (checks using ===)
-- `toEqual(value)` (checks using ==)
-- `toMatch(regex)` (checks using String.prototype.match and a regular expression)
-- `toBeDefined()` (checks whether the actual value is defined)
-- `toBeUndefined()` (opposite of the above)
-- `toBeNull()` (checks whether the actual value is null)
-- `toBeTruthy()` (checks whether the actual value is castable to true)
-- `toBeFalsy()` (checks whether the actual value is castable to false)
-- `toContain(needle)` (checks whether an array contains the needle value)
-- `toBeLessThan(value)`
-- `toBeGreaterThan(value)`
-- `toBeCloseTo(value, precision)` (can check float values until a given precision)
-- `to(callback)` (checks the value using the provided callback (which gets passed the actual value as first parameter))
+- `toBe(value)` — strict equality (`===`)
+- `toEqual(value)` — loose equality (`==`)
+- `toMatch(regex)` — regex match
+- `toBeDefined()` / `toBeUndefined()`
+- `toBeNull()`
+- `toBeTruthy()` / `toBeFalsy()`
+- `toContain(needle)` — array contains
+- `toBeLessThan(value)` / `toBeGreaterThan(value)`
+- `toBeCloseTo(value, precision)` — float comparison
+- `toThrow()` — expects function to throw
+- `to(callback)` — custom matcher
 
-There is also a `spy` method with which the call of methods can be checked, this is forked from [mysticatea/spy](https://github.com/mysticatea/spy).
+All matchers support `.not` for negation.
 
-```js
-// spy.spec.ts
+### Spy
 
-import { describe, it, expect, spy } from '@gjsify/unit';
+```typescript
+import { spy } from '@gjsify/unit';
 
-export default async () => {
-    await describe("'spy' function", async () => {
-        await it("should have a calls length of 1 after called one time.", async () => {
-            const f = spy()
-            f()
-
-            expect(f.calls.length).toBe(1)
-        })
-	})
-}
+const f = spy();
+f();
+expect(f.calls.length).toBe(1);
 ```
 
-I recommend looking at the test suite for examples.
+## Credits
 
-Happy testing!
+Forked from [gjsunit](https://github.com/philipphoffmann/gjsunit). Spy functionality forked from [mysticatea/spy](https://github.com/mysticatea/spy).
 
+## License
 
+MIT

package/lib/esm/index.js

@@ -1,16 +1,67 @@
 import "@girs/gjs";
 export * from "./spy.js";
-import nodeAssert from "assert";
+import nodeAssert from "node:assert";
+import { quitMainLoop } from "@gjsify/utils/main-loop";
 const mainloop = globalThis?.imports?.mainloop;
 let countTestsOverall = 0;
 let countTestsFailed = 0;
 let countTestsIgnored = 0;
 let runtime = "";
+let runStartTime = 0;
+const DEFAULT_TIMEOUT_CONFIG = {
+  testTimeout: 5e3,
+  suiteTimeout: 3e4,
+  runTimeout: 12e4
+};
+let timeoutConfig = { ...DEFAULT_TIMEOUT_CONFIG };
+class TimeoutError extends Error {
+  constructor(label, timeoutMs) {
+    super(`Timeout: "${label}" exceeded ${timeoutMs}ms`);
+    this.name = "TimeoutError";
+  }
+}
+async function withTimeout(fn, timeoutMs, label) {
+  if (timeoutMs <= 0) return fn();
+  let timeoutId;
+  const timeoutPromise = new Promise((_, reject) => {
+    timeoutId = setTimeout(() => reject(new TimeoutError(label, timeoutMs)), timeoutMs);
+  });
+  const fnPromise = Promise.resolve(fn());
+  fnPromise.catch(() => {
+  });
+  try {
+    return await Promise.race([fnPromise, timeoutPromise]);
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+const configure = (overrides) => {
+  timeoutConfig = { ...timeoutConfig, ...overrides };
+};
+function applyEnvOverrides() {
+  try {
+    const env = globalThis.process?.env;
+    if (!env) return;
+    const t = parseInt(env.GJSIFY_TEST_TIMEOUT, 10);
+    if (!isNaN(t) && t >= 0) timeoutConfig.testTimeout = t;
+    const s = parseInt(env.GJSIFY_SUITE_TIMEOUT, 10);
+    if (!isNaN(s) && s >= 0) timeoutConfig.suiteTimeout = s;
+    const r = parseInt(env.GJSIFY_RUN_TIMEOUT, 10);
+    if (!isNaN(r) && r >= 0) timeoutConfig.runTimeout = r;
+  } catch (_e) {
+  }
+}
 const RED = "\x1B[31m";
 const GREEN = "\x1B[32m";
 const BLUE = "\x1B[34m";
 const GRAY = "\x1B[90m";
 const RESET = "\x1B[39m";
+const now = () => globalThis.performance?.now?.() ?? Date.now();
+const formatDuration = (ms) => {
+  if (ms >= 1e3) return `${(ms / 1e3).toFixed(2)}s`;
+  if (ms >= 100) return `${Math.round(ms)}ms`;
+  return `${ms.toFixed(1)}ms`;
+};
 const print = globalThis.print || console.log;
 class MatcherFactory {
   constructor(actualValue, positive, negated) {
@@ -25,8 +76,10 @@ class MatcherFactory {
   not;
   triggerResult(success, msg) {
     if (success && !this.positive || !success && this.positive) {
+      const error = new Error(msg);
+      error.__testFailureCounted = true;
       ++countTestsFailed;
-      throw new Error(msg);
+      throw error;
     }
   }
   to(callback) {
@@ -51,14 +104,30 @@ class MatcherFactory {
       Actual: ${this.actualValue} (${typeof this.actualValue})`
     );
   }
+  toStrictEqual(expectedValue) {
+    let success = true;
+    let errorMessage = "";
+    try {
+      nodeAssert.deepStrictEqual(this.actualValue, expectedValue);
+    } catch (e) {
+      success = false;
+      errorMessage = e.message || "";
+    }
+    this.triggerResult(
+      success,
+      `      Expected values to be deeply strictly equal
+      Expected: ${JSON.stringify(expectedValue)}
+      Actual: ${JSON.stringify(this.actualValue)}` + (errorMessage ? `
+      ${errorMessage}` : "")
+    );
+  }
   toEqualArray(expectedValue) {
     let success = Array.isArray(this.actualValue) && Array.isArray(expectedValue) && this.actualValue.length === expectedValue.length;
     for (let i = 0; i < this.actualValue.length; i++) {
       const actualVal = this.actualValue[i];
       const expectedVal = expectedValue[i];
       success = actualVal == expectedVal;
-      if (!success)
-        break;
+      if (!success) break;
     }
     this.triggerResult(
       success,
@@ -67,6 +136,21 @@ class MatcherFactory {
       Actual: ${this.actualValue} (${typeof this.actualValue})`
     );
   }
+  toBeInstanceOf(expectedType) {
+    this.triggerResult(
+      this.actualValue instanceof expectedType,
+      `      Expected value to be instance of ${expectedType.name || expectedType}
+      Actual: ${this.actualValue?.constructor?.name || typeof this.actualValue}`
+    );
+  }
+  toHaveLength(expectedLength) {
+    const actualLength = this.actualValue?.length;
+    this.triggerResult(
+      actualLength === expectedLength,
+      `      Expected length: ${expectedLength}
+      Actual length: ${actualLength}`
+    );
+  }
   toMatch(expectedValue) {
     if (typeof this.actualValue.match !== "function") {
       throw new Error(`You can not use toMatch on type ${typeof this.actualValue}`);
@@ -107,9 +191,18 @@ class MatcherFactory {
     );
   }
   toContain(needle) {
+    const value = this.actualValue;
+    let contains;
+    if (typeof value === "string") {
+      contains = value.includes(String(needle));
+    } else if (value instanceof Array) {
+      contains = value.indexOf(needle) !== -1;
+    } else {
+      contains = false;
+    }
     this.triggerResult(
-      this.actualValue instanceof Array && this.actualValue.indexOf(needle) !== -1,
-      `      Expected ` + this.actualValue + ` to contain ` + needle
+      contains,
+      `      Expected ` + value + ` to contain ` + needle
     );
   }
   toBeLessThan(greaterValue) {
@@ -124,6 +217,18 @@ class MatcherFactory {
       `      Expected ` + this.actualValue + ` to be greater than ` + smallerValue
     );
   }
+  toBeGreaterThanOrEqual(value) {
+    this.triggerResult(
+      this.actualValue >= value,
+      `      Expected ${this.actualValue} to be greater than or equal to ${value}`
+    );
+  }
+  toBeLessThanOrEqual(value) {
+    this.triggerResult(
+      this.actualValue <= value,
+      `      Expected ${this.actualValue} to be less than or equal to ${value}`
+    );
+  }
   toBeCloseTo(expectedValue, precision) {
     const shiftHelper = Math.pow(10, precision);
     this.triggerResult(
@@ -131,18 +236,23 @@ class MatcherFactory {
       `      Expected ` + this.actualValue + ` with precision ` + precision + ` to be close to ` + expectedValue
     );
   }
-  toThrow(ErrorType) {
+  toThrow(expected) {
     let errorMessage = "";
     let didThrow = false;
     let typeMatch = true;
+    let messageMatch = true;
     try {
       this.actualValue();
       didThrow = false;
     } catch (e) {
       errorMessage = e.message || "";
       didThrow = true;
-      if (ErrorType) {
-        typeMatch = e instanceof ErrorType;
+      if (typeof expected === "function") {
+        typeMatch = e instanceof expected;
+      } else if (typeof expected === "string") {
+        messageMatch = errorMessage.includes(expected);
+      } else if (expected instanceof RegExp) {
+        messageMatch = expected.test(errorMessage);
       }
     }
     const functionName = this.actualValue.name || typeof this.actualValue === "function" ? "[anonymous function]" : this.actualValue.toString();
@@ -150,21 +260,113 @@ class MatcherFactory {
       didThrow,
       `      Expected ${functionName} to ${this.positive ? "throw" : "not throw"} an exception ${!this.positive && errorMessage ? `, but an error with the message "${errorMessage}" was thrown` : ""}`
     );
-    if (ErrorType) {
+    if (typeof expected === "function") {
+      this.triggerResult(
+        typeMatch,
+        `      Expected Error type '${expected.name}', but the error is not an instance of it`
+      );
+    } else if (expected !== void 0) {
+      this.triggerResult(
+        messageMatch,
+        `      Expected error message to match ${expected}
+      Actual message: "${errorMessage}"`
+      );
+    }
+  }
+  async toReject(expected) {
+    let didReject = false;
+    let errorMessage = "";
+    let typeMatch = true;
+    let messageMatch = true;
+    try {
+      await this.actualValue;
+      didReject = false;
+    } catch (e) {
+      didReject = true;
+      errorMessage = e?.message || String(e);
+      if (typeof expected === "function") {
+        typeMatch = e instanceof expected;
+      } else if (typeof expected === "string") {
+        messageMatch = errorMessage.includes(expected);
+      } else if (expected instanceof RegExp) {
+        messageMatch = expected.test(errorMessage);
+      }
+    }
+    this.triggerResult(
+      didReject,
+      `      Expected promise to ${this.positive ? "reject" : "resolve"}${!this.positive && errorMessage ? `, but it rejected with "${errorMessage}"` : ""}`
+    );
+    if (didReject && typeof expected === "function") {
       this.triggerResult(
         typeMatch,
-        `      Expected Error type '${ErrorType.name}', but the error is not an instance of it`
+        `      Expected rejection type '${expected.name}', but the error is not an instance of it`
+      );
+    } else if (didReject && expected !== void 0) {
+      this.triggerResult(
+        messageMatch,
+        `      Expected rejection message to match ${expected}
+      Actual message: "${errorMessage}"`
       );
     }
   }
+  async toResolve() {
+    let didResolve = false;
+    let errorMessage = "";
+    try {
+      await this.actualValue;
+      didResolve = true;
+    } catch (e) {
+      didResolve = false;
+      errorMessage = e?.message || String(e);
+    }
+    this.triggerResult(
+      didResolve,
+      `      Expected promise to ${this.positive ? "resolve" : "reject"}${!didResolve ? `, but it rejected with "${errorMessage}"` : ""}`
+    );
+  }
 }
-const describe = async function(moduleName, callback) {
+const describe = async function(moduleName, callback, options) {
+  const suiteTimeoutMs = typeof options === "number" ? options : options?.timeout ?? timeoutConfig.suiteTimeout;
   print("\n" + moduleName);
-  await callback();
+  const t0 = now();
+  try {
+    await withTimeout(callback, suiteTimeoutMs, `describe: ${moduleName}`);
+  } catch (e) {
+    if (e instanceof TimeoutError) {
+      ++countTestsFailed;
+      print(`  ${RED}\u23F1 Suite timed out: ${e.message}${RESET}`);
+    } else {
+      throw e;
+    }
+  }
+  const duration = now() - t0;
+  print(`  ${GRAY}\u21B3 ${formatDuration(duration)}${RESET}`);
   beforeEachCb = null;
   afterEachCb = null;
 };
+describe.skip = async function(moduleName, _callback) {
+  ++countTestsIgnored;
+  print(`
+${BLUE}- ${moduleName} (skipped)${RESET}`);
+};
+const hasDisplay = () => {
+  const env = globalThis.process?.env;
+  if (env) {
+    return !!(env.DISPLAY || env.WAYLAND_DISPLAY);
+  }
+  try {
+    const GLib = globalThis?.imports?.gi?.GLib;
+    if (GLib) {
+      return !!(GLib.getenv("DISPLAY") || GLib.getenv("WAYLAND_DISPLAY"));
+    }
+  } catch (_) {
+  }
+  return false;
+};
 const runtimeMatch = async function(onRuntime, version) {
+  if (onRuntime.includes("Display")) {
+    return { matched: hasDisplay() };
+  }
   const currRuntime = await getRuntime();
   const foundRuntime = onRuntime.find((r) => currRuntime.includes(r));
   if (!foundRuntime) {
@@ -210,23 +412,34 @@ const beforeEach = function(callback) {
 const afterEach = function(callback) {
   afterEachCb = callback;
 };
-const it = async function(expectation, callback) {
+const it = async function(expectation, callback, options) {
+  const timeoutMs = typeof options === "number" ? options : options?.timeout ?? timeoutConfig.testTimeout;
+  const t0 = now();
   try {
     if (typeof beforeEachCb === "function") {
       await beforeEachCb();
     }
-    await callback();
+    await withTimeout(callback, timeoutMs, expectation);
     if (typeof afterEachCb === "function") {
       await afterEachCb();
     }
-    print(`  ${GREEN}\u2714${RESET} ${GRAY}${expectation}${RESET}`);
+    const duration = now() - t0;
+    print(`  ${GREEN}\u2714${RESET} ${GRAY}${expectation}  (${formatDuration(duration)})${RESET}`);
   } catch (e) {
-    print(`  ${RED}\u274C${RESET} ${GRAY}${expectation}${RESET}`);
+    const duration = now() - t0;
+    if (!e.__testFailureCounted) {
+      ++countTestsFailed;
+    }
+    const icon = e instanceof TimeoutError ? "\u23F1" : "\u274C";
+    print(`  ${RED}${icon}${RESET} ${GRAY}${expectation}  (${formatDuration(duration)})${RESET}`);
     print(`${RED}${e.message}${RESET}`);
-    if (e.stack)
-      print(e.stack);
+    if (e.stack) print(e.stack);
   }
 };
+it.skip = async function(expectation, _callback) {
+  ++countTestsIgnored;
+  print(`  ${BLUE}-${RESET} ${GRAY}${expectation} (skipped)${RESET}`);
+};
 const expect = function(actualValue) {
   ++countTestsOverall;
   const expecter = new MatcherFactory(actualValue, true);
@@ -237,7 +450,12 @@ const assert = function(success, message) {
   if (!success) {
     ++countTestsFailed;
   }
-  nodeAssert(success, message);
+  try {
+    nodeAssert(success, message);
+  } catch (error) {
+    error.__testFailureCounted = true;
+    throw error;
+  }
 };
 assert.strictEqual = function(actual, expected, message) {
   ++countTestsOverall;
@@ -245,6 +463,7 @@ assert.strictEqual = function(actual, expected, message) {
     nodeAssert.strictEqual(actual, expected, message);
   } catch (error) {
     ++countTestsFailed;
+    error.__testFailureCounted = true;
     throw error;
   }
 };
@@ -256,11 +475,9 @@ assert.throws = function(promiseFn, ...args) {
   } catch (e) {
     error = e;
   }
-  if (!error)
-    ++countTestsFailed;
+  if (!error) ++countTestsFailed;
   nodeAssert.throws(() => {
-    if (error)
-      throw error;
+    if (error) throw error;
   }, args[0], args[1]);
 };
 assert.deepStrictEqual = function(actual, expected, message) {
@@ -269,6 +486,7 @@ assert.deepStrictEqual = function(actual, expected, message) {
     nodeAssert.deepStrictEqual(actual, expected, message);
   } catch (error) {
     ++countTestsFailed;
+    error.__testFailureCounted = true;
     throw error;
   }
 };
@@ -283,16 +501,18 @@ const runTests = async function(namespaces) {
   }
 };
 const printResult = () => {
+  const totalMs = runStartTime > 0 ? now() - runStartTime : 0;
+  const durationStr = totalMs > 0 ? `  ${GRAY}(${formatDuration(totalMs)})` : "";
   if (countTestsIgnored) {
     print(`
 ${BLUE}\u2714 ${countTestsIgnored} ignored test${countTestsIgnored > 1 ? "s" : ""}${RESET}`);
   }
   if (countTestsFailed) {
     print(`
-${RED}\u274C ${countTestsFailed} of ${countTestsOverall} tests failed${RESET}`);
+${RED}\u274C ${countTestsFailed} of ${countTestsOverall} tests failed${durationStr}${RESET}`);
   } else {
     print(`
-${GREEN}\u2714 ${countTestsOverall} completed${RESET}`);
+${GREEN}\u2714 ${countTestsOverall} completed${durationStr}${RESET}`);
   }
 };
 const getRuntime = async () => {
@@ -325,17 +545,54 @@ const printRuntime = async () => {
   print(`
 Running on ${runtime2}`);
 };
-const run = async (namespaces) => {
+const run = async (namespaces, options) => {
+  applyEnvOverrides();
+  runStartTime = now();
+  if (options) {
+    if (typeof options === "number") {
+      timeoutConfig.runTimeout = options;
+    } else {
+      if (options.timeout !== void 0) timeoutConfig.runTimeout = options.timeout;
+      if (options.testTimeout !== void 0) timeoutConfig.testTimeout = options.testTimeout;
+      if (options.suiteTimeout !== void 0) timeoutConfig.suiteTimeout = options.suiteTimeout;
+    }
+  }
   printRuntime().then(async () => {
-    return runTests(namespaces).then(() => {
-      printResult();
-      print();
-      mainloop?.quit();
-    });
+    try {
+      await withTimeout(() => runTests(namespaces), timeoutConfig.runTimeout, "entire test run");
+    } catch (e) {
+      if (e instanceof TimeoutError) {
+        print(`
+${RED}\u23F1 ${e.message}${RESET}`);
+        ++countTestsFailed;
+      } else {
+        throw e;
+      }
+    }
+  }).then(async () => {
+    printResult();
+    print();
+    quitMainLoop();
+    mainloop?.quit();
+    if (!mainloop) {
+      const exitCode = countTestsFailed > 0 ? 1 : 0;
+      try {
+        const process = globalThis.process || await import("process");
+        process.exit(exitCode);
+      } catch (_e) {
+      }
+    }
   });
   mainloop?.run();
+  if (mainloop) {
+    const exitCode = countTestsFailed > 0 ? 1 : 0;
+    try {
+      globalThis.imports.system.exit(exitCode);
+    } catch (_e) {
+    }
+  }
 };
-var src_default = {
+var index_default = {
   run,
   assert,
   expect,
@@ -344,13 +601,15 @@ var src_default = {
   beforeEach,
   on,
   describe,
+  configure,
   print
 };
 export {
   afterEach,
   assert,
   beforeEach,
-  src_default as default,
+  configure,
+  index_default as default,
   describe,
   expect,
   it,