risei 1.3.4 → 2.0.1

package/README.md

@@ -1,51 +1,73 @@
 
-# Risei
+# Risei Read-Me
 
-## What Risei is
+## Overview
 
-**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 is a new way to write unit tests that's easier and faster, more dependable, and keeps your tests from standing in the way of redesigns.
 
+Risei does all this by replacing hand-coded tests with simple declarative syntax.
 
+- Risei has many convenient and time-saving [features](#features-of-risei).
+- Risei works with object-oriented JavaScript in modules.
+- Risei works with TypeScript after just a few [tweaks](https://deusware.com/risei/index.html#typescript-with-risei).
 
+You can find a longer version of this read-me at [https://deusware.com/risei](https://deusware.com/risei/index.html).   It expands greatly on the information here.
 
-## 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 using the inputs from `.in` and the expected output from `.out`: 
+## Examples
 
-![https://deusware.com/Syntax-example.png](https://deusware.com/Syntax-example.png)
+Here are two example tests, in which `SortModel.countSort()` is being tested using the inputs from `.in` and the expected output from `.out`: 
 
+![https://deusware.com/risei/images/Syntax-example.png](https://deusware.com/risei/images/Syntax-example.png)
 
-Here is the terminal output of these two example tests.   Tests are grouped by class and method.   Inputs, expected, and actual values are displayed for all tests, to make intended usage obvious at a glance:
 
-![https://deusware.com/Output-example.png](https://deusware.com/Output-example.png)
+Here are the example test results for those two tests:
 
+![https://deusware.com/risei/images/Output-example.png](https://deusware.com/risei/images/Output-example.png)
 
-- An individual test may appear on one line or multiple lines, depending on how wide the terminal window is.
+- Outputs are always listed, even on passing tests, which makes code usage much clearer.
 - Any failing tests appear in light red.
-- Your latest-edited tests always sort to the bottom, so you can see your current test results at a glance.
+- Your latest tests always sort to the bottom so it's easy to find their results.
 
 
-Test runs also feature a title bar at the top, as well as a summary bar at the bottom:
+Test runs have a title bar so the starting point is easy to find:
 
-![https://deusware.com/Summary-example.png](https://deusware.com/Summary-example.png)
+![https://deusware.com/risei/images/Title-example.png](https://deusware.com/risei/images/Title-example.png)
 
 
+And they have a summary bar at the bottom:
 
+![https://deusware.com/risei/images/Summary-example.png](https://deusware.com/risei/images/Summary-example.png)
 
-## Using Risei
+- This bar is red when any tests fail, much as you'd expect.
 
-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).
 
-There are a few additional or different steps for [using Typescript with Risei](#using-typescript-with-risei).
 
+## Status
 
+Risei is under active development and new enhancements appear often.   The latest release, **2.0.1**, brings many major improvements, including broader capabilities and simpler syntax, and a few minor breaking changes.
 
-### Installation
+Check out the [full list of changes](#version-history).
+
+
+
+## Features of Risei
+
+- #### Declarative syntax to write tests simply and quickly.      ►   [Writing tests](https://deusware.com/risei/index.html#writing-tests)   (basics below)
+- #### Easy-to-read test definitions and test outputs.    ►  [Test and output examples](https://deusware.com/risei/index.html#examples)   (also above)
+- #### Even less to write by stating reused test properties only once.      ►   [Collapsing forward](https://deusware.com/risei/index.html#collapsing-forward)   (basics below)
+- #### Built-in declarative syntax to fake test-time values from dependencies.      ►   [Spoofing using `.plus`](https://deusware.com/risei/index.html#spoofing)   (basics below)
+- #### Testing properties, methods, static and instance members all the same way.      ►   [Properties and statics](https://deusware.com/risei/index.html#testing-properties-and-static-methods)
+- #### Testing `throw` paths effortlessly.      ►   [Using `.and: "throws"`](https://deusware.com/risei/index.html#using-and-throws)
+- #### Deriving actual values to test from raw outputs or property retrieval.      ►   [Using `.from`](https://deusware.com/risei/index.html#using-from)
+- #### Setting up and tearing down arbitrary test state.      ►   [Using `.do` and `.undo`](https://deusware.com/risei/index.html#using-do-and-undo)
+- #### Testing for `undefined` as output.      ►   [Using `this.undef`](https://deusware.com/risei/index.html#using-undef)
+
+- And more!   Check out the full [Risei home page](https://deusware.com/risei).
+
+
+## Installation
 
 Install Risei for development time only:
 
@@ -53,7 +75,7 @@ Install Risei for development time only:
 npm install --save-dev risei
 ```
 
-Make sure your `package.json` specifies that ESM is in use:
+Ensure that `package.json` specifies ECMAScript modules:
 
 ```json
 "type": "module"
@@ -67,105 +89,17 @@ 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:
+## Running Tests
 
-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 `[]`.
-
-- Tests are isolated in general, but if the code you're testing mutates its arguments, you have to state them in each test so the mutations aren't carried forward.
-
-
-
-#### Spoof away code dependencies:
-
-When your tests need certain results from code dependencies, just _spoof_ what you want using a `.plus` test property:
-
-```javascript
-        { on: CombinerClass, with: [], 
-          of: "combineResults",
-          plus: [ 
-            { on: ClassA, of: "someMethod", as: 10 },    // Spoof this ClassA method to return 10.
-            { on: ClassB, of: "someMethod" },            // Spoof this ClassB method not to return (or do) anything.
-            { of: "firstMethod", as: [ 7, 8, 9, 10 ] },  // Spoof a method on the tested class (CombinerClass).
-            { of: "secondMethod" },                      // Spoof a method on CombinerClass not to do anything.
-            { on: ClassC,                                // Spoof this ClassC method to be this nonce code.
-              of: "someMethod", 
-              as: (arg) => { return { color: arg }; } },  
-            { on: ClassD, as: [                          // Spoof two methods on ClassD at the same time.
-                { of: "firstMethod", as: 11 }, 
-                { of: "secondMethod", as: 12 } 
-              ] },
-          ],
-          for: "When called, returns an array of values from sources.",
-          in: [ "green" ], out: [ 7, 8, 9, 10, 10, 11, 12, { color: "green" } ] }
-```
-
-- It's just like _fakes_, _mocks_, or _test doubles_ in other test systems, but much easier to write and read.
-
-- Spoofed code is fully isolated within tests, even though spoof definitions collapse forward across tests (and within `.plus`).
-
-
-
-### Running tests
-
-Run your tests by invoking Risei's `index.js` file:
+Once you have some tests written, you can run them manually:
 
 ```bash
 node ./node_modules/risei/index.js
 ```
 
-Or write a `package.json` script that does the same:
+Or write a script in `package.json` that does the same:
 
 ```json
 "scripts": {
@@ -179,438 +113,158 @@ 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.
-
-
-
-### Learning more about Risei
-
-Read through the rest of this doc to learn more about Risei's many capabilities, and about where Risei is headed.
-
-- For instance, learn about using `.and` to test static methods or throws.
-- Or learn about using `.from` to test property results or other state.
-- Don't miss out:  Once you've tried the basics, read the rest...!
-
-
-
-
-## Risei in depth
-
-<details>
-<summary>
-There's plenty more to learn about Risei and how it makes testing easy...
-</summary>
-
-### Installation
-
-- You can use any file extension you want in Risei's metadata in `package.json`, and Risei will scan those files for tests.
-
-- You can install Risei outside of development time the usual way, but as with any test system, this is definitely not recommended.
-
-- Risei uses ESM syntax, and may not work in older environments where that's not available or is patched in.
-
-
-
-### Siting tests
-
-- Match your Risei test file's extensions to whatever you choose in the metadata in `package.json`.
-
-- Test classes must inherit from `ATestSource` in `"risei/ATestSource"`: this type name is looked for specifically, so duck-typing doesn't work.
-
-
-
-### Writing tests
-
-- The order and placement of test properties doesn't matter, although the order seen in the examples is probably most readable.
-
-
-
-#### Basic test properties and options for each:
-
-| Name   | Contents                                                                                                  |
-|--------|-----------------------------------------------------------------------------------------------------------|
-| `on`   | The class under test, as a symbol / name (already imported into the test file)                            |
-| `with` | An array of any arguments to pass to the constructor of the tested class, or an empty array `[]` if none |
-| `of`   | The name of the method under test, as a string, no `()` needed                                            |
-| `for`  | A description of what the test proves, for test output                                                    |
-| `in`   | An array of the input arguments to pass to the tested method, or an empty array `[]` if none             |
-| `out`  | The expected return value, not in an array                                                                |
-
-- There are additional properties for extended functionality, covered later.
-- The property names were chosen to be easy to remember and type, but longer alternatives are available, covered later.
-
-
-
-### Test-property reuse _AKA_ Collapsing forward
-
-- To save time and effort, any property you write is collapsed forward to subsequent tests unless you replace it or erase it with an empty array `[]`.
-  - Property values are gathered across partial test objects until they add up to a runnable test, which is then run.
-  - Changes to properties are combined with previous ones to produce intended new tests.
-    - For a rare and avoidable side-effect of this system, see [known issues and workarounds](#known-issues-and-workarounds).
-
-- Test contents, reused or not, are automatically reset when it makes the most sense:
-  - Changing the tested class in `.on` wipes out all prior test properties, so the new class has a fresh start.
-  - Changing the tested method in `.of` wipes out only test properties related to methods, to preserve class values you usually want.
-
-- Individual tests remain isolated, except for when args are mutated by the code under test.
-  - Restate args for each test when the code mutates them.
-  - This limitation is the result of limits on what can be copied reliably in JavaScript.
-
-
-### Choosing test-only dependency inputs _AKA_ Spoofing
-
-- Spoofing is Risei's way of providing test-only inputs from dependencies the tested code uses, written in simple declarative syntax.
-  - It's therefore the equivalent of test doubles, mocks, fakes, and so on.
-
-
-- As the earlier examples and this table show, you can spoof in many ways, both on the dependencies, and on the class being tested.
-- All classes whose members are being spoofed have to be imported.
-
-
-
-#### Spoof-definition properties:
-
-| Name | Necessary or Optional | Contents                                                                                                                                                             |
-|------|-----------------------|----------------------------------------------------------------------------|
-| `on` | Optional              | Symbol for a type (class); if omitted, the targeted model class is assumed |
-| `of` | Necessary             | Name of the method to spoof, as a string, trailing `()` not needed         |
-| `as` | Optional              | Value to return or nonce implementation; if omitted, an empty method with no return value is used<br> &mdash; or &mdash;<br>A list of partial spoof definitions for the same class |
-
-
-- You can spoof multiple methods of a class individually, or list them together with partial definitions as seen in the example, with the same effect either way.
-
-
-#### Partial spoof-definition properties:
-
-| Name | Necessary or Optional | Contents                                                                                          |
-|------|-----------------------|---------------------------------------------------------------------------------------------------|
-| `of` | Necessary             | Name of the method to spoof, as a string, trailing `()` not needed                                |                                                                                  
-| `as` | Optional              | Value to return or nonce implementation; if omitted, an empty method with no return value is used |
-
-
-- Defining new spoofing wipes out all old definitions.
-
-
-- Spoofing is done at the start of each test and undone at the end of each test, keeping all tests isolated.
-
-
-
-
-## Advanced Risei usage
 
-### Testing special test conditions with `.and`
 
-You can use the special test property `.and`, always a string, to indicate special conditions that apply to your test.
-- At present, the values available are `"static"` and `"throw"` / `"throws"` (either one works).
-- You can list `static` and `throw` / `throws` together if needed, separated by a space.
+## Writing Tests
 
-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"`:
-
-```javascript
-{ on: StaticTextProfileModel, with: [] },
-
-{ of: "getTextProfile",
-  for: "Returns accurate profile of arg text.",
-  and: "static",
-  in: [ "This is a short sentence." ],
-  out: { isFullSentence: true, characters: 25, words: 5 }
-}
-```
-
-
-
-#### Testing throws
-
-To test a throw, use an `.and` of `"throw"` or `"throws"`:
+You write tests in `.rt.js` files like this:
 
 ```javascript
-{ on: InstanceTextProfileModel, with: [] },
+import ATestSource from "risei/ATestSource";
+import ClassToTest from "ClassToTest.js";
 
-{ 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?"
+export class SomeTests extends ATestSource {
+    tests = [ ... ];
 }
 ```
 
-
-
-### 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:
-
-| 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       |
-
-
-- Getting properties, mutated args, and other non-return values is known as _retrieving_.
-- Retrieving definitions collapse forward across tests unless replaced with new definitions, or erased by setting `.from` to an empty array `[]`.
-
-
-<details>
-<summary>
-&nbsp; More information
-</summary>
-<br>
-
-- Use of `.from` with a property name looks like this: 
+Write individual tests as plain JavaScript objects with Risei's simple syntax:
 
 ```javascript
-{ on: StatefulModel, with: [] },
-
-{ of: "storePolyProduct",
-  for: "The result of the calculation is stored as .result.",
-  in: [ 10, 8, 9, 6 ], out: 4320, from: "result" },
+tests = [ ...
+    { on: ContainerClass, 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.
+... ];
 ```
 
-- 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:
-
-| 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           |
+- Use empty arrays for `.in` or `.with` when there are no args to pass.
+- You can use [long names](https://deusware.com/risei/index.html#long-names) for properties if you want.
 
 
-- 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.
 
+## Basic collapsing forward example
 
-- 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.
+You can state test properties once and let them _collapse forward_ across subsequent tests to save time and make tests easier to read.
 
-
-- Another usage of a `.from` function is to look at an input to see if it was changed as expected:
+Risei collapses values together from partial or full test objects until it has a full test to run.&nbsp;  Every property collapses forward until it is changed or wiped out:
 
 ```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]; } 
-},
-```
-
-</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>
-
-<details>
-<summary>
-&nbsp; Spoof properties' short and long names
-</summary>
-
-| Short Name | Long Name |
-|------------|-----------|
-| `on`       | `target`  |
-| `of`       | `method`  |
-| `as`       | `output`  |
-
-</details>
-
-
-
-### Further capabilities of Risei
-
-Constructors can be tested with no special test properties or keywords.
-- The method name in `.of` is simply `"constructor"`.
-- Any `.with` args are completely ignored for a constructor test.&nbsp;  Only those in the test's `.in` property are used.
-  - However, a `.with` must still be provided.&nbsp;  It can simply be an empty array `[]`.
-
-</details>
-
-
-
+{ on: ContainerClass, with: [ "a", "b", "c" ] },                     // Following tests are of this class.
 
-## Using TypeScript with Risei
+{ of: "doesContain" },                                               // Following tests are of this method.
+{ for: "Returns true when arg present.", in: [ "c" ], out: true },   // First test: now Risei has enough to run on.
+{ for: "Returns false when arg absent.", in: [ "d" ], out: false },  // Next test: same method, different test case.
 
-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.
+{ of: "countOf" },                                                   // Change of tested method.  Method-related props are wiped out.
+...
 
-- 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.
-- Varying other approaches are also sure to work, depending on the other technical choices in play.
-
-
-
-### In `package.json`:
-
-Add transpilation and deletion operations to the `test` script, with each operation conditional on completion of the preceding one:
-
-```json
-"scripts": {
-  "test": "tsc && node ./node_modules/risei/index.js && rm -r ./dist/out-tsc"
-}
+{ on: SortingClass, with: [ ] },                                     // Change of tested class.  All existing props are wiped out.
 ```
 
-- Generally, you should use `tsc` or another plain transpiler, not web frameworks' complex processes with single output files.
-- Deleting the files at the end prevents interference with web frameworks' bundling.
-- The deletion path must match the `outDir` in `tsconfig.json`.
-
-> You can run Risei manually with the same sequence of operations.
+- There are more options available, and an exclusion for mutated args.
+- Learn all the details [here](https://deusware.com/risei/index.html#collapsing-forward).
 
 
 
-### In `tsconfig.json`:
+## Basic spoofing example
 
-You set up the transpiler to output files to a directory with these settings:
+You can use declarative _spoofing_ syntax to define what dependencies of your targeted code return for it to use.
 
-```json
-{
-  "outDir": "dist/out-tsc",
-  "noEmit": false
-}
-```
-
-- The `outDir` can be any location.&nbsp;  It's best not to just use `dist`, where adding or deleting files may interfere with web frameworks' build steps.
-- These settings are normally not near each other in the file (as seen here).
-- You can also set the `target` to `es6` or higher, although Risei works fine with ES5.
-
-
-
-
-### 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:
+The most basic spoofing looks like this:
 
 ```javascript
-import { TestedClass } from "../../dist/out-tsc/SubPath/TestedClass.js";
+{ 
+  on: TestedClass,
+  ...
+  plus: [ 
+      { on: Dependency, of: "someMethod", as: 10 },  // Dependency.someMethod() returns 10 in this test.
+      { of: "testedClassMethod", as: 11 }            // TestedClass.testedClassMethod() returns 11 in this test.
+    ],
+  ... 
+}
 ```
 
-- Output files may be in a folder tree parallel to the originals (Angular), or may all be in the `outDir` folder itself (React).
+- Numerous additional capabilities, as well as compressed syntax, can be mixed freely in many ways.
+- Learn more [here](https://deusware.com/risei/index.html#spoofing).
 
 
 
+## TypeScript with Risei
 
-## Limitations in Risei
-
-The following are not supported at present:
-- Use of `async` syntax
-- Code written in ESM `export` modules, but not within classes
-- Standalone functions and other functionality not built into classes, AKA _loose code_
-- CJS syntax using `require()`
-- Spoofing mixes of properties and methods, such as `something.method.property.method`
-- Debugging model code during tests
-- Comparing rare JS object types like `Proxy` or `ArrayBuffer` in test assertions
-
-Some of these are on the tentative future-development list.&nbsp;  In the meantime, Risei can be used to save development time for most of your JavaScript code, while these can be tested using another framework invoked alongside Risei.
+To test TypeScript code with Risei, you make sure the code is transpiled before the tests are run, and you point Risei to the transpiled `.js` files.
 
+- Learn all about it [here](https://deusware.com/risei/index.html#typescript-with-risei).
 
 
 
 ## Troubleshooting
 
-Most problems with using Risei are minor mistakes in syntax, or omissions in test definitions:
-
-| 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 |
+If problems cause test files not to load, a gold bar appears and tests in those files disappear from output:
 
+![https://deusware.com/risei/images/Gold-bar-example.png](https://deusware.com/risei/images/Gold-bar-example.png)
 
+- Those and other problems can be solved with the help of this [troubleshooting guide](https://deusware.com/risei/index.html#troubleshooting).
 
 
-## Known issues and workarounds
-
-Two issues are known to exist:
-
-- When code mutates its args in test definitions, the mutated forms are used in subsequent tests unless those args are restated.
-  - To avoid this problem, just restate the args in each test of this code.
-  - The workaround for this &mdash; copying and initing objects to bypass mutation &mdash; requires too many assumptions to be reliable.
+## Version history
 
+- Release **2.0.1** (August, 2024) contains all of these changes:
+  - Risei now can determine automatically if tested methods are static.
+  - You can now directly test properties just like methods.
+    - Risei can also determine automatically if these are static.
+    - Directly tested properties appear in the output in the form `.name`.
+  - You can now spoof properties on the targeted class instance, and static properties on the target class itself.
+  - You can now perform arbitrary operations, if needed, with the two-part `.do` property and one-part `.undo` property.
+  - You can now change test properties without accidentally creating a new test using `.just`.
+  - You can now directly test for `undefined` in `.out` using `this.undef` / `ATestSource.undefSymbol`.
+  - `Error` objects are now compared accurately.
+  - You can now identify member types with `.`, `:`, and `()` in `.of`, `.plus`, and `.from`, though they aren't necessary.
+  - **(Breaking change)**&nbsp;  The actual for throw tests is now the entire thrown object (usually an `Error`), rather than the `Error`'s message text.
+  - **(Breaking change)**&nbsp;  `ATestSource` is now a default export, changing its imports from `import { ATestSource } from` to `import ATestSource from`.
 
-- When a few properties are changed in separate objects, they are treated as whole new tests, which usually fail because of their unintended mix of old and new properties.
-  - To avoid this problem, just change properties as part of whole new tests, or else restate `.of` along with the changed properties.
-  - Risei is actually working as intended when this happens, but ways to optionally prevent it are being considered.
+> Risei has been massively re-engineered internally along with these improvements.
 
 
 
-## What's new in Risei
-
-- Release **1.3.4** (March, 2024) fixes a bug that caused class definitions still to appear instead of class names when classes were used as object properties.
-  - As a side effect of this change, objects' own `toString()` is never used in onscreen test output any longer, but all of Risei's output display is now handled the same.
-
-
-- Release **1.3.3** (March, 2024) fixes a major bug related to file paths that prevented any tests from loading or running in Windows environments.
-  - Risei is now fully usable in Windows environments again.
-
+<details>
+<summary>
+Older releases
+</summary>
 
-- Release **1.3.2** (February, 2024) does not change the code at all, but improves this read-me.
-  - It now explains the easiest way to deal with mutable args (which is just restating the args).
-  - A few mistakes in the text were also fixed.
+- Release **2.0.0** (August, 2024) is identical to 2.0.1 except for some unneeded extra files.
+- 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.
+- Release **1.3.0** (February, 2024) added the loading-error gold bar and fixed a test-sorting bug.
+- Release **1.2.0** (January, 2024) changed test sorting to move last-edited tests to the end.
+- Release **1.1.2** of Risei (January, 2024) fixed class displays and inaccurate `Date` comparisons.
 
+> The oldest releases are no longer listed here, and old releases are dropped progressively over time.&nbsp;  Using the latest release is recommended.
 
-- Release **1.3.1** (February, 2024) reverses some changes in 1.3.0 that were intended to fully isolate tests against mutable args, but which caused incomplete or inaccurate object contents in some cases.
-  - Supporting built-in total test isolation is not feasible with collapsing forward, nor is it usually necessary given easy usage alternatives.
-  - In contrast, collapsing forward is both highly beneficial and frequently used.
+</details>
 
 
-- Release **1.3.0** (February, 2024) makes two changes:
-  - If there are any test-loading errors, their messages now appear in a new gold bar that appears below the summary of the test run.
-  - A test-sorting error has also been fixed that occurred when no test files existed yet. 
+## Known issues and workarounds
 
+The only issue at present is reuse of method args mutated by tested code when collapsing forward. 
 
-- Release **1.2.0** (January, 2024) changes sorting of test files to make tests you're working on now appear at the bottom.
-  - Previously tests were displayed in the order found, which is always alphabetical (though is not guaranteed to be so).
-  - The order for all files except one remains the same.
-  - The last-edited file is moved to the bottom, making it easy to see the latest test results.
+- The workaround is just to restate those args for each test.
 
 
-- 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.
+## Exclusions from Risei
 
+At present, there are a few things Risei doesn't support, such as `async` syntax.&nbsp;  Some of these may be supported in the future.
 
-- Don't use release **1.1.1**, which contains an internal path error.
+- You can see the whole list [here](https://deusware.com/risei/index.html#exclusions-from-risei).
+- You can save a lot of time by using Risei for most of your code, and another framework for whatever it doesn't support.
 
 
 
-## Who makes Risei
+## Maker
 
 Risei is written by myself, Ed Fallin.&nbsp;  I'm a longtime software developer who likes to find better ways to do things.
 
@@ -620,8 +274,7 @@ You can get in touch about Risei at **riseimaker@gmail.com**.
 
 
 
-
-## Risei license
+## License
 
 Risei is published for use under the terms of the MIT license:
 
@@ -638,3 +291,5 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
 
 
 &nbsp;
+
+