risei 1.1.0 → 1.1.1

package/README.md

@@ -8,72 +8,55 @@
 * 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 was originally known as _RiseiJs_.   Risei is often referred to as **Rs** here for brevity.
+> Risei is under active development.   To see the latest changes, check out [What's new in Risei](#whats-new-in-risei).
+> 
+> For a list of any known bugs and workarounds, see [Known bugs and workarounds](#known-bugs-and-workarounds).   To see which JavaScript features Risei doesn't address yet, check out [Limitations in Risei](#limitations-in-risei).
 
+Risei may be referred to as **Rs** here for brevity.   A dotted `.name` here means a property, just like a `name()` with parens is a method or function.
 
 
-## Basics of the Risei approach
 
-Risei replaces coded tests with simple declarative syntax that's far easier to draft than any other unit-testing approach.
 
-Here are two example tests.   `SortModel.countSort()` is being tested with the inputs found in `.in` and the expected output found in `.out`: 
+## The Risei approach
+
+Risei replaces coded tests with simple declarative syntax that's far easier to draft than any other unit-testing approach.
 
-<div style="padding-left: 1.5rem">
+Here are two example tests.&nbsp;  `SortModel.countSort()` is being tested using the inputs from `.in` and the expected output from `.out`: 
 
 ![https://deusware.com/Syntax-example.png](https://deusware.com/Syntax-example.png)
 
-</div>
 
 Here is the terminal output of these two example tests.&nbsp;  Tests are grouped by class and method.&nbsp;  Inputs, expected, and actual values are displayed for all tests, to make intended usage obvious at a glance:
 
-<div style="padding-left: 1.5rem;">
-
 ![https://deusware.com/Output-example.png](https://deusware.com/Output-example.png)
 
-</div>
 
 An individual test may appear on one line or multiple lines, depending on how wide the terminal window is.&nbsp;  Any failing tests appear in light red.&nbsp;
 
 Test runs also feature a title bar, as well as a summary bar at the bottom:
 
-<div style="padding-left: 1.5rem;">
-
 ![https://deusware.com/Summary-example.png](https://deusware.com/Summary-example.png)
 
-</div>
 
 
 
-## How to install Risei
+## Using Risei
 
-1. Install Risei the usual way for a development-time `npm` package:
+### Installation
 
-<div style="padding-left: 1.5rem;">
+Install Risei for development time only:
 
 ```bash
 npm install --save-dev risei
 ```
 
-</div>
-
-<details>
-<summary>
-&nbsp; More information
-</summary>
-<br>
-
-- Risei is an `npm` package that uses ESM syntax.&nbsp;  It only works well with modern versions of Node that automatically support ESM.
-  - Although ESM is usable with older Node versions using external workarounds, a modern version is highly recommended, and Rs is not guaranteed to work with older versions.
-- You can install Rs as a regular dependency if you want, using `npm install risei`, but ordinarily this doesn't make sense, and exposing tests in production is generally considered a bad practice.
-  - Risei doesn't directly add any security risks to your code, but exposing tests that use it might (as it can with other test frameworks).
-
-</details>
-
-
+Make sure your `package.json` specifies that ESM is in use:
 
-2. Add a `risei` node to your project's `package.json` to tell Rs what kind of files to find tests in:
+```json
+"type": "module"
+```
 
-<div style="padding-left: 1.5rem;">
+And add Risei's metadata to `package.json`:
 
 ```json
 "risei": {
@@ -81,359 +64,225 @@ npm install --save-dev risei
 }
 ```
 
-</div>
-
-<details>
-<summary>
-&nbsp; More options
-</summary>
-<br>
-
-- The extension `.rt.js` is standard, but you can actually use any extension you want.
-- Whatever extension you use, it should be unique, to avoid scanning many extra files for tests at each test run.
-
-</details>
-
-
-
-## How to use Risei
-
-1. Create test files with a `.rt.js` extension.
-
-<details>
-<summary>
-&nbsp; More options
-</summary>
-<br>
-
-- If you chose another extension for your unit-test files (covered earlier), use that instead here.
-
-</details>
 
 
+### Siting tests
 
-2. Import `ATestSource` from `risei/ATestSource` in each test file, subclass it, and set `tests` to an array of test definitions.
-
-<div style="padding-left: 1.5rem;">
+Add tests in files ending in `.rt.js` like this:
 
 ```javascript
 import { ATestSource } from "risei/ATestSource";
-import { TargetClass } from "your/path/and/file.js";
+import { ClassToBeTested } from "somewhere";
 
-export TargetClassTests extends ATestSource {
-    tests = [ ];    // Not `this.tests`.  This array is where test definitions are written.
+export class SomeTests extends ATestSource {
+    tests = [ ... ];  // This array is where test definitions are written.
 }
 ```
 
-</div>
-
-<details>
-<summary>
-&nbsp; More information
-</summary>
-<br>
-
-- Tests must be placed in subclasses of `ATestSource`.
-  - Risei looks for this class relationship internally, so duck-typing does not work.
-- You have to `import` the class/es being tested in the file/s containing their tests.
-- Don't use &cross;`this.tests` by accident &mdash; it just causes an exception when tests are run.
-
-</details>
 
 
+### Writing tests
 
-3. Write each test as a JavaScript object literal in the array, using Risei's simple, light syntax: 
-
-<div style="padding-left: 1.5rem;">
+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" ], out: true }                              // Inputs and expected output.
-    ... ];
+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.
+...];
 ```
 
-</div>
-
-<details>
-<summary>
-&nbsp; Basic test properties and options for each
-</summary>
-<br>
-
-<div style="padding-left: 1.5rem;">
-
-| Name   | Contents                                                                 |
-|--------|--------------------------------------------------------------------------|
-| `on`   | The class under test, as a symbol (already imported into the test file)  |
-| `with` | An array of any arguments to pass to the constructor of the tested class |
-| `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             |
-| `out`  | The expected return value, not in an array                               |
-
-- Properties can be listed in any order within a test definition.
-- There are additional properties for extended functionality (covered later).
-- When there are no parameters for a class' constructor, use an empty array `[ ]` for `.with`.
-- When there are no inputs to a method, use an empty array `[ ]` for `.in`.
-- When the output of a method is an array, freely use an array for `.out`.
-- When there is no output to a method, put the expected value in `.out`, and use special syntax to get the actual value to compare it with (covered later).
-- The property names were chosen to be easy to remember and type, but longer alternatives are available (covered later).
-
-</div>
-
-</details>
-
 
 
-4. Write more tests with less syntax, by defining properties that are automatically reused in upcoming tests, and/or setting only the properties in a test that are different from the previous test/s:
+#### Write more tests with less syntax:
 
-<div style="padding-left: 1.5rem;">
+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 },
+    /* 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 }
+    /* First test for ContainerModelClass .countOf(). */
+    { of: "countOf", for: "Returns the number present.", in: [ "b" ], out: 2 }
 ```
 
-</div>
-
-<details>
-<summary>
-&nbsp; More information
-</summary>
-<br>
-
-- This simplification tactic, called _collapsing forward_, saves a lot of typing and makes reading tests much easier.
-- Individual tests remain isolated because class instances, spoofed methods (covered later) and so on are all created anew for each test.
-- Test contents are partially or fully reset when it makes the most sense:
-  - Changing the class under test in `.on` wipes out all prior test properties, so the new class has a fresh start.
-  - Changing the method under test with a new `.of` wipes out only test properties related to methods, to preserve class values you usually want.
-- You can also change individual test properties such as `.with` whenever you want just by stating a new value &mdash; but by design, they are collapsed forward to following tests.
-
-</details>
+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 `[ ]`.  
 
 
 
-5. To isolate any tests with dependencies, you define test-only results for the methods depended on using _spoofing_, which is similar to mocks or fakes, but easier to use.&nbsp;  Definitions for spoofs are set in the `.plus` property:
+#### Spoof away code dependencies:
 
-<div style="padding-left: 1.5rem;">
+When your code has dependencies on other code, just _spoof_ the results of that code to get what your test needs from it, using a `.plus` property on your tests that offers many options:
 
 ```javascript
         { on: CombinerClass, with: [ ], 
           of: "combineResults",
           plus: [ 
-            { on: ArraySource, of: "getAllValues", as: [ 7, 8, 9, 10 ] }, 
-            { on: ScalarSource, of: "getValue", as: 12 },
-            { on: ObjectSource, of: "getObject", as: { color: "green" } }
-          ]
+            { 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: [ ], out: [ 7, 8, 9, 10, 12, { color: "green" } ] }
+          in: [ "green" ], out: [ 7, 8, 9, 10, 10, 11, 12, { color: "green" } ] }
 ```
 
-- Spoofing definitions collapse forward across tests unless they're replaced with new definitions, or are erased by setting `.plus` to an empty array `[ ]`.
-- Defining new spoofing wipes out all old definitions.
-
-</div>
+These are basically all varieties of spoofing.&nbsp;  Spoofing collapses forward across tests, but not across the elements within `.plus`. 
 
-<details>
-<summary>
-&nbsp; Spoofing syntax and options
-</summary>
-<br>
 
-- Each object in `.plus` consists of the following:
 
-<div style="padding-left: 1.5rem;">
+### Running tests
 
-| Name | Necessary or Optional | Contents                                                                                                                  |
-|------|-----------------------|---------------------------------------------------------------------------------------------------------------------------|
-| `on` | Optional              | Symbol for a type (class); if omitted, the targeted model class is assumed                                                |
-| `of` | Necessary             | Name of method to spoof, as a string, `()` not needed                                                                     |                                                                                  
-| `as` | Optional              | Value to return, or nonce implementation; if omitted, an empty method with no return value is used |
+Run your tests by invoking Risei's `index.js` file:
 
-</div>
-
-- You can leave out `.as` when you don't need a return value.&nbsp;  In that case, an empty method is used (that is, `() => { }`).
-- When necessary, you can provide a function to use in place of the real code, in `.as`.
+```bash
+node ./node_modules/risei/index.js
+```
 
+Or write a `package.json` script that does the same:
 
-- This example uses all three syntax options:
+```json
+"scripts": {
+  ...
+  "test": "node ./node_modules/risei/index.js",
+  ...
+}
+```
 
-<div style="padding-left: 1.5rem;">
+And then run that script:
 
-```javascript
-        { on: CombinerClass, with: [ ], 
-          of: "combineResults",
-          plus: [ 
-            { on: ArraySource, of: "getAllValues", as: [ 7, 8, 9, 10 ] },
-            { on: ScalarSource, of: "getValue" },
-            { on: ObjectSource, of: "getObject", as: () => { return { color: "blue" }; } }
-          ]
-          for: "When called, returns sources' values, skipping any undefineds.",
-          in: [ ], out: [ 7, 8, 9, 10, { color: "blue" } ] }
+```bash
+npm test
 ```
 
-</div>
+Risei can be used alongside other test frameworks.&nbsp;  You might run them all from the same test script, or perhaps write unique scripts for each.
 
-- You can spoof methods nested inside of other objects  using `.` syntax in the `.of` property:
 
-<div style="padding-left: 1.5rem;">
 
-```javascript
-          plus: [
-            { on: SimpleObject, of: "getText", as: "Text" }, 
-            { on: DeepObject, of: "root.branch.leaf.getOptimum", as: 100 }
-          ]
-```
+### Learning more about Risei
 
-</div>
+Be sure to read through the rest of this doc to learn more about Risei's many capabilities, and about where Risei is headed.
 
-- Types whose members are being spoofed (like `ArraySource` or `SimpleObject` in the examples) have to be imported normally.
-- The properties in the spoof definitions within `.plus` don't collapse forward within the array, but must be repeated for each one.
-- You can spoof methods of objects provided in a test's `.with` and `.in` as well, although you usually don't need to.
-- Properties of spoof objects also have long names (covered later).
+- For instance, learn about using `.and` to test static code or throws.
+- Or learn about using `.from` to test property results or other state.
+- Don't miss out:&nbsp; Once you've tried the basics, read the rest...!
 
-<details>
-<summary>
-&nbsp; Further spoofing options
-</summary>
-<br>
 
-- You can spoof many methods on a class at the same time with an array of partial spoof objects for the `.as` property:
 
-<div style="padding-left: 1.5rem;">
 
-```javascript
-          plus: [
-            { on: SimpleObject, of: "getText", as: "Text" }, 
-            { on: ComplexObject, 
-                as: [ { of: "getIntegers", as: [ 6, 7, 8 ] }, 
-                      { of: "getDoubles", as: [ 6.0, 7.0, 8.0 ] } ]
-            }
-          ]
-```
+## Risei in depth
 
-</div>
+### Installation
 
-- You can use this syntax, or list multiple full `.on`-`.as`-`.of` objects for a class in `.plus`, with the same effect either way.
-- Nested partial spoof definitions in `.as: [ ... ]` never contain `.on`, and must contain at least `.of`.
-- As in other spoof definitions, `.as` can be omitted in these nested partial spoof objects, with the same effect.
+- You can use any file extension you want in Risei's metadata in `package.json`, and Risei will scan those files for tests.
 
-</details>
+- You can install Risei outside of development time the usual way, but as with any test system, this is definitely not recommended.
 
-</details>
+- Risei uses ESM syntax, and may not work in older environments where that's not available or is patched in.
 
 
 
-## How to run Risei tests
+### Siting tests
 
-1. Run your tests by invoking Risei's `index.js` file:
+- Match your Risei test file's extensions to whatever you choose in the metadata in `package.json`.
 
-<div style="padding-left: 1.5rem;">
+- Test classes must inherit from `ATestSource` in `"risei/ATestSource"`: this type name is looked for specifically, so duck-typing doesn't work.
 
-```bash
-node ./node_modules/risei/index.js
-```
 
-</div>
 
-<details>
-<summary>
-&nbsp; More information
-</summary>
-<br>
+### Writing tests
 
-- At present, Rs isn't set up as a script that runs independently, nor as a compiled executable, so you have to run it via its entry-point script.
+- The order and placement of test properties doesn't matter, although the order seen in the examples is probably most readable.
 
-</details>
 
+#### 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                                                                |
 
-2. Or write the `test` script in `package.json` to invoke `index.js`, to make your life easier:
+- 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.
 
-<div style="padding-left: 1.5rem;">
 
-```json
-"scripts": {
-  "test": "node ./node_modules/risei/index.js"
-}
-```
-</div>
+</details>
 
-<details>
-<summary>
-&nbsp; More options
-</summary>
-<br>
 
-- You can instead write a unique script for Rs, though this takes more syntax to call later:
+### Test-property reuse _AKA_ Collapsing forward
 
-<div style="padding-left: 1.5rem;">
+- 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 bugs and workarounds](#known-bugs-and-workarounds).
 
-```json
-"scripts": {
-  "risei": "node ./node_modules/risei/index.js"
-}
-```
+- 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.
 
-</div>
 
-- You can define your test scripting to include the Risei tests alongside other tests if you wish to mix framework usages, which may be appropriate for some scenarios:
+- Individual tests remain isolated because class instances, spoofed methods (covered later) and so on are all created anew for each test.
+  - However, input (`.in`) and instantiation (`.with`) arguments that are mutated by tested code are not yet isolated.
+  - They will be fully isolated in a future release.
+  - In the meantime, calling a function to supply them to `.in` or `.with` does isolate them completely.
 
-<div style="padding-left: 1.5rem;">
 
-```json
-"risei": "node ./node_modules/risei/index.js"
-"test": "mocha **/* && risei" 
-```
+### Choosing test-only dependency inputs _AKA_ Spoofing
 
-</div>
+- 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.
 
-- Of course, if you are used to Linux / Unix scripting, you may also find other techniques to make running tests easier.
 
-</details>
+- 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:
 
-3. Run that script whenever you want to run tests:
+| 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 |
 
-<div style="padding-left: 1.5rem;">
 
-```bash
-npm test
-```
+- 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.
 
-</div>
 
-<details>
-<summary>
-&nbsp; More options
-</summary>
-<br>
+#### Partial spoof-definition properties:
 
-- Or run a custom script with longer syntax like this:
+| 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 |
 
-<div style="padding-left: 1.5rem;">
 
-```bash
-npm run risei
-```
+- Defining new spoofing wipes out all old definitions.
 
-</div>
 
-</details>
+- Spoofing is done at the start of each test and undone at the end of each test, keeping all tests isolated.
+
 
 
 
@@ -441,17 +290,11 @@ npm run risei
 
 ### 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.&nbsp;  At present, the values available are `"static"` and `"throw"` / `"throws"` (either one works).&nbsp;  You can list `static` and `throw` / `throws` together if needed, separated by a space.
+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.
 
-<details>
-<summary>
-&nbsp; More information
-</summary>
-<br>
-
-- 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).
-
-</details>
+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).
 
 
 
@@ -459,8 +302,6 @@ You can use the special test property `.and`, always a string, to indicate speci
 
 To test a static method, use an `.and` of `"static"`:
 
-<div style="padding-left: 1.5rem">
-
 ```javascript
 { on: StaticTextProfileModel, with: [] },
 
@@ -472,16 +313,12 @@ To test a static method, use an `.and` of `"static"`:
 }
 ```
 
-</div>
-
 
 
 #### Testing throws
 
 To test a throw, use an `.and` of `"throw"` or `"throws"`:
 
-<div style="padding-left: 1.5rem">
-
 ```javascript
 { on: InstanceTextProfileModel, with: [] },
 
@@ -493,22 +330,17 @@ To test a throw, use an `.and` of `"throw"` or `"throws"`:
 }
 ```
 
-</div>
-
 
 
 ### Testing object properties and other non-`return` results
 
 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:
 
-<div style="padding-left: 1.5rem">
-
 | 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       |
 
-</div>
 
 - 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 `[ ]`.
@@ -522,8 +354,6 @@ To test a value that isn't the exercised code's return value, you use `.out` nor
 
 - Use of `.from` with a property name looks like this: 
 
-<div style="padding-left: 1.5rem">
-
 ```javascript
 { on: StatefulModel, with: [] },
 
@@ -532,20 +362,15 @@ To test a value that isn't the exercised code's return value, you use `.out` nor
   in: [ 10, 8, 9, 6 ], out: 4320, from: "result" },
 ```
 
-</div>
-
 - Only instance properties can be retrieved by name.&nbsp;  For static properties, use `.and` (covered earlier), plus a function as `.from` (covered next).
 
 When the contents of `.from` are a function, these are the two parameters:
 
-<div style="padding-left: 1.5rem">
-
 | 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 |
+| `test`   | The test definition itself, whose properties may have been mutated by the tested method           |
 
-</div>
 
 - 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). 
@@ -557,8 +382,6 @@ When the contents of `.from` are a function, these are the two parameters:
 
 - Another usage of a `.from` function is to look at an input to see if it was changed as expected:
 
-<div style="padding-left: 1.5rem">
-
 ```javascript
 { on: SecurityModel, with: [] },
 
@@ -570,8 +393,6 @@ When the contents of `.from` are a function, these are the two parameters:
 },
 ```
 
-</div>
-
 </details>
 
 
@@ -588,8 +409,6 @@ All test properties have long names that you can use instead of the short ones i
 &nbsp; Test properties' short and long names
 </summary>
 
-<div style="padding-left: 1.5rem;">
-
 | Short Name | Long Name |
 |------------|-----------|
 | `on`       | `type`    |
@@ -602,8 +421,6 @@ All test properties have long names that you can use instead of the short ones i
 | `from`     | `source`  |
 | `and`      | `factors` |
 
-</div>
-
 </details>
 
 <br>
@@ -613,16 +430,12 @@ All test properties have long names that you can use instead of the short ones i
 &nbsp; Spoof properties' short and long names
 </summary>
 
-<div style="padding-left: 1.5rem;">
-
 | Short Name | Long Name |
 |------------|-----------|
 | `on`       | `target`  |
 | `of`       | `method`  |
 | `as`       | `output`  |
 
-</div>
-
 </details>
 
 
@@ -640,10 +453,15 @@ Constructors can be tested with no special test properties or keywords.
 
 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.
+- 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.
+
 
 
 
@@ -651,14 +469,50 @@ The following are not supported at present:
 
 Most problems with using Risei are minor mistakes in syntax, or omissions in test definitions:
 
-| Error text                                                          | Probable cause / fix                                                                               |
-|---------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
-| `"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 `[ ]` 
+| Error condition or text           | Probable cause / fix                                           |
+|-----------------------------------|----------------------------------------------------------------|
+| Sudden drop in the number of tests run                              | An error occurred in a test file; error output at the top of the test run 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>Tested method mutates `.in` or `.with` args: preventable by using a function to supply those args<br>&mdash; or &mdash;<br>Pre-listed test properties produce extra tests: preventable by restating class in `.on` 
+|
+
+
+
+
+## Known bugs and workarounds
+
+One known bug exists:
+- When the args stated in `.with` or `.in` are mutated by the method under test (or by anything done within a test), the mutated values are carried forward to other tests.
+- A workaround exists for now: just provide those args using a fixture function when they may be mutated.&nbsp;  The function is called each time, isolating them completely.
+
+
+ - This problem with test isolation is being fixed in an upcoming release.
+
+
+One known unexpected result (not quite a bug) exists:
+- Because test properties collapse forward to form whole tests, pre-stating new properties for upcoming tests without changing `.on` is treated as a new test like prior ones, with just those properties changed.
+  - Pre-stating properties might be done as a way to make them stand out when reading through the tests.
+
+- This means you see an extra unexpected test that most likely fails, due to the mix of old and new properties.
+
+- A workaround exists: if you pre-state new properties, also restate the class under test in `.on`, which erases all prior test properties.
+  - Restating `.on` doesn't cause the class name to be displayed again in output.
+
+
+ - This output is rarely an issue, and may be what is wanted in some cases, but options for preventing it are being considered.
+
+
+
+## What's new in Risei
+
+Release **1.1.1** of Risei (January, 2024) fixes two problems:
+- Classes were sometimes displayed in output as their entire definition, instead of just the class name.
+- All `Date` instances were considered equal, regardless of their actual value.
+
+Development of Risei is ongoing, including internal improvements, problem fixes, and additional options for testing.
 
-When something is wrong in one test file, other test files still usually load and run, so a good sign that there's a problem is a sudden decrease in the number of run tests reported.
 
 
 
@@ -668,11 +522,12 @@ Risei is written by myself, Ed Fallin.&nbsp;  I'm a longtime software developer
 
 If you find Risei useful, consider spreading the word to other devs, making a donation, suggesting enhancements, or proposing sponsorships.
 
-You can get in touch about Risei at **Riseimaker@gmail.com**.
+You can get in touch about Risei at **riseimaker@gmail.com**.
+
 
 
 
-## What the Risei license is
+## Risei license
 
 Risei is published for use under the terms of the MIT license: