risei 1.3.1 → 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 `[ ]`.
 
-- When the tested code mutates the contents of `.with` or `.in`, provide these args as the output of a function or method, because at present, the mutated values are collapsed forward.
+- 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,9 +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 isolated, except for when args are mutable.
-  - To use the original, un-mutated args for successive tests, just return them from a function or method to set `.with` or `.in`.
-
+- 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
@@ -514,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";
@@ -524,6 +524,7 @@ import { TestedClass } from "../../dist/out-tsc/SubPath/TestedClass.js";
 
 
 
+
 ## Limitations in Risei
 
 The following are not supported at present:
@@ -544,15 +545,15 @@ 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 `[ ]` |
-| Unexpected actual values, or unexpected passes / fails in test runs | Pre-listed test properties have produced extra tests; changing properties as part of new tests prevents this |
-| Unexpected actual values, or unexpected passes / fails in test runs | `.with` or `.in` values were mutated by a test and passed to subsequent tests; providing contents of these properties with a function prevents this |
+| 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 |
+
 
 
 
@@ -560,22 +561,22 @@ Most problems with using Risei are minor mistakes in syntax, or omissions in tes
 
 Two issues are known to exist:
 
-- If the contents of `.with` or `.in` are mutated by the code being tested, the mutated values are carried from test to test.
-  - To use the original, un-mutated args for successive tests, just return them from a function or method, and call it to set `.with` or `.in`.
-  - Ways to prevent this are being looked at.
+- 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.
 
 
-- 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.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;  Later work may restore full isolation in a different way at some point.
+- 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. 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "risei",
-  "version": "1.3.1",
+  "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.3.1"
+    "risei": "1.3.2"
   }
 }