risei 1.3.4 → 2.0.0

package/README.md

@@ -4,16 +4,16 @@
 ## What Risei is
 
 **Risei is a new way to write unit tests that allows you to:**
-* Whip up full test coverage of object-oriented or object-hosted JavaScript and TypeScript in no time.
-* Refactor or replace existing designs without worrying about the cost in past or future test time.
-* Create tests with immediate confidence, because you can't introduce mistakes in test code you write.
+* Whip up full test coverage in no time for object-oriented (or object-hosted) JavaScript and TypeScript.
+* Refactor or replace existing designs without worrying about about a heavy cost in past or future test construction.
+* Create tests with immediate confidence, since you can't introduce mistakes when writing test code.
 
 
 
 
 ## The Risei approach
 
-Risei replaces coded tests with simple declarative syntax that's far easier to draft than any other unit-testing approach.
+Risei replaces coded tests with simple declarative syntax.
 
 Here are two example tests.   `SortModel.countSort()` is being tested using the inputs from `.in` and the expected output from `.out`: 
 
@@ -25,12 +25,16 @@ Here is the terminal output of these two example tests.   Tests are grouped
 ![https://deusware.com/Output-example.png](https://deusware.com/Output-example.png)
 
 
-- An individual test may appear on one line or multiple lines, depending on how wide the terminal window is.
 - Any failing tests appear in light red.
-- Your latest-edited tests always sort to the bottom, so you can see your current test results at a glance.
+- Your latest tests always sort to the bottom so it's easy to find their results.
 
 
-Test runs also feature a title bar at the top, as well as a summary bar at the bottom:
+Test runs also feature a title bar at the top:
+
+![https://deusware.com/Title-example.png](https://deusware.com/Title-example.png)
+
+
+As well as a summary bar at the bottom:
 
 ![https://deusware.com/Summary-example.png](https://deusware.com/Summary-example.png)
 
@@ -39,9 +43,30 @@ Test runs also feature a title bar at the top, as well as a summary bar at the b
 
 ## Using Risei
 
-Risei is under active development.   If you've been here before, check out [what's new in Risei](#whats-new-in-risei) for the latest.   Also see [known issues and workarounds](#known-issues-and-workarounds) and [limitations in Risei](#limitations-in-risei).
+Risei is under active development.   The newest release, **2.0.0**, brings many major improvements:
+
+- You can now test properties just like methods.
+- You can now spoof properties on the targeted class instance.
+- Risei now can determine automatically if tested or spoofed methods and properties are static.
+- You can now perform arbitrary operations if needed.
+- You can now change a test property without accidentally creating a new test.
+- `Error` objects are now compared accurately.
+- Outputs for `throw` tests are now the entire `Error` objects (breaking change).
+
+Risei has been reengineered internally along with these improvements.
+
+- In addition, `ATestSource` is now a default export (breaking change).
+  - This means a simple adjustment from `import { ATestSource }` to `import ATestSource`.
+
+These changes and others are detailed at the new external Risei documentation website:
+
+&cruft, new site
+[https://deusware.com/risei-docs/index.html](https://deusware.com/risei-docs/index.html)
+
+If you've been here before, check out [what's new in Risei](#whats-new-in-risei) for the latest.   Also see [known issues and workarounds](#known-issues-and-workarounds) and [limitations in Risei](#limitations-in-risei).
+
+Risei works with Typescript, requiring only a few additional or different steps, described in [using Typescript with Risei](#using-typescript-with-risei).
 
-There are a few additional or different steps for [using Typescript with Risei](#using-typescript-with-risei).
 
 
 
@@ -53,7 +78,7 @@ Install Risei for development time only:
 npm install --save-dev risei
 ```
 
-Make sure your `package.json` specifies that ESM is in use:
+Make sure your `package.json` specifies that ECMAScript modules are in use:
 
 ```json
 "type": "module"
@@ -67,99 +92,20 @@ And add Risei's metadata to `package.json`:
 }
 ```
 
-Just a [few extra steps](#using-typescript-with-risei) are required for Risei to work with TypeScript.
-
-
-
-### Siting tests
-
-Add tests in files ending in `.rt.js` like this:
-
-```javascript
-import { ATestSource } from "risei/ATestSource";
-import { ClassToBeTested } from "somewhere";
-
-export class SomeTests extends ATestSource {
-    tests = [ ... ];  // This array is where test definitions are written.
-}
-```
-
-
-
-### Writing tests
-
-Write tests with Risei's easy syntax:
-
-```javascript
-tests = [ ...
-    { on: ContainerModelClass, with: [ "a", "b", "c" ],      // Target class and constructor args.
-      of: "doesContain",                                     // Target method.
-      for: "When the input arg is present, returns true.",   // Description of test.
-      in: [ "c" ],                                           // Inputs.
-      out: true },                                           // Expected output.
-...];
-```
-
-
-
-#### Write more tests with less syntax:
-
-You can save a lot of time by putting repeated test properties into an object once, just before the related tests:
-
-```javascript
-    /* All of the following tests are of ContainerModelClass. */
-    { on: ContainerModelClass, with: [ "a", "b", "c", "a", "b" ] },
+> Just a [few extra steps](#using-typescript-with-risei) are required for Risei to work with TypeScript.
 
-    /* Two tests for ContainerModelClass .doesContain(). */
-    { of: "doesContain" },
-    { for: "When the input arg is present, returns true.",
-      in: [ "c" ], out: true },
-    { for: "When the input arg is not present, returns false.",
-      in: [ "d" ], out: false },
-        
-    /* First test for ContainerModelClass .countOf(). */
-    { of: "countOf", for: "Returns the number present.", in: [ "b" ], out: 2 }
-```
+&cruft, new site / section
+- Further general options can be found [here](https://deusware.com/risei-docs/index.html#installation).
 
-- 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 `[]`.
+&cruft, new site / section
+- Further Typescript details can be found [here](https://deusware.com/risei-docs/index.html#using-typescript).
 
-- 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.
-
-
-
-#### Spoof away code dependencies:
-
-When your tests need certain results from code dependencies, just _spoof_ what you want using a `.plus` test property:
-
-```javascript
-        { on: CombinerClass, with: [], 
-          of: "combineResults",
-          plus: [ 
-            { on: ClassA, of: "someMethod", as: 10 },    // Spoof this ClassA method to return 10.
-            { on: ClassB, of: "someMethod" },            // Spoof this ClassB method not to return (or do) anything.
-            { of: "firstMethod", as: [ 7, 8, 9, 10 ] },  // Spoof a method on the tested class (CombinerClass).
-            { of: "secondMethod" },                      // Spoof a method on CombinerClass not to do anything.
-            { on: ClassC,                                // Spoof this ClassC method to be this nonce code.
-              of: "someMethod", 
-              as: (arg) => { return { color: arg }; } },  
-            { on: ClassD, as: [                          // Spoof two methods on ClassD at the same time.
-                { of: "firstMethod", as: 11 }, 
-                { of: "secondMethod", as: 12 } 
-              ] },
-          ],
-          for: "When called, returns an array of values from sources.",
-          in: [ "green" ], out: [ 7, 8, 9, 10, 10, 11, 12, { color: "green" } ] }
-```
-
-- It's just like _fakes_, _mocks_, or _test doubles_ in other test systems, but much easier to write and read.
-
-- Spoofed code is fully isolated within tests, even though spoof definitions collapse forward across tests (and within `.plus`).
 
 
 
 ### Running tests
 
-Run your tests by invoking Risei's `index.js` file:
+Once you've written your tests, run them by invoking Risei's `index.js` file:
 
 ```bash
 node ./node_modules/risei/index.js
@@ -179,292 +125,126 @@ And then run that script:
 npm test
 ```
 
-Risei can be used alongside other test frameworks, and even run with them from the same test script if you want.
-
+- Risei can be used alongside other test frameworks, and even run with them from the same test script if you want.
 
+&cruft, new site / section
+- Find more information about this mixed testing and other config / run options [here](https://deusware.com/risei-docs/index.html#running-tests).
 
-### Learning more about Risei
-
-Read through the rest of this doc to learn more about Risei's many capabilities, and about where Risei is headed.
-
-- For instance, learn about using `.and` to test static methods or throws.
-- Or learn about using `.from` to test property results or other state.
-- Don't miss out:  Once you've tried the basics, read the rest...!
-
-
-
-
-## Risei in depth
-
-<details>
-<summary>
-There's plenty more to learn about Risei and how it makes testing easy...
-</summary>
-
-### Installation
-
-- You can use any file extension you want in Risei's metadata in `package.json`, and Risei will scan those files for tests.
-
-- You can install Risei outside of development time the usual way, but as with any test system, this is definitely not recommended.
-
-- Risei uses ESM syntax, and may not work in older environments where that's not available or is patched in.
 
 
 
 ### Siting tests
 
-- Match your Risei test file's extensions to whatever you choose in the metadata in `package.json`.
-
-- Test classes must inherit from `ATestSource` in `"risei/ATestSource"`: this type name is looked for specifically, so duck-typing doesn't work.
-
-
-
-### Writing tests
-
-- The order and placement of test properties doesn't matter, although the order seen in the examples is probably most readable.
-
-
-
-#### Basic test properties and options for each:
-
-| Name   | Contents                                                                                                  |
-|--------|-----------------------------------------------------------------------------------------------------------|
-| `on`   | The class under test, as a symbol / name (already imported into the test file)                            |
-| `with` | An array of any arguments to pass to the constructor of the tested class, or an empty array `[]` if none |
-| `of`   | The name of the method under test, as a string, no `()` needed                                            |
-| `for`  | A description of what the test proves, for test output                                                    |
-| `in`   | An array of the input arguments to pass to the tested method, or an empty array `[]` if none             |
-| `out`  | The expected return value, not in an array                                                                |
-
-- There are additional properties for extended functionality, covered later.
-- The property names were chosen to be easy to remember and type, but longer alternatives are available, covered later.
-
-
-
-### Test-property reuse _AKA_ Collapsing forward
-
-- To save time and effort, any property you write is collapsed forward to subsequent tests unless you replace it or erase it with an empty array `[]`.
-  - Property values are gathered across partial test objects until they add up to a runnable test, which is then run.
-  - Changes to properties are combined with previous ones to produce intended new tests.
-    - For a rare and avoidable side-effect of this system, see [known issues and workarounds](#known-issues-and-workarounds).
-
-- Test contents, reused or not, are automatically reset when it makes the most sense:
-  - 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 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
-
-- Spoofing is Risei's way of providing test-only inputs from dependencies the tested code uses, written in simple declarative syntax.
-  - It's therefore the equivalent of test doubles, mocks, fakes, and so on.
-
-
-- As the earlier examples and this table show, you can spoof in many ways, both on the dependencies, and on the class being tested.
-- All classes whose members are being spoofed have to be imported.
-
-
-
-#### Spoof-definition properties:
-
-| Name | Necessary or Optional | Contents                                                                                                                                                             |
-|------|-----------------------|----------------------------------------------------------------------------|
-| `on` | Optional              | Symbol for a type (class); if omitted, the targeted model class is assumed |
-| `of` | Necessary             | Name of the method to spoof, as a string, trailing `()` not needed         |
-| `as` | Optional              | Value to return or nonce implementation; if omitted, an empty method with no return value is used<br> &mdash; or &mdash;<br>A list of partial spoof definitions for the same class |
-
-
-- You can spoof multiple methods of a class individually, or list them together with partial definitions as seen in the example, with the same effect either way.
-
-
-#### Partial spoof-definition properties:
-
-| Name | Necessary or Optional | Contents                                                                                          |
-|------|-----------------------|---------------------------------------------------------------------------------------------------|
-| `of` | Necessary             | Name of the method to spoof, as a string, trailing `()` not needed                                |                                                                                  
-| `as` | Optional              | Value to return or nonce implementation; if omitted, an empty method with no return value is used |
-
-
-- Defining new spoofing wipes out all old definitions.
-
-
-- Spoofing is done at the start of each test and undone at the end of each test, keeping all tests isolated.
-
-
-
-
-## Advanced Risei usage
-
-### Testing special test conditions with `.and`
-
-You can use the special test property `.and`, always a string, to indicate special conditions that apply to your test.
-- At present, the values available are `"static"` and `"throw"` / `"throws"` (either one works).
-- You can list `static` and `throw` / `throws` together if needed, separated by a space.
-
-The `.and` property is an expansion point for supporting more special conditions in the future.&nbsp;  Values will always be listable together (as long as any particular grouping makes sense).
-
-
-
-#### Testing static methods
-
-To test a static method, use an `.and` of `"static"`:
+Add tests in files ending in `.rt.js` like this:
 
 ```javascript
-{ on: StaticTextProfileModel, with: [] },
+import ATestSource from "risei/ATestSource";
+import { ClassToBeTested } from "somewhere";
 
-{ of: "getTextProfile",
-  for: "Returns accurate profile of arg text.",
-  and: "static",
-  in: [ "This is a short sentence." ],
-  out: { isFullSentence: true, characters: 25, words: 5 }
+export class SomeTests extends ATestSource {
+    tests = [ ... ];  // Test definitions are added here.
 }
 ```
 
 
 
-#### Testing throws
+### Writing tests
 
-To test a throw, use an `.and` of `"throw"` or `"throws"`:
+Write tests with Risei's simple syntax:
 
 ```javascript
-{ on: InstanceTextProfileModel, with: [] },
-
-{ of: "getTextProfile",
-  for: "Throws with a helpful message when there is no arg text.",
-  and: "throws",
-  in: [],
-  out: "Could not build a profile.  Did you forget to provide a text?"
-}
+tests = [ ...
+    { on: ContainerModelClass, with: [ "a", "b", "c" ],  // Target class and constructor args.
+      of: "doesContain",                                 // Target method name.
+      for: "When the arg is present, returns true.",     // Description of test.
+      in: [ "c" ],                                       // Inputs to method.
+      out: true },                                       // Expected output.
+...];
 ```
 
+- To test a throw path in a method, add an `.and` test property with the text value `"throws"`.
+
+- To test a property of the target instance after running code, add a `.from` property with the property's name as a string.
 
+- To test a value derived from the initial actual value, or otherwise from any available context, add a `from` property that's an arrow function taking (at present) `target` and `test` parameters:  `(target, test) => { return test.actual.someProperty; }`.
 
-### Testing object properties and other non-`return` results
+- To perform operations like creating files temporarily, use the `.do` property (encompassing two stages, `.before` and `.after`) to set up isolated test state, and `.undo` to restore normal state.
+  - The `.do`-`.before` steps are taken before the target class instance is created, the `.do`-`.after steps are taken after that but before the target method / property is run.
+  - The `.undo` is an arrow function taking a `test` arg.&nbsp;  It is run after all other steps of the test have been run.&nbsp;  **(2.0.0)**
 
-To test a value that isn't the exercised code's return value, you use `.out` normally, and you add a `.from` property to your test, which can be one of two things:
+  - To maintain the benefits of using Risei's declarative style, avoid arbitrary options as much as possible.
 
-| Contents of `.from`    | Usage                                                                   |
-|--------------------------------|-------------------------------------------------------------------------|
-| Property name as string        | Retrieves the actual from the named property on the test's target class |
-| Specialized function | Retrieves the actual from either its `target` or `test` parameter       |
+- If you prefer test property names that aren't JavaScript keywords, alternatives are available for all of them.
 
+- Further details about syntax options can be found [here](https://deusware.com/risei-docs/index.html#test-syntax).
 
-- Getting properties, mutated args, and other non-return values is known as _retrieving_.
-- Retrieving definitions collapse forward across tests unless replaced with new definitions, or erased by setting `.from` to an empty array `[]`.
 
 
-<details>
-<summary>
-&nbsp; More information
-</summary>
-<br>
 
-- Use of `.from` with a property name looks like this: 
+#### Write more tests with less syntax:
+
+To save a lot of time, state repeated test values just once, and let them _collapse forward_ into following tests:
 
 ```javascript
-{ on: StatefulModel, with: [] },
+    /* All of the following tests are of ContainerModelClass. */
+    { on: ContainerModelClass, with: [ "a", "b", "c", "a", "b" ] },
 
-{ of: "storePolyProduct",
-  for: "The result of the calculation is stored as .result.",
-  in: [ 10, 8, 9, 6 ], out: 4320, from: "result" },
+    /* Two tests for ContainerModelClass .doesContain(). */
+    { of: "doesContain" },
+    { for: "When the input arg is present, returns true.",
+      in: [ "c" ], out: true },
+    { for: "When the input arg is not present, returns false.",
+      in: [ "d" ], out: false },
+        
+    /* First test for ContainerModelClass .countOf(). */
+    { of: "countOf", for: "Returns the number present.", in: [ "b" ], out: 2 }
 ```
 
-- Only instance properties can be retrieved by name.&nbsp;  For static properties, use `.and` (covered earlier), plus a function as `.from` (covered next).
+- When you change the class in `.on`, all test properties are wiped away, and when you change the method in `.of`, only test properties about the class (like `.with`) are retained.
 
-When the contents of `.from` are a function, these are the two parameters:
+- Tests remain isolated, in effect, except when a test mutates input arguments.&nbsp;  In that case, restate them in each test so the mutations aren't carried forward.
 
-| Name     | Contents                                                                                          |
-|----------|---------------------------------------------------------------------------------------------------|
-| `target` | The instance of the class being tested                                                            |
-| `test`   | The test definition itself, whose properties may have been mutated by the tested method           |
+- Change test contents without possibly adding an unintended new test by adding a `.just` property (with any value, such as `true`) alongside the changed properties.&nbsp;  **(2.0.0)**
 
+&cruft, new site / details
+- Further options and details can be found [here](https://deusware.com/risei-docs/index.html#collapsing-forward).
 
-- The `test` parameter to a `.from` function contains all of the properties of your test definition, including those that collapsed forward.
-  - These properties are available by both short or long names (covered later). 
-- The `test.on` property always references the class under test, rather than an instance of it.
 
 
-- You can write a function for `.from` that uses `test.on` to get the values of static properties, in conjunction with `and: "static"` in the encompassing test.
 
+#### Ensure desired inputs from dependencies
 
-- Another usage of a `.from` function is to look at an input to see if it was changed as expected:
+To make code dependencies return what your tests need, just _spoof_ what you want using a `.plus` test property:
 
 ```javascript
-{ on: SecurityModel, with: [] },
-
-{ of: "addHash",
-  for: "The content's hash is added to the input arg a new property.",
-  in: [ { content: "SecretValue" }, iterations: 8 ],
-  out: { content: "SecretValue", hash: "FasBdQ-fljk%asPcdf" },
-  from: (target, test) => { return test.in[0]; } 
-},
+        { on: CombinerClass, with: [], 
+          of: "combineResults",
+          plus: [ 
+            { on: ClassA, of: "someMethod", as: 10 },  // Spoofing one method to return 10.
+            { on: ClassB, of: "someMethod" },          // Spoofing one method not to return anything.
+            { on: ClassC, as: [                        // Spoofing two class methods together. 
+                { of: "firstMethod", as: 11 }, 
+                { of: "secondMethod", as: 12 } 
+              ] },
+          ],
+          for: "When called, returns an array of values from sources.",
+          in: [ "green" ], out: [ 7, 8, 9, 10, 10, 11, 12, { color: "green" } ] }
 ```
 
-</details>
-
-
-
-### Property long names
-
-Property names are short so they're easy to use.&nbsp;  Some of them overlap with JavaScript keywords, but this causes no harm.
-
-All test properties have long names that you can use instead of the short ones if you prefer, mixed together as much as you want.&nbsp;  None of the long names are JavaScript keywords.
-
-
-<details>
-<summary>
-&nbsp; Test properties' short and long names
-</summary>
+- It's just like _fakes_, _mocks_, or _test doubles_ in other test systems, but easier to write and read.
 
-| Short Name | Long Name |
-|------------|-----------|
-| `on`       | `type`    |
-| `with`     | `initors` |
-| `of`       | `method`  |
-| `for`      | `nature`  |
-| `in`       | `inputs`  |
-| `out`      | `output`  |
-| `plus`     | `spoofed` |
-| `from`     | `source`  |
-| `and`      | `factors` |
+&cruft, site / section
+- There are many further spoofing options that save effort, including using nonce methods as spoofs and spoofing target-instance properties.&nbsp;  **(2.0.0)**&nbsp;  Check out all your options [here](https://deusware.com/risei-docs/index.html#collapsing-forward).
 
-</details>
 
-<br>
-
-<details>
-<summary>
-&nbsp; Spoof properties' short and long names
-</summary>
-
-| Short Name | Long Name |
-|------------|-----------|
-| `on`       | `target`  |
-| `of`       | `method`  |
-| `as`       | `output`  |
-
-</details>
-
-
-
-### Further capabilities of Risei
-
-Constructors can be tested with no special test properties or keywords.
-- The method name in `.of` is simply `"constructor"`.
-- Any `.with` args are completely ignored for a constructor test.&nbsp;  Only those in the test's `.in` property are used.
-  - However, a `.with` must still be provided.&nbsp;  It can simply be an empty array `[]`.
-
-</details>
+- Spoofed code is fully isolated within tests, even though spoof definitions collapse forward across tests (and within `.plus`).
 
 
 
 
 ## Using TypeScript with Risei
 
-Testing TypeScript code with Risei basically just means transpiling before running the tests, and being sure to point to its output JS files, not the TS ones.
+Testing TypeScript code with Risei basically just means transpiling before running the tests, and pointing Risei to the transpiled JS files.
 
 - Anything beyond those basics is intended to keep JS files separate from TS files and the output of web frameworks' own, complex build processes.
 
@@ -509,7 +289,6 @@ 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 Javascript (`.js`) files in the `outDir` path or subfolders there, using relative-path syntax:
@@ -523,90 +302,72 @@ import { TestedClass } from "../../dist/out-tsc/SubPath/TestedClass.js";
 
 
 
-## Limitations in Risei
-
-The following are not supported at present:
-- Use of `async` syntax
-- Code written in ESM `export` modules, but not within classes
-- Standalone functions and other functionality not built into classes, AKA _loose code_
-- CJS syntax using `require()`
-- Spoofing mixes of properties and methods, such as `something.method.property.method`
-- Debugging model code during tests
-- Comparing rare JS object types like `Proxy` or `ArrayBuffer` in test assertions
-
-Some of these are on the tentative future-development list.&nbsp;  In the meantime, Risei can be used to save development time for most of your JavaScript code, while these can be tested using another framework invoked alongside Risei.
+## What's new in Risei
 
+- Release **2.0.0** (month, 2024) introduces many [improvements](#using-risei), including new capabilities, bug fixes, and two breaking changes with only minor impacts on consuming code.
 
+- 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.
 
-## Troubleshooting
+- Release **1.3.2** (February, 2024) only improved this read-me's contents.
 
-Most problems with using Risei are minor mistakes in syntax, or omissions in test definitions:
+- Release **1.3.1** (February, 2024) reversed some changes in 1.3.0 that did not work as hoped.
 
-| 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 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 |
+- 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 not listed here, and old releases are dropped progressively over time.&nbsp;  Using the latest release is recommended.
 
-## Known issues and workarounds
 
-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.
 
+## Troubleshooting
 
-- 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.
-  - Risei is actually working as intended when this happens, but ways to optionally prevent it are being considered.
+Problems loading tests are almost always a missing or extra comma, brace, or similar.&nbsp;  When a test file can't be loaded, loading continues with the next file.&nbsp;  The number of tests drops (or doesn't increase as expected), and a gold bar appears naming the file and problem:
 
+![https://deusware.com/Gold-bar-example.png](https://deusware.com/Gold-bar-example.png)
 
+- Unfortunately, there is no way to list the problem line number.
+- A sudden fail of many test files is usually due to a problem in the tested code, not the tests themselves.
 
-## What's new in Risei
+Problems with test results themselves are usually due to omissions or other mistakes in test definitions.
 
-- Release **1.3.4** (March, 2024) fixes a bug that caused class definitions still to appear instead of class names when classes were used as object properties.
-  - As a side effect of this change, objects' own `toString()` is never used in onscreen test output any longer, but all of Risei's output display is now handled the same.
+For far more information about troubleshooting, including some specific error messages, check out the documentation [here](https://deusware.com/risei-docs/index.html#troubleshooting).
 
 
-- Release **1.3.3** (March, 2024) fixes a major bug related to file paths that prevented any tests from loading or running in Windows environments.
-  - Risei is now fully usable in Windows environments again.
 
 
-- Release **1.3.2** (February, 2024) does not change the code at all, but improves this read-me.
-  - It now explains the easiest way to deal with mutable args (which is just restating the args).
-  - A few mistakes in the text were also fixed.
+## Known issues and workarounds
 
+At present, there are two known issues, both with simple workarounds:
 
-- 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.
-  - Supporting built-in total test isolation is not feasible with collapsing forward, nor is it usually necessary given easy usage alternatives.
-  - In contrast, collapsing forward is both highly beneficial and frequently used.
+- When tested code mutates its args, the mutated forms are used in subsequent tests if collapsed forward.
+  - To avoid this, simply restate the args for each test that mutates them.
 
 
-- Release **1.3.0** (February, 2024) makes two changes:
-  - If there are any test-loading errors, their messages now appear in a new gold bar that appears below the summary of the test run.
-  - A test-sorting error has also been fixed that occurred when no test files existed yet. 
+- 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 add a `.just` or `.only` property, of any value, in the same objects as those tests.change properties as part of whole new tests, or else restate `.of` along with the changed properties.
+  - You can also clear existing properties with `.on` or `.of` and then do this, since then there aren't enough test properties present yet to comprise a full test.
 
 
-- Release **1.2.0** (January, 2024) changes sorting of test files to make tests you're working on now appear at the bottom.
-  - Previously tests were displayed in the order found, which is always alphabetical (though is not guaranteed to be so).
-  - The order for all files except one remains the same.
-  - The last-edited file is moved to the bottom, making it easy to see the latest test results.
 
+## Limitations in Risei
 
-- Release **1.1.2** of Risei (January, 2024) fixes two problems:
-  - Classes were sometimes displayed in output as their entire definition.&nbsp;  Now just the class name is displayed.
-  - All `Date` instances were considered equal, regardless of their actual value.&nbsp;  Now they only are considered equal when they actually are.
+The following are not supported at present:
+- Use of `async` syntax
+- Code written in ESM `export` modules, but not within classes
+- Standalone functions and other functionality not built into classes, AKA _loose code_
+- CJS syntax using `require()`
+- Debugging model code during tests
+- Comparing rare JS object types like `Proxy` or `ArrayBuffer` in test assertions
 
+Some of these are on the tentative future-development list.
+- In the meantime, Risei can be used to save development time for most of your JavaScript code, while these cases can be tested using another framework invoked alongside Risei.
 
-- Don't use release **1.1.1**, which contains an internal path error.
 
 
 
@@ -638,3 +399,5 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
 
 
 &nbsp;
+
+