risei 3.0.0 → 3.1.1

package/README.md

@@ -46,7 +46,7 @@ And they have a summary bar at the bottom:
 
 ## Status
 
-Risei is under active development and new enhancements appear often.   The latest release, **3.0.0**, brings major improvements, starting with the ability to test `async` code, and builds on many major improvements in **2.0.0**, including broader capabilities and simpler syntax, and a few minor breaking changes.
+Risei's major features are now complete, but new enhancements or fixes may appear from time to time.   The latest release, **3.1.1**, includes significant improvements and bug fixes, on top of the major improvements in releases **3.0.0** and **2.0.0**.
 
 Check out the [full list of changes](#version-history).
 
@@ -91,6 +91,9 @@ And add Risei's metadata to `package.json`:
 }
 ```
 
+## Testing Risei
+
+To test Risei, you clone it from a parallel [repository](https://gitlab.com/riseimaker/risei-public.git), install its dependencies, and run its self-tests.   See the full explanation [here](https://deusware.com/risei/index.html#self-testing).
 
 
 ## Running Tests
@@ -205,21 +208,30 @@ To test TypeScript code with Risei, you make sure the code is transpiled before
 
 ## Troubleshooting
 
-If problems cause test files not to load, a gold bar appears and tests in those files disappear from output:
+If errors are thrown while testing, gold bars listing them appear at the bottom, and full stack traces appear amid the test output.   If problems cause test files not to load, a gold bar with the error message also appears:
 
 ![https://deusware.com/risei/images/Gold-bar-example.png](https://deusware.com/risei/images/Gold-bar-example.png)
 
+- If files don't load, tests in those files disappear from the output and the totals.
 - Those and other problems can be solved with the help of this [troubleshooting guide](https://deusware.com/risei/index.html#troubleshooting).
 
 
 
 ## Version history
 
-- Release **3.0.0** (August, 2024) contains all of these changes:
-  - Asynchronous code with `async` syntax is now fully supported, with no special test syntax required.
-  - **(Breaking change)**   `.from` functions now take `test` and `actual` as parameters, rather than `target` and `test`.
-    - If you need to work with the target of the test (usually an instance of the class being tested), it's available as `test.target`.
-  - You can now call target code more than once in one test using an `.and` of `"poly"` (AKA _poly-calling_).
+- Release **3.1.1** (January, 2025) contains these changes:
+  - Extra commas and non-objects in arrays of test objects are disregarded, and no longer cause a throw.
+  - Throws in wider scopes are now listed at the end, like others already found there.
+
+- Release **3.1.0** (January, 2025) contains these changes:
+  - Accessor properties (formally _accessor descriptors_) are now compared for test results and displayed in test outputs.
+    - Any accessor properties that throw errors during display are displayed as `(threw)`.
+  - Throws in tested code and in test framing code are now listed at the end, and also displayed amid the tests.
+  - `File` objects now have a succinct custom display in outputs.
+  - **(Breaking change)**   In `constructor` tests, constructed instances are available in `.from` functions only as `actual` / `test.actual`.
+    - **(Breaking change)**   In `constructor` tests, `test.target` is now the `prototype` of the tested class.
+  - Widespread internal reengineering of other kinds.
+
 
 
 <details>
@@ -227,7 +239,13 @@ If problems cause test files not to load, a gold bar appears and tests in those
 Older releases
 </summary>
 
-- Release **2.0.1** (August, 2024) contained all of these changes:
+- Release **3.0.0** (August, 2024) contained all of these changes:
+  - Asynchronous code with `async` syntax is now supported, with no special test syntax.
+  - **(Breaking change)**&nbsp;  `.from` functions now take `test` and `actual` as parameters, rather than `target` and `test`.
+    - If you need to work with the target of the test (usually an instance of the class being tested), it's available as `test.target`.
+  - You can now call target code more than once in one test using an `.and` of `"poly"` (AKA _poly-calling_).
+
+- Release **2.0.0** / **2.0.1** (August, 2024) contained all of these changes:
   - Risei now can determine automatically if tested methods are static.
   - You can now directly test properties just like methods.
     - Risei can also determine automatically if these are static.
@@ -242,17 +260,7 @@ Older releases
   - **(Breaking change)**&nbsp;  `ATestSource` is now a default export, changing its imports from `import { ATestSource } from` to `import ATestSource from`.
   - Major internal re-engineering.
 
-- Release **2.0.0** (August, 2024) was identical to 2.0.1 except for some unneeded extra files.
-
-- Release **1.3.4** (March, 2024) fixed a bug that caused class display problems in some cases.
-- Release **1.3.3** (March, 2024) fixed a major bug that prevented tests from running in Windows.
-- Release **1.3.2** (February, 2024) only improved this read-me's contents.
-- Release **1.3.1** (February, 2024) reversed some changes in 1.3.0 that did not work as hoped.
-- Release **1.3.0** (February, 2024) added the loading-error gold bar and fixed a test-sorting bug.
-- Release **1.2.0** (January, 2024) changed test sorting to move last-edited tests to the end.
-- Release **1.1.2** of Risei (January, 2024) fixed class displays and inaccurate `Date` comparisons.
-
-> The oldest releases are no longer listed here, and old releases are dropped progressively over time.&nbsp;  Using the latest release is recommended.
+> Older releases are dropped from this list progressively over time.&nbsp;  Using the latest release is recommended.
 
 </details>
 
@@ -260,9 +268,14 @@ Older releases
 
 ## Known issues and workarounds
 
-The only issue at present is reuse of method args mutated by tested code when collapsing forward. 
+There are two minor issues at present:
 
-- The workaround is just to restate those args for each test.
+- If args for a test are mutated by tested code, the mutated args are used when collapsing forward.
+  - The workaround is just to restate those args for each test.
+
+
+- Spoofing accessor properties only works when they have both a getter and a setter.
+  - The workaround is to find another way to produce the property values you need.
 
 
 
@@ -271,7 +284,9 @@ The only issue at present is reuse of method args mutated by tested code when co
 At present, there are a few things Risei doesn't support.&nbsp;  Some of these may be supported in the future.
 
 - You can see the whole list [here](https://deusware.com/risei/index.html#exclusions-from-risei).
-- You can save a lot of time by using Risei for most of your code, and another framework for whatever it doesn't support.
+
+
+Risei can be run alongside other test frameworks, so if you can't test all of your code with Risei, you can still save a lot of time by using Risei to test the bulk of it.
 
 
 
@@ -291,7 +306,7 @@ Risei is published for use under the terms of the MIT license:
 
 <div style="border: solid darkgray 1px; padding: 0.5rem;">
 
-<b>Risei Copyright &copy; 2023&ndash;2024 Ed Fallin</b>
+<b>Risei Copyright &copy; 2023&ndash;2025 Ed Fallin</b>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

package/index.js

@@ -8,60 +8,21 @@
 
 // region Imports
 
-// region Test-running dependencies
-
+import TerminalReporter from "./system/TerminalReporter.js";
 import TestRunner from "./system/TestRunner.js";
 import LocalCaller from "./system/LocalCaller.js";
-import TerminalReporter from "./system/TerminalReporter.js";
 import TestFinder from "./system/TestFinder.js";
 
-// endregion Test-running dependencies
-
-// region Display dependencies
-
-import chalk from "chalk";
-import Moment from "./system/Moment.js";
-
-// endregion Display dependencies
-
 // endregion Imports
 
 // region Exports
 
-// region Classes that users typically subclass
+/* Class that users subclass for test classes. */
 
 export * from "./system/ATestSource.js";
 
-// endregion Classes that users typically subclass
-
-// region Classes that users might subclass for uncommon cases
-
-export * from "./system/ATestFinder.js";
-export * from "./system/ATestReporter.js";
-
-// endregion Classes that users might subclass for uncommon cases
-
 // endregion Exports
 
-// region Named styles
-
-/* Display styles for the start title and other general needs. */
-const title = chalk.hex("FFFFFF").bgHex("191970").bold;
-const fails = chalk.hex("000000").bgHex("FFD700").bold;
-
-// endregion Named styles
-
-// region Styling for color stripes
-
-let wide = (text) => { 
-    let width = process.stdout.columns;
-    text = text || "";
-
-    return text.padEnd(width, "\u00A0");
-};
-
-// endregion Styling for color stripes
-
 // region Key callable, its scripted call, and its export
 
 async function runRiseiTests(testFinderPath) {
@@ -76,30 +37,21 @@ async function runRiseiTests(testFinderPath) {
     
     // endregion Converting test-finder from path to class
 
+    let reporter = new TerminalReporter();
+
     // region Intro / title
     
-    console.clear();
-    console.log();
-    console.log(title(wide()));
-    
-    let now = new Date();
-    now = new Moment(now);
-    
-    console.log(title(wide(` Risei tests run on ${ now.asReadable() } local time.`)));
-    console.log(title(wide()));
-    
-    console.log();
-    
-    // endregion Intro / title
+    reporter.reportTitle();
+
+    // // endregion Intro / title
 
     // region Running tests
     
     // Test-system objects and their relationships.
-    const finder = new finderClass.prototype.constructor();
-    const runner = new TestRunner();
-    const reporter = new TerminalReporter();
-    
-    const caller = new LocalCaller(finder, runner, reporter);
+    let finder = new finderClass.prototype.constructor();
+    let runner = new TestRunner();
+
+    let caller = new LocalCaller(finder, runner, reporter);
 
     // Actually running the tests using this system.
     await caller.runAllTests();
@@ -109,20 +61,20 @@ async function runRiseiTests(testFinderPath) {
     // region Trailing display of test-loading issues
 
     if (finder.thrown.length !== 0) {
+        reporter.blankLine();
+
         let loadFails = finder.thrown;
 
         for (let fail of loadFails) {
-            console.log(fails(wide(` ${ fail }`)));
+            reporter.reportLoadFail(fail);
         }
     }
 
-    // endregion Trailing display of test-loading issues
-
     // region Trailing formatting
-    
-    console.log();
-    console.log();
-    
+
+    reporter.blankLine();
+    reporter.blankLine();
+
     // endregion Trailing formatting
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "risei",
-  "version": "3.0.0",
+  "version": "3.1.1",
   "description": "Risei allows you to write unit tests as simple JavaScript objects, so it's easy and fast, with no drag on redesign.",
   "keywords": [
     "unit test",
@@ -24,11 +24,11 @@
   "private": false,
   "scripts": {
     "start": "node ./bin/www",
-    "rself": "clear && node system/Risei.js",
+    "rself": "clear && node ./TrialTests.js",
     "rtest": "clear && node ./node_modules/risei/index.js",
     "xtest": "clear && mocha **/*.tests.js",
     "mixedtest": "clear && mocha **/*.tests.js; node ./node_modules/risei/index.js",
-    "alltest": "clear && mocha **/*.tests.js; node ./node_modules/risei/index.js; node system/Risei.js",
+    "alltest": "clear && mocha **/*.tests.js; node ./node_modules/risei/index.js; node ./TrialTests.js",
     "test": "clear && node ./node_modules/risei/index.js"
   },
   "risei": {
@@ -41,7 +41,9 @@
   "dependencies": {
     "chalk": "^5.0.0",
     "fs": "^0.0.1-security",
-    "minimatch": "^9.0.1"
+    "minimatch": "^9.0.1",
+    "npm": "^11.0.0",
+    "risei": "^3.1.0"
   },
   "devDependencies": {
     "chai": "^4.3.6",
@@ -49,7 +51,6 @@
     "debug": "~2.6.9",
     "fs": "^0.0.1-security",
     "mocha": "^10.0.0",
-    "morgan": "~1.9.1",
-    "risei": "^3.0.0"
+    "morgan": "~1.9.1"
   }
 }

package/system/CallTypes.js

@@ -0,0 +1,10 @@
+/**/
+
+export default class CallTypes {
+    static methodMono = "methodMono";
+    static propMono = "propMono";
+    static conMono = "conMono";
+    static methodPoly = "methodPoly";
+    static propPoly = "propPoly";
+    static conPoly = "conPoly";
+}

package/system/Choices.js

@@ -0,0 +1,92 @@
+/**/
+
+import path from "node:path";
+import fs from "node:fs";
+
+export default class Choices {
+    // region Definitions
+
+    static METADATA_FILE = "package.json";
+    static TESTS_PROP = "tests";
+
+    // endregion Definitions
+
+    // region Static fields
+
+    // Local copy of package.json's .risei node.
+    static #node;
+
+    // endregion Static fields
+
+    // region Static choice properties
+
+    static get testTargeting() /* verified */ {
+        let tests = Choices.#supplyOrThrow(Choices.TESTS_PROP);
+        return tests;
+    }
+
+    // endregion Static choice properties
+
+    // region Dependencies of static properties
+
+    /* Used for properties that are always needed. */
+    static #supplyOrThrow(prop) /* verified */ {
+        Choices.#maybeSetNode();
+        Choices.#throwWhenMissing(prop);
+        return Choices.#node[prop];
+    }
+
+    /* Used for properties that aren't always needed. */
+    static #supplyOrUndef(prop) /* verified */ {
+        Choices.#maybeSetNode();
+
+        if (!Choices.#nodeContains(prop)) {
+            return undefined;
+        }
+
+        return Choices.#node[prop];
+    }
+
+    static #maybeSetNode() /* verified */ {
+        if (Choices.#node === undefined) {
+            Choices.#setNode();
+        }
+    }
+
+    // To init hidden Singleton instance.
+    static #setNode() /* verified */ {
+        // App's package.json always found at process.cwd().
+        let packageSite = process.cwd();
+        let pathAndName = path.join(packageSite, Choices.METADATA_FILE);
+
+        // Contents of package.json are just a single JSON object.
+        let packageJson = fs.readFileSync(pathAndName, { encoding: "utf8" });
+        packageJson = JSON.parse(packageJson);
+
+        // Can't run or reasonably recover if this is not defined.
+        if (packageJson.risei === undefined) {
+            throw new Error(
+                `For Risei tests to run, this app's package.json must contain `
+                + `a node like this: "risei": { tests: "path-or-glob-here" }.  `
+                + `One glob or path may be used, or an array of them.`);
+        }
+
+        // Only Risei's own metadata is needed.
+        Choices.#node = packageJson.risei;
+    }
+
+    static #throwWhenMissing(prop) /* verified */ {
+        if (!Choices.#nodeContains(prop)) {
+            throw new Error(
+                `The property .${ prop } is not defined `
+                 + `for .risei in package.json.`
+            );
+        }
+    }
+
+    static #nodeContains(prop) /* verified */ {
+        return prop in Choices.#node;
+    }
+
+    // endregion Dependencies of static properties
+}

package/system/LocalCaller.js

@@ -1,14 +1,54 @@
 /**/
 
-/* LocalCaller is an ATestCaller that invokes each available test in turn locally 
-   on the server, without HTTP calls from a browser or other external source. */
+/* LocalCaller has TestRunner run each test in turn on the server, 
+   without HTTP calls from a browser or other external source. */
 
-import ATestFinder from "./ATestFinder.js";
-import ATestCaller from "./ATestCaller.js";
 import TerminalReporter from "./TerminalReporter.js";
 import TestRunner from "./TestRunner.js";
 
-export default class LocalCaller extends ATestCaller {
+export default class LocalCaller {
+    // region Fields
+
+    #finder;
+    #runner;
+    #reporter;
+
+    // endregion Fields
+
+    // region Properties
+
+    get finder() {
+        return this.#finder;
+    }
+    
+    set finder(value) {
+        this.#finder = value;
+    }
+
+    get runner() {
+        return this.#runner;
+    }
+
+    set runner(value) {
+        this.#runner = value;
+    }
+
+    get reporter() {
+        return this.#reporter;
+    }
+
+    set reporter(value) {
+        this.#reporter = value;
+    }
+
+    // endregion Properties
+
+    constructor(finder, runner, reporter) {
+        this.#finder = finder;
+        this.#runner = runner;
+        this.#reporter = reporter;
+    }
+
     async runAllTests() {
         let tests = await this.finder.findAllTests();
         this.runner.useTests(tests);

package/system/ObjectAnalyzer.js

@@ -0,0 +1,36 @@
+/**/
+
+import TypeAnalyzer from "./TypeAnalyzer.js";
+
+export default class ObjectAnalyzer {
+    /* Retrieves names of all properties, both values 
+       and accessors, including all in superclasses. */
+    static allProperties(topic) /* passed */ {
+        let proto = Object.getPrototypeOf(topic);
+
+        let getters = [];
+
+        // Accessors, including in superclasses.
+        // Nonce object has no prototype / type.
+        if (proto !== null) {
+            let type = proto.constructor;
+            getters = TypeAnalyzer.allGetters(type);
+        }
+
+        let names = [];
+
+        // All value names, including inherited ones.
+        for (let name in topic) {
+            names.push(name);
+        }
+
+        // Concat good enough since sorting needed after anyway.
+        let output = names.concat(getters);
+
+        // Instead of mixed two sets in order coded, 
+        // accessors backwards up prototype chain.
+        output.sort();
+
+        return output;
+    }
+}