risei 1.3.3 → 2.0.0

package/README.md

@@ -4,18 +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.
-
-Risei may be referred to as **Rs** here for brevity.
+* 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`: 
 
@@ -27,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:
+
+![https://deusware.com/Title-example.png](https://deusware.com/Title-example.png)
 
 
-Test runs also feature a title bar at the top, as well as a summary bar at the bottom:
+As well as a summary bar at the bottom:
 
 ![https://deusware.com/Summary-example.png](https://deusware.com/Summary-example.png)
 
@@ -41,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).
 
 
 
@@ -55,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"
@@ -69,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" ] },
-
-    /* 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 }
-```
-
-- 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 `[]`.
+> Just a [few extra steps](#using-typescript-with-risei) are required for Risei to work with 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.
+&cruft, new site / section
+- Further general options can be found [here](https://deusware.com/risei-docs/index.html#installation).
 
+&cruft, new site / section
+- Further Typescript details can be found [here](https://deusware.com/risei-docs/index.html#using-typescript).
 
 
-#### 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
@@ -181,298 +125,132 @@ 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.
 
-### Learning more about Risei
+&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).
 
-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.
 
-### Testing object properties and other non-`return` results
+- 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; }`.
 
-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 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)**
 
-| 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       |
+  - To maintain the benefits of using Risei's declarative style, avoid arbitrary options as much as possible.
 
+- If you prefer test property names that aren't JavaScript keywords, alternatives are available for all of them.
 
-- 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 `[]`.
+- Further details about syntax options can be found [here](https://deusware.com/risei-docs/index.html#test-syntax).
 
 
-<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>
-
-| Short Name | Long Name |
-|------------|-----------|
-| `on`       | `type`    |
-| `with`     | `initors` |
-| `of`       | `method`  |
-| `for`      | `nature`  |
-| `in`       | `inputs`  |
-| `out`      | `output`  |
-| `plus`     | `spoofed` |
-| `from`     | `source`  |
-| `and`      | `factors` |
-
-</details>
-
-<br>
+- It's just like _fakes_, _mocks_, or _test doubles_ in other test systems, but easier to write and read.
 
-<details>
-<summary>
-&nbsp; Spoof properties' short and long names
-</summary>
+&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).
 
-| 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.
 
 If you follow the general Risei set-up, you can just make the following few modifications for TypeScript applications.
 - These steps have worked with both Angular and React.
-- Variant approaches are also sure to work, depending on the other technical choices in play.
+- Varying other approaches are also sure to work, depending on the other technical choices in play.
 
 
 
@@ -511,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:
@@ -525,70 +302,72 @@ import { TestedClass } from "../../dist/out-tsc/SubPath/TestedClass.js";
 
 
 
-## Limitations in Risei
+## What's new 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
+- 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.
 
-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.
+- 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.
 
-## Troubleshooting
+- Release **1.3.0** (February, 2024) added the loading-error gold bar and fixed a test-sorting bug.
 
-Most problems with using Risei are minor mistakes in syntax, or omissions in test definitions:
+- Release **1.2.0** (January, 2024) changed test sorting to move last-edited tests to the end.
 
-| 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.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:
+## Troubleshooting
 
-- 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.
+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)
 
-- 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.
+- 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.
 
+Problems with test results themselves are usually due to omissions or other mistakes in test definitions.
 
+For far more information about troubleshooting, including some specific error messages, check out the documentation [here](https://deusware.com/risei-docs/index.html#troubleshooting).
 
-## What's new in Risei
 
-- 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.
 
-- 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.
+## Known issues and workarounds
+
+At present, there are two known issues, both with simple workarounds:
+
+- 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.
+
+
+- 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.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.
 
-- 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.
+## 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()`
+- 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.
 
 
 
@@ -620,3 +399,5 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
 
 
 &nbsp;
+
+