risei 2.0.1 → 3.1.0

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, **2.0.1**, brings many major improvements, 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.0**, 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).
 
@@ -58,11 +58,13 @@ Check out the [full list of changes](#version-history).
 - #### Easy-to-read test definitions and test outputs.    ►  [Test and output examples](https://deusware.com/risei/index.html#examples)   (also above)
 - #### Even less to write by stating reused test properties only once.      ►   [Collapsing forward](https://deusware.com/risei/index.html#collapsing-forward)   (basics below)
 - #### Built-in declarative syntax to fake test-time values from dependencies.      ►   [Spoofing using `.plus`](https://deusware.com/risei/index.html#spoofing)   (basics below)
-- #### Testing properties, methods, static and instance members all the same way.      ►   [Properties and statics](https://deusware.com/risei/index.html#testing-properties-and-static-methods)
+- #### Full support for `async` code with no special syntax needed.      ►   [Writing tests](https://deusware.com/risei/index.html#writing-tests)   (basics below)
+- #### Testing properties and methods, static and instance members all the same way.      ►   [Properties and statics](https://deusware.com/risei/index.html#testing-properties-and-static-methods)
 - #### Testing `throw` paths effortlessly.      ►   [Using `.and: "throws"`](https://deusware.com/risei/index.html#using-and-throws)
 - #### Deriving actual values to test from raw outputs or property retrieval.      ►   [Using `.from`](https://deusware.com/risei/index.html#using-from)
 - #### Setting up and tearing down arbitrary test state.      ►   [Using `.do` and `.undo`](https://deusware.com/risei/index.html#using-do-and-undo)
 - #### Testing for `undefined` as output.      ►   [Using `this.undef`](https://deusware.com/risei/index.html#using-undef)
+- #### Running a method repeatedly in one test.      ►   [Using `.and: "poly"`](https://deusware.com/risei/index.html#using-and-poly)
 
 - And more!   Check out the full [Risei home page](https://deusware.com/risei).
 
@@ -89,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
@@ -140,11 +145,11 @@ tests = [ ...
 ... ];
 ```
 
+- Asynchronous code with `async` and `await` keywords can tested with no changes at all to this syntax.
 - Use empty arrays for `.in` or `.with` when there are no args to pass.
 - You can use [long names](https://deusware.com/risei/index.html#long-names) for properties if you want.
 
 
-
 ## Basic collapsing forward example
 
 You can state test properties once and let them _collapse forward_ across subsequent tests to save time and make tests easier to read.
@@ -187,6 +192,7 @@ The most basic spoofing looks like this:
 }
 ```
 
+- It's just like _fakes_, _mocks_, or _test doubles_ in other test systems, but easier to write and read.
 - Numerous additional capabilities, as well as compressed syntax, can be mixed freely in many ways.
 - Learn more [here](https://deusware.com/risei/index.html#spoofing).
 
@@ -202,16 +208,40 @@ 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 **2.0.1** (August, 2024) contains all of these changes:
+- 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 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>
+<summary>
+Older releases
+</summary>
+
+- 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.
@@ -221,46 +251,38 @@ If problems cause test files not to load, a gold bar appears and tests in those
   - You can now change test properties without accidentally creating a new test using `.just`.
   - You can now directly test for `undefined` in `.out` using `this.undef` / `ATestSource.undefSymbol`.
   - `Error` objects are now compared accurately.
-  - You can now identify member types with `.`, `:`, and `()` in `.of`, `.plus`, and `.from`, though they aren't necessary.
+  - You can now identify member types with `.`, `:`, and `()` in any of `.of`, `.plus`, and `.from`, though it isn't necessary.
   - **(Breaking change)**&nbsp;  The actual for throw tests is now the entire thrown object (usually an `Error`), rather than the `Error`'s message text.
   - **(Breaking change)**&nbsp;  `ATestSource` is now a default export, changing its imports from `import { ATestSource } from` to `import ATestSource from`.
+  - Major internal re-engineering.
 
-> Risei has been massively re-engineered internally along with these improvements.
-
+> Older releases are dropped from this list progressively over time.&nbsp;  Using the latest release is recommended.
 
+</details>
 
-<details>
-<summary>
-Older releases
-</summary>
 
-- Release **2.0.0** (August, 2024) is 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.
+## Known issues and workarounds
 
-</details>
+There are two minor issues at present:
 
+- 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.
 
-## Known issues and workarounds
 
-The only issue at present is reuse of method args mutated by tested code when collapsing forward. 
+- 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.
 
-- The workaround is just to restate those args for each test.
 
 
 ## Exclusions from Risei
 
-At present, there are a few things Risei doesn't support, such as `async` syntax.&nbsp;  Some of these may be supported in the future.
+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.
 
 
 
@@ -280,7 +302,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": "2.0.1",
+  "version": "3.1.0",
   "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.0.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": "^1.3.4"
+    "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/ClassTestGroup.js

@@ -1,8 +1,8 @@
-/**/
-
-import TestGroup from "./TestGroup.js";
-
-/* Identifies a grouping of tests by class.  No specialized workings. */
-
-export default class ClassTestGroup extends TestGroup {
-}
+/**/
+
+import TestGroup from "./TestGroup.js";
+
+/* Identifies a grouping of tests by class.  No specialized workings. */
+
+export default class ClassTestGroup extends TestGroup {
+}

package/system/LocalCaller.js

@@ -1,21 +1,61 @@
 /**/
 
-/* 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); 
+        this.runner.useTests(tests);
 
         // Getting each run test / summary result 
         // and having it reported in the terminal.
-        for (let result of this.runner) {
+        for await (let result of this.runner.runTests()) {
             this.reporter.reportNext(result);
         }
     }

package/system/MethodSpoofer.js

@@ -39,7 +39,7 @@ export default class MethodSpoofer extends ASpoofingFixture {
     // endregion Properties
 
     constructor() {
-        super("MethodSpoofer", "Construction");
+        super();
     }
     
     // Spoofs methods of classes as defined in nonce 
@@ -53,7 +53,7 @@ export default class MethodSpoofer extends ASpoofingFixture {
         if (!Array.isArray(spoofNonces)) {
             return;
         }
-
+        
         // Converting to scope object type.
         let spoofDefs = SpoofDef.fromNonceTuples(spoofNonces, type);
 

package/system/MethodTestGroup.js

@@ -1,8 +1,8 @@
-/**/
-
-import TestGroup from "./TestGroup.js";
-
-/* Identifies a grouping of tests by method.  No specialized workings. */
-
-export default class MethodTestGroup extends TestGroup {
-}
+/**/
+
+import TestGroup from "./TestGroup.js";
+
+/* Identifies a grouping of tests by method.  No specialized workings. */
+
+export default class MethodTestGroup extends TestGroup {
+}

package/system/Moment.js

@@ -1,29 +1,29 @@
-/**/
-
-export default class Moment {
-    #now;
-
-    constructor(now) {
-        this.#now = now;
-    }
-
-    asReadable() /* passed */ {
-        let now = this.#now;
-        let asTwo = this.#asTwo;
-    
-        let day = `${ now.getMonth() + 1 }/${ asTwo(now.getDate()) }/${ now.getFullYear() }`;
-
-        let time = `${ now.getHours() % 12 || 12 }:${ asTwo(now.getMinutes()) }:${ asTwo(now.getSeconds()) } `
-            + `${ now.getHours() < 12 ? "AM" : "PM" }`;
-
-        return `${ day } at ${ time }`;
-    }
-
-    #asTwo(number) /* verified */ {
-        let text = `${ number }`;
-        text = text.padStart(2, "0");
-
-        return text;
-    }
-
-}
+/**/
+
+export default class Moment {
+    #now;
+
+    constructor(now) {
+        this.#now = now;
+    }
+
+    asReadable() /* passed */ {
+        let now = this.#now;
+        let asTwo = this.#asTwo;
+    
+        let day = `${ now.getMonth() + 1 }/${ asTwo(now.getDate()) }/${ now.getFullYear() }`;
+
+        let time = `${ now.getHours() % 12 || 12 }:${ asTwo(now.getMinutes()) }:${ asTwo(now.getSeconds()) } `
+            + `${ now.getHours() < 12 ? "AM" : "PM" }`;
+
+        return `${ day } at ${ time }`;
+    }
+
+    #asTwo(number) /* verified */ {
+        let text = `${ number }`;
+        text = text.padStart(2, "0");
+
+        return text;
+    }
+
+}