risei 1.3.0 → 1.3.2

package/README.md

@@ -123,9 +123,9 @@ You can save a lot of time by putting repeated test properties into an object on
     { of: "countOf", for: "Returns the number present.", in: [ "b" ], out: 2 }
 ```
 
-- This _collapsing forward_ works for just about every test property, but is reset when you change the class in `.on`, when you give the property a new value, or you erase it with an empty array `[ ]`.
+- This _collapsing forward_ is reset when you change the class in `.on`, when you give the property a new value, or you erase it with an empty array `[ ]`.
 
-- Collapsing forward doesn't reduce test isolation — for instance, with mutable args — because Risei always runs a copy of the test definition, not the original.
+- Tests are isolated in general, but if the code you're testing mutates its arguments, you have to state them in each test so the mutations aren't carried forward.
 
 
 
@@ -153,9 +153,9 @@ When your tests need certain results from code dependencies, just _spoof_ what y
           in: [ "green" ], out: [ 7, 8, 9, 10, 10, 11, 12, { color: "green" } ] }
 ```
 
-- Spoofing collapses forward across tests, but not across the elements within `.plus`.
+- It's just like _fakes_, _mocks_, or _test doubles_ in other test systems, but much easier to write and read.
 
-- Spoofing is also fully isolated within tests.
+- Spoofed code is fully isolated within tests, even though spoof definitions collapse forward across tests (and within `.plus`).
 
 
 
@@ -254,10 +254,9 @@ There's plenty more to learn about Risei and how it makes testing easy...
   - Changing the tested class in `.on` wipes out all prior test properties, so the new class has a fresh start.
   - Changing the tested method in `.of` wipes out only test properties related to methods, to preserve class values you usually want.
 
-- Individual tests remain fully isolated:
-  - Test args, including objects and functions in `.with`, `.plus`, and `.in`, are all copied for running in each test, so nothing is reused across tests.
-  - Class instances, spoofs (covered later), and so on are all created anew for each test.
-
+- Individual tests remain isolated, except for when args are mutated by the code under test.
+  - Restate args for each test when the code mutates them.
+  - This limitation is the result of limits on what can be copied reliably in JavaScript.
 
 
 ### Choosing test-only dependency inputs _AKA_ Spoofing
@@ -515,7 +514,7 @@ You set up the transpiler to output files to a directory with these settings:
 
 ### In test files:
 
-All `import` statements have to point to the `outDir` path or subfolders there, using relative-path syntax:
+All `import` statements have to point to the Javascript (`.js`) files in the `outDir` path or subfolders there, using relative-path syntax:
 
 ```javascript
 import { TestedClass } from "../../dist/out-tsc/SubPath/TestedClass.js";
@@ -525,6 +524,7 @@ import { TestedClass } from "../../dist/out-tsc/SubPath/TestedClass.js";
 
 
 
+
 ## Limitations in Risei
 
 The following are not supported at present:
@@ -545,33 +545,39 @@ Some of these are on the tentative future-development list.   In the meanti
 
 Most problems with using Risei are minor mistakes in syntax, or omissions in test definitions:
 
-| Error condition or text                                             | Probable cause / fix                                                                                                                                                                                                                                                                                                                       |
+| Error condition or text                                             | Probable cause                                                                                                                                                                                                                                                                                                                       |
 |---------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | Gold bar appears below the summary, and the number of tests run drops        | A syntax error caused a test file not to load; error output in the gold bar explains why                                                                                                                                                                                                                                        |
 | `"Test loading failed for...  SyntaxError: Unexpected token ':'"`   | Missing comma in your tests in the named file                                                                                                                                                                                                                                                                                              |
 | `"Test loading failed for...  SyntaxError: Unexpected token '.'"`   | Using `this.tests = []` instead of `tests = []` in the file named                                                                                                                                                                                                                                                                          |
 | Other `... Unexpected token ...` errors                             | Some other syntax error in the file named, most likely a missing or extra delimiter                                                                                                                                                                                                                                                        |
-| Unexpected actual values, or unexpected passes / fails in test runs | Spoofs, retrievals, or special conditions from previous tests not replaced or reset with `[ ]`<br>&mdash; or &mdash;<br>Pre-listed test properties produce extra tests: preventable by restating class in `.on` |
+| Unexpected extra, failing test/s   | Partial test properties in a mid-list object have produced extra tests |
+| Unexpected actual values, or unexpected passes / fails in test runs | Test properties from previous tests not replaced or reset with `[ ]` <br>&mdash; or &mdash;<br> Args mutated by tested code were not restated in following tests to isolate them |
 
 
 
 
 ## Known issues and workarounds
 
-- No bugs are known to exist at present.
+Two issues are known to exist:
+
+- When code mutates its args in test definitions, the mutated forms are used in subsequent tests unless those args are restated.
+  - To avoid this problem, just restate the args in each test of this code.
+  - The workaround for this &mdash; copying and initing objects to bypass mutation &mdash; requires too many assumptions to be reliable.
 
-- One unexpected result is known to exist:
-  - Changing one or more properties in objects by themselves in the middle of tests (perhaps to emphasize them) can create extra tests.
-    - The extra tests usually fail, because they have an unintended mix of old and new properties.
-    - In this case, Rs is actually working properly, running prior tests with the new properties swapped in.
-  - To avoid this problem, include changed properties in full tests to run, or restate `.of` along with the changed properties.
 
- - This situation is rarely an issue, but ways to optionally prevent it are being considered.
+- When a few properties are changed in separate objects, they are treated as whole new tests, which usually fail because of their unintended mix of old and new properties.
+  - To avoid this problem, just change properties as part of whole new tests, or else restate `.of` along with the changed properties.
+  - Rs is actually working as intended when this happens, but ways to optionally prevent it are being considered.
 
 
 
 ## What's new in Risei
 
+- Release **1.3.2** (February, 2024) does not change the code at all, but improves this read-me, notably explaining the easiest way to deal with mutable args (which is just restating the args), and correcting a few mistakes.
+
+- Release **1.3.1** (February, 2024) reverses some changes in 1.3.0 that were intended to fully isolate tests against mutable args, but which caused incomplete or inaccurate object contents in some cases.&nbsp;  This sort of built-in total isolation is not feasible, and in fact is rarely needed.
+
 - Release **1.3.0** (February, 2024) moves the display of test-loading error messages to a new gold bar that appears at the bottom of the summary when there are any loading errors.&nbsp;  A sorting error that occurs when no test files exist yet has also been fixed. 
 
 - Release **1.2.0** (January, 2024) changes sorting of test files.&nbsp;  Previously they were displayed in the order found.&nbsp;  Now the order remains the same, except that the last-edited file is moved to the bottom, making it easy to see the latest test results.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "risei",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "Risei is the framework that allows you to write unit tests as collections of values in JavaScript objects, so it's easy and fast, and tests don't serve as a drag on redesigns.",
   "keywords": [
     "unit test",
@@ -48,6 +48,6 @@
     "fs": "^0.0.1-security",
     "mocha": "^10.0.0",
     "morgan": "~1.9.1",
-    "risei": "1.2.0"
+    "risei": "1.3.2"
   }
 }

package/system/SpoofClassMethodsFixture.js

@@ -53,10 +53,10 @@ export class SpoofClassMethodsFixture extends ASpoofingFixture {
         }
     
         // Converting to scope object type.
-        let spoofDefinitionss = SpoofDefinition.fromNonceTuples(spoofNonces);
+        let spoofDefinitions = SpoofDefinition.fromNonceTuples(spoofNonces);
         
         // Storing spoofing definitions.
-        this.#retainSpoofsByClass(type, spoofDefinitionss);
+        this.#retainSpoofsByClass(type, spoofDefinitions);
         
         // Storing originals for restoring later.
         this.#reserveOriginalsByClass();
@@ -67,9 +67,9 @@ export class SpoofClassMethodsFixture extends ASpoofingFixture {
 
     // region Dependencies of spoof()
 
-    #retainSpoofsByClass(type, spoofDefinitionss) {
+    #retainSpoofsByClass(type, spoofDefinitions) {
         // Map of Maps: by type, then by method.
-        for (let tuple of spoofDefinitionss) {
+        for (let tuple of spoofDefinitions) {
             // If no .target, use `type`. 
             if (!tuple.target) {
                 tuple.target = type;

package/system/TestDefinition.js

@@ -299,8 +299,7 @@ export class TestDefinition {
             // Add (copy of) latest (for isolation), 
             // only if it's ready to run as a test.
             if (latest.isRunnable) {
-                let copy = latest.copy();
-                tuples.push(copy);
+                tuples.push(latest);
             }
         }
 

package/system/TestFrame.js

@@ -14,6 +14,7 @@ export class TestFrame {
     
     testFrame(test) {
         console.log(`cruft : a`);
+
         // Outer try for fails of groundwork requested.
         try {
             console.log(`cruft : b`);

package/system/TotalCopier.js

@@ -1,103 +1,106 @@
-/**/
-
-import { TypeIdentifier } from "./TypeIdentifier.js";
-import { Types } from "./Types.js";
-
-export class TotalCopier {
-    #identifier = new TypeIdentifier();
-
-    copy(original) /* passed */ {
-        return this.recursiveCopy(original);
-    }
-
-    recursiveCopy(original) /* verified */ {
-        /* &cruft, factor, possibly abstracting similar code, 
-                   and/or return copy only once, or similar */
-
-        /* Algorithm: First copied at current level by value if a value, by reference if 
-                      not a value; then recursively replaced at next level, and so on. */
-
-        let copy;
-        
-        let type = this.#identifier.identify(original);
-
-        if (type === Types.isArray) {
-            copy = [ ];
-            
-            // Traversal construction with recursion.
-            for (let item of original) {
-                let next = this.recursiveCopy(item);
-                copy.push(next);
-            }
-            
-            return copy;
-        }
-        
-        if (type === Types.isMap) {
-            copy = new Map();
-
-            // Traversal construction with recursion.
-            for (let entry of original.entries()) {
-                let next = this.recursiveCopy(entry);
-                copy.set(next[0], next[1]);
-            }
-            
-            return copy;
-        }
-        
-        if (type === Types.isSet) {
-            copy = new Set();
-
-            // Traversal construction with recursion.
-            for (let value of original.values()) {
-                let next = this.recursiveCopy(value);
-                copy.add(next);
-            }
-
-            return copy;
-        }
-
-        if (type === Types.isDate) {
-            copy = new Date(original);
-            return copy;
-        }
-        
-        // Actually copying isn't needed (or desirable) here, 
-        // since should always point to same thing regardless.
-        if (type === Types.isClass) {
-            copy = original;
-            return copy;
-        }
-
-        // The workaround here makes a true independent copy of the 
-        // original function, regardless of its definition style.
-        if (type === Types.isFunction) {
-            let passer = [ original ];
-            passer = [ ...passer ];
-            copy = passer[0];
-
-            return copy;
-        }
-
-        if (original instanceof Object) {
-            copy = { };
-            
-            let keys = Object.keys(original);
-            
-            // Traversal construction with recursion.
-            for (let key of Object.keys(original)) {
-                let next = this.recursiveCopy(original[key]);
-                copy[key] = next;
-            }
-            
-            return copy;
-        }
-        
-        /* &cruft, other object types here */
-
-        // All object types exhausted, so this is a value, 
-        // which can be used directly for a copy.
-        copy = original;
-        return copy;
-    }
-}
+/**/
+
+import { TypeIdentifier } from "./TypeIdentifier.js";
+import { Types } from "./Types.js";
+
+export class TotalCopier {
+    #identifier = new TypeIdentifier();
+
+    copy(original) /* passed */ {
+        return this.recursiveCopy(original);
+    }
+
+    recursiveCopy(original) /* verified */ {
+        /* &cruft, factor, possibly abstracting similar code, 
+                   and/or return copy only once, or similar */
+
+        /* Algorithm: First copied at current level by value if a value, by reference if 
+                      not a value; then recursively replaced at next level, and so on. */
+
+        let copy;
+        
+        let type = this.#identifier.identify(original);
+
+        if (type === Types.isArray) {
+            copy = [ ];
+            
+            // Traversal construction with recursion.
+            for (let item of original) {
+                let next = this.recursiveCopy(item);
+                copy.push(next);
+            }
+            
+            return copy;
+        }
+        
+        if (type === Types.isMap) {
+            copy = new Map();
+
+            // Traversal construction with recursion.
+            for (let entry of original.entries()) {
+                let next = this.recursiveCopy(entry);
+                copy.set(next[0], next[1]);
+            }
+            
+            return copy;
+        }
+        
+        if (type === Types.isSet) {
+            copy = new Set();
+
+            // Traversal construction with recursion.
+            for (let value of original.values()) {
+                let next = this.recursiveCopy(value);
+                copy.add(next);
+            }
+
+            return copy;
+        }
+
+        if (type === Types.isDate) {
+            copy = new Date(original);
+            return copy;
+        }
+        
+        // Actually copying isn't needed (or desirable) here, 
+        // since should always point to same thing regardless.
+        if (type === Types.isClass) {
+            copy = original;
+            return copy;
+        }
+
+        // The workaround here makes a true independent copy of the 
+        // original function, regardless of its definition style.
+        if (type === Types.isFunction) {
+            let passer = [ original ];
+            passer = [ ...passer ];
+            copy = passer[0];
+
+            return copy;
+        }
+
+        if (original instanceof Object) {
+            // If original has a prototype, it's probably a class instance, 
+            // so it's constructed, so it includes all methods and accessors.
+            let prototype = Object.getPrototypeOf(original);
+            copy = prototype !== null ? new prototype.constructor() : { };
+            
+            let keys = Object.keys(original);
+            
+            // Settable properties are added, with recursion.
+            for (let key of Object.keys(original)) {
+                let next = this.recursiveCopy(original[key]);
+                copy[key] = next;
+            }
+            
+            return copy;
+        }
+        
+        /* &cruft, other object types here */
+
+        // All object types exhausted, so this is a value, 
+        // which can be used directly for a copy.
+        copy = original;
+        return copy;
+    }
+}

package/system/TypeAnalyzer.js

@@ -1,103 +1,103 @@
-/**/
-
-/* Used to analyze classes / members of classes being tested. */
-
-export class TypeAnalyzer {
-    // region Definitions
-
-    static constructorName = "constructor";
-    static getName = "get";
-    static setName = "set";
-
-    // endregion Definitions
-
-    // region Fields
-
-    #type;
-
-    // endregion Fields
-
-    constructor(type) {
-        this.#type = type;
-    }
-
-    /* Returns true if instance or static member is a property (value or accessor).  Returns false if member is a method. */
-    memberIsProperty(name) /* passed */ {
-        // Constructor is never a property and is irregular, 
-        // so other type-analysis code can't handle it.
-        if (name === TypeAnalyzer.constructorName) {
-            return false;
-        }
-    
-        // Static methods and properties (value or accessor) are on type.
-        if (name in this.#type) {
-            return this.#staticMemberIsProperty(this.#type, name);
-        }
-        
-        // Methods and accessor properties are on prototype.
-        if (name in this.#type.prototype) {
-            return this.#instanceMemberIsProperty(this.#type.prototype, name);
-        }
-
-        // Instance value properties are not on type or prototype.
-        return true;
-    }
-    
-    // region Dependencies of memberIsProperty()
-    
-    /* Algorithm specialized with function check for static members. */
-    #staticMemberIsProperty(type, name) {
-        let descriptor = Object.getOwnPropertyDescriptor(type, name);
-        
-        // If on type and has accessors, it's a static accessor property.
-        if (this.#doesHaveAccessorProps(descriptor)) {
-            return true;
-        }
-        
-        // If on type and has non-Function .value, it's a static value property.
-        if (this.#doesNotHaveFunctionValue(descriptor)) {
-            return true;
-        }
-
-        // If on type but not a static property, it's a static method.
-        return false;
-    }
-
-    /* Algorithm specialized for instance members, no function check. */
-    #instanceMemberIsProperty(prototype, name) {
-        let descriptor = Object.getOwnPropertyDescriptor(prototype, name);
-        
-        // If on prototype and has accessors, it's an accessor property.
-        if (this.#doesHaveAccessorProps(descriptor)) {
-            return true;
-        }
-        
-        // If on prototype but not an accessor property, it's a method.
-        return false;
-    }
-    
-    // region Internally reused dependencies of other memberIsProperty() dependencies
-    
-    #doesHaveAccessorProps(descriptor) /* verified */ {
-        // Accessor properties have one or both of these in descriptor.
-        if (TypeAnalyzer.getName in descriptor || TypeAnalyzer.setName in descriptor) {
-            return true;
-        }
-        
-        return false;
-    }
-    
-    #doesNotHaveFunctionValue(descriptor) /* verified */ {
-        // Simple inverter of other method for readability.
-        return !this.#doesHaveFunctionValue(descriptor);
-    }
-    
-    #doesHaveFunctionValue(descriptor) /* verified */ {
-        // If no member, .value of undefined.
-        return descriptor.value instanceof Function;
-    }
-
-    // endregion Internally reused dependencies of other memberIsProperty() dependencies
-
-    // endregion Dependencies of memberIsProperty()
-}
+/**/
+
+/* Used to analyze classes / members of classes being tested. */
+
+export class TypeAnalyzer {
+    // region Definitions
+
+    static constructorName = "constructor";
+    static getName = "get";
+    static setName = "set";
+
+    // endregion Definitions
+
+    // region Fields
+
+    #type;
+
+    // endregion Fields
+
+    constructor(type) {
+        this.#type = type;
+    }
+
+    /* Returns true if instance or static member is a property (value or accessor).  Returns false if member is a method. */
+    memberIsProperty(name) /* passed */ {
+        // Constructor is never a property and is irregular, 
+        // so other type-analysis code can't handle it.
+        if (name === TypeAnalyzer.constructorName) {
+            return false;
+        }
+    
+        // Static methods and properties (value or accessor) are on type.
+        if (name in this.#type) {
+            return this.#staticMemberIsProperty(this.#type, name);
+        }
+        
+        // Methods and accessor properties are on prototype.
+        if (name in this.#type.prototype) {
+            return this.#instanceMemberIsProperty(this.#type.prototype, name);
+        }
+
+        // Instance value properties are not on type or prototype.
+        return true;
+    }
+    
+    // region Dependencies of memberIsProperty()
+    
+    /* Algorithm specialized with function check for static members. */
+    #staticMemberIsProperty(type, name) {
+        let descriptor = Object.getOwnPropertyDescriptor(type, name);
+        
+        // If on type and has accessors, it's a static accessor property.
+        if (this.#doesHaveAccessorProps(descriptor)) {
+            return true;
+        }
+        
+        // If on type and has non-Function .value, it's a static value property.
+        if (this.#doesNotHaveFunctionValue(descriptor)) {
+            return true;
+        }
+
+        // If on type but not a static property, it's a static method.
+        return false;
+    }
+
+    /* Algorithm specialized for instance members, no function check. */
+    #instanceMemberIsProperty(prototype, name) {
+        let descriptor = Object.getOwnPropertyDescriptor(prototype, name);
+        
+        // If on prototype and has accessors, it's an accessor property.
+        if (this.#doesHaveAccessorProps(descriptor)) {
+            return true;
+        }
+        
+        // If on prototype but not an accessor property, it's a method.
+        return false;
+    }
+    
+    // region Internally reused dependencies of other memberIsProperty() dependencies
+    
+    #doesHaveAccessorProps(descriptor) /* verified */ {
+        // Accessor properties have one or both of these in descriptor.
+        if (TypeAnalyzer.getName in descriptor || TypeAnalyzer.setName in descriptor) {
+            return true;
+        }
+        
+        return false;
+    }
+    
+    #doesNotHaveFunctionValue(descriptor) /* verified */ {
+        // Simple inverter of other method for readability.
+        return !this.#doesHaveFunctionValue(descriptor);
+    }
+    
+    #doesHaveFunctionValue(descriptor) /* verified */ {
+        // If no member, .value of undefined.
+        return descriptor.value instanceof Function;
+    }
+
+    // endregion Internally reused dependencies of other memberIsProperty() dependencies
+
+    // endregion Dependencies of memberIsProperty()
+}