risei 1.0.4 → 1.1.1

package/README.md

@@ -1,76 +1,62 @@
 
-# RiseiJs
+# Risei
 
-## What RiseiJs is
+## What Risei is
 
-**RiseiJs is a new way to write unit tests that allows you to:**
+**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 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.
 
-RiseiJs' `npm`-friendly name is **Risei**.   The package is often referred to as **Rjs** 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).
 
-### Basics of the RiseiJs approach
+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.
 
-RiseiJs 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`: 
 
-<div style="padding-left: 1.5rem">
+
+## 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.&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 use RiseiJs
 
-1. Install RiseiJs the usual way for a development-time `npm` package, using its `npm`-friendly name `risei`:
+## Using Risei
+
+### Installation
 
-<div style="padding-left: 1.5rem;">
+Install Risei for development time only:
 
 ```bash
 npm install --save-dev risei
 ```
 
-</div>
+Make sure your `package.json` specifies that ESM is in use:
 
-<details>
-<summary>
-&nbsp; More information
-</summary>
-<br>
-
-- RiseiJs 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 Rjs is not guaranteed to work with older versions.
-- You can install Rjs 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.
-  - RiseiJs 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>
-
-
-
-2. Add a `risei` node to your project's `package.json` to tell Rjs 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": {
@@ -78,368 +64,246 @@ 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>
-
-
 
-3. 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
 
-
-
-4. 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`.
-  - RiseiJs 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>
-
 
 
-5. Write each test as a JavaScript object literal in the array, using RiseiJs' simple, light syntax: 
+### Writing tests
 
-<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>
 
+#### Write more tests with less syntax:
 
-
-6. 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:
-
-<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>
+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 `[ ]`.  
 
-<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>
+#### Spoof away code dependencies:
 
-
-
-7. 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:
-
-<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.
+These are basically all varieties of spoofing.&nbsp;  Spoofing collapses forward across tests, but not across the elements within `.plus`. 
 
-</div>
 
-<details>
-<summary>
-&nbsp; Spoofing syntax and options
-</summary>
-<br>
 
-- Each object in `.plus` consists of the following:
+### Running tests
 
-<div style="padding-left: 1.5rem;">
+Run your tests by invoking Risei's `index.js` file:
 
-| 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 |
+```bash
+node ./node_modules/risei/index.js
+```
 
-</div>
+Or write a `package.json` script that does the same:
 
-- 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`.
+```json
+"scripts": {
+  ...
+  "test": "node ./node_modules/risei/index.js",
+  ...
+}
+```
 
+And then run that script:
 
-- This example uses all three syntax options:
+```bash
+npm test
+```
 
-<div style="padding-left: 1.5rem;">
+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.
 
-```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" } ] }
-```
 
-</div>
 
-- You can spoof methods nested inside of other objects  using `.` syntax in the `.of` property:
+### Learning more about Risei
 
-<div style="padding-left: 1.5rem;">
+Be sure to read through the rest of this doc to learn more about Risei's many capabilities, and about where Risei is headed.
 
-```javascript
-          plus: [
-            { on: SimpleObject, of: "getText", as: "Text" }, 
-            { on: DeepObject, of: "root.branch.leaf.getOptimum", as: 100 }
-          ]
-```
+- 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...!
 
-</div>
 
-- 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).
 
-<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:
+## Risei in depth
 
-<div style="padding-left: 1.5rem;">
+### Installation
 
-```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 ] } ]
-            }
-          ]
-```
+- You can use any file extension you want in Risei's metadata in `package.json`, and Risei will scan those files for tests.
 
-</div>
+- You can install Risei outside of development time the usual way, but as with any test system, this is definitely not recommended.
 
-- 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.
+- Risei uses ESM syntax, and may not work in older environments where that's not available or is patched in.
 
-</details>
 
-</details>
 
+### Siting tests
 
+- Match your Risei test file's extensions to whatever you choose in the metadata in `package.json`.
 
-8. Run your tests by invoking RiseiJs' `index.js` file:
+- Test classes must inherit from `ATestSource` in `"risei/ATestSource"`: this type name is looked for specifically, so duck-typing doesn't work.
 
-<div style="padding-left: 1.5rem;">
 
-```bash
-node ./node_modules/risei/index.js
-```
 
-</div>
+### Writing tests
 
-<details>
-<summary>
-&nbsp; More information
-</summary>
-<br>
+- 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.
 
-- At present, Rjs 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.
 
 </details>
 
 
+### Test-property reuse _AKA_ Collapsing forward
 
-9. Or write the `test` script in `package.json` to invoke `index.js`, to make your life easier:
+- 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).
 
-<div style="padding-left: 1.5rem;">
+- 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.
 
-```json
-"scripts": {
-  "test": "node ./node_modules/risei/index.js"
-}
-```
-</div>
 
-<details>
-<summary>
-&nbsp; More options
-</summary>
-<br>
+- 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.
 
-- You can instead write a unique script for Rjs, though this takes more syntax to call later:
 
-<div style="padding-left: 1.5rem;">
+### Choosing test-only dependency inputs _AKA_ Spoofing
 
-```json
-"scripts": {
-  "risei": "node ./node_modules/risei/index.js"
-}
-```
+- 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.
 
-</div>
 
-- You can define your test scripting to include the RiseiJs tests alongside other tests if you wish to mix framework usages, which may be appropriate for some scenarios:
+- 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.
 
-<div style="padding-left: 1.5rem;">
 
-```json
-"risei": "node ./node_modules/risei/index.js"
-"test": "mocha **/* && risei" 
-```
+#### Spoof-definition properties:
 
-</div>
+| 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 |
 
-- Of course, if you are used to Linux / Unix scripting, you may also find other techniques to make running tests easier.
 
-</details>
+- 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:
 
-7. Run that script whenever you want to run tests:
+| 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 test
-```
+- Defining new spoofing wipes out all old definitions.
 
-</div>
 
-<details>
-<summary>
-&nbsp; More options
-</summary>
-<br>
+- Spoofing is done at the start of each test and undone at the end of each test, keeping all tests isolated.
 
-- Or run a custom script with longer syntax like this:
 
-<div style="padding-left: 1.5rem;">
 
-```bash
-npm run risei
-```
 
-</div>
+## Advanced Risei usage
 
-</details>
+### 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).
 
-## Advanced RiseiJs usage
 
-### Testing static methods
 
-To test a static method, you add an `.and` property to a test, with the value `"static"`:
+#### Testing static methods
 
-<div style="padding-left: 1.5rem">
+To test a static method, use an `.and` of `"static"`:
 
 ```javascript
-{ on: StaticModel, with: [] },
+{ on: StaticTextProfileModel, with: [] },
 
 { of: "getTextProfile",
   for: "Returns accurate profile of arg text.",
@@ -449,31 +313,34 @@ To test a static method, you add an `.and` property to a test, with the value `"
 }
 ```
 
-</div>
 
-<details>
-<summary>
-&nbsp; More information
-</summary>
-<br>
 
-- The `.and` property is an expansion point for supporting more unusual situations in the future.&nbsp;  At present, it only supports static operations.
+#### Testing throws
+
+To test a throw, use an `.and` of `"throw"` or `"throws"`:
+
+```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?"
+}
+```
 
-</details>
 
 
 ### 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 `[ ]`.
@@ -487,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: [] },
 
@@ -497,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). 
@@ -522,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: [] },
 
@@ -535,11 +393,10 @@ When the contents of `.from` are a function, these are the two parameters:
 },
 ```
 
-</div>
-
 </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.
@@ -552,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`    |
@@ -566,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>
@@ -577,20 +430,17 @@ 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>
 
 
-### Further capabilities of RiseiJs
+
+### Further capabilities of Risei
 
 Constructors can be tested with no special test properties or keywords.
 - The method name in `.of` is simply `"constructor"`.
@@ -598,45 +448,92 @@ Constructors can be tested with no special test properties or keywords.
   - However, a `.with` must still be provided.&nbsp;  It can simply be an empty array `[ ]`.
 
 
-### Limitations in RiseiJs
+
+### 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.
+- 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.
+
+
+
 
 ## Troubleshooting
 
-Most problems with using RiseiJs are minor mistakes in syntax, or omissions in test definitions:
+Most problems with using Risei are minor mistakes in syntax, or omissions in test definitions:
+
+| 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.
+
+
 
-| 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 `[ ]` 
 
-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.
+## Who makes Risei
 
+Risei is written by myself, Ed Fallin.&nbsp;  I'm a longtime software developer who likes to find better ways to do things.
 
-## Who makes RiseiJs
+If you find Risei useful, consider spreading the word to other devs, making a donation, suggesting enhancements, or proposing sponsorships.
 
-RiseiJs is written by myself, Ed Fallin.&nbsp;  I'm a longtime software developer who likes to find better ways to do things.
+You can get in touch about Risei at **riseimaker@gmail.com**.
 
-If you find RiseiJs useful, consider spreading the word to other devs, making a donation, suggesting enhancements, or proposing sponsorships.
 
-You can get in touch about RiseiJs at **riseijsmaker@gmail.com**.
 
 
-## What the RiseiJs license is
+## Risei license
 
-RiseiJs is published for use under the terms of the MIT license:
+Risei is published for use under the terms of the MIT license:
 
 <div style="border: solid darkgray 1px; padding: 0.5rem;">
 
-<b>RiseiJs Copyright &copy; 2023 Ed Fallin</b>
+<b>Risei Copyright &copy; 2023 Ed Fallin</b>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: