risei 2.0.0 → 2.0.1

package/README.md

@@ -1,76 +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 in no time for object-oriented (or object-hosted) JavaScript and TypeScript.
-* Refactor or replace existing designs without worrying about about a heavy cost in past or future test construction.
-* Create tests with immediate confidence, since you can't introduce mistakes when writing test code.
+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.
 
-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)
 
+- Outputs are always listed, even on passing tests, which makes code usage much clearer.
 - Any failing tests appear in light red.
 - 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:
+Test runs have a title bar so the starting point is easy to find:
 
-![https://deusware.com/Title-example.png](https://deusware.com/Title-example.png)
+![https://deusware.com/risei/images/Title-example.png](https://deusware.com/risei/images/Title-example.png)
 
 
-As well as a summary bar at the bottom:
+And they have a summary bar at the bottom:
 
-![https://deusware.com/Summary-example.png](https://deusware.com/Summary-example.png)
+![https://deusware.com/risei/images/Summary-example.png](https://deusware.com/risei/images/Summary-example.png)
 
+- This bar is red when any tests fail, much as you'd expect.
 
 
 
-## Using Risei
+## Status
 
-Risei is under active development.   The newest release, **2.0.0**, brings many major improvements:
+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.
 
-- You can now test properties just like methods.
-- You can now spoof properties on the targeted class instance.
-- Risei now can determine automatically if tested or spoofed methods and properties are static.
-- You can now perform arbitrary operations if needed.
-- You can now change a test property without accidentally creating a new test.
-- `Error` objects are now compared accurately.
-- Outputs for `throw` tests are now the entire `Error` objects (breaking change).
+Check out the [full list of changes](#version-history).
 
-Risei has been reengineered internally along with these improvements.
 
-- In addition, `ATestSource` is now a default export (breaking change).
-  - This means a simple adjustment from `import { ATestSource }` to `import ATestSource`.
 
-These changes and others are detailed at the new external Risei documentation website:
+## Features of Risei
 
-&cruft, new site
-[https://deusware.com/risei-docs/index.html](https://deusware.com/risei-docs/index.html)
+- #### 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)
 
-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).
+- And more!   Check out the full [Risei home page](https://deusware.com/risei).
 
-Risei works with Typescript, requiring only a few additional or different steps, described in [using Typescript with Risei](#using-typescript-with-risei).
 
-
-
-
-### Installation
+## Installation
 
 Install Risei for development time only:
 
@@ -78,7 +75,7 @@ Install Risei for development time only:
 npm install --save-dev risei
 ```
 
-Make sure your `package.json` specifies that ECMAScript modules are in use:
+Ensure that `package.json` specifies ECMAScript modules:
 
 ```json
 "type": "module"
@@ -92,26 +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.
-
-&cruft, new site / section
-- Further general options can be found [here](https://deusware.com/risei-docs/index.html#installation).
-
-&cruft, new site / section
-- Further Typescript details can be found [here](https://deusware.com/risei-docs/index.html#using-typescript).
 
 
+## Running Tests
 
-
-### Running tests
-
-Once you've written your tests, run them 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": {
@@ -125,253 +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.
-
-&cruft, new site / section
-- Find more information about this mixed testing and other config / run options [here](https://deusware.com/risei-docs/index.html#running-tests).
-
 
 
+## Writing Tests
 
-### Siting tests
-
-Add tests in files ending in `.rt.js` like this:
+You write tests in `.rt.js` files like this:
 
 ```javascript
 import ATestSource from "risei/ATestSource";
-import { ClassToBeTested } from "somewhere";
+import ClassToTest from "ClassToTest.js";
 
 export class SomeTests extends ATestSource {
-    tests = [ ... ];  // Test definitions are added here.
+    tests = [ ... ];
 }
 ```
 
-
-
-### Writing tests
-
-Write tests with Risei's simple syntax:
+Write individual tests as plain JavaScript objects with Risei's simple syntax:
 
 ```javascript
 tests = [ ...
-    { on: ContainerModelClass, with: [ "a", "b", "c" ],  // Target class and constructor args.
-      of: "doesContain",                                 // Target method name.
-      for: "When the arg is present, returns true.",     // Description of test.
-      in: [ "c" ],                                       // Inputs to method.
-      out: true },                                       // Expected output.
-...];
+    { 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.
+... ];
 ```
 
-- To test a throw path in a method, add an `.and` test property with the text value `"throws"`.
-
-- To test a property of the target instance after running code, add a `.from` property with the property's name as a string.
-
-- To test a value derived from the initial actual value, or otherwise from any available context, add a `from` property that's an arrow function taking (at present) `target` and `test` parameters:  `(target, test) => { return test.actual.someProperty; }`.
-
-- To perform operations like creating files temporarily, use the `.do` property (encompassing two stages, `.before` and `.after`) to set up isolated test state, and `.undo` to restore normal state.
-  - The `.do`-`.before` steps are taken before the target class instance is created, the `.do`-`.after steps are taken after that but before the target method / property is run.
-  - The `.undo` is an arrow function taking a `test` arg.   It is run after all other steps of the test have been run.   **(2.0.0)**
-
-  - To maintain the benefits of using Risei's declarative style, avoid arbitrary options as much as possible.
+- 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.
 
-- If you prefer test property names that aren't JavaScript keywords, alternatives are available for all of them.
 
-- Further details about syntax options can be found [here](https://deusware.com/risei-docs/index.html#test-syntax).
 
+## Basic collapsing forward example
 
+You can state test properties once and let them _collapse forward_ across subsequent tests to save time and make tests easier to read.
 
-
-#### Write more tests with less syntax:
-
-To save a lot of time, state repeated test values just once, and let them _collapse forward_ into following tests:
+Risei collapses values together from partial or full test objects until it has a full test to run.   Every property collapses forward until it is changed or wiped out:
 
 ```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 }
-```
-
-- When you change the class in `.on`, all test properties are wiped away, and when you change the method in `.of`, only test properties about the class (like `.with`) are retained.
-
-- Tests remain isolated, in effect, except when a test mutates input arguments.   In that case, restate them in each test so the mutations aren't carried forward.
-
-- Change test contents without possibly adding an unintended new test by adding a `.just` property (with any value, such as `true`) alongside the changed properties.   **(2.0.0)**
-
-&cruft, new site / details
-- Further options and details can be found [here](https://deusware.com/risei-docs/index.html#collapsing-forward).
-
-
+{ on: ContainerClass, with: [ "a", "b", "c" ] },                     // Following tests are of this class.
 
+{ 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.
 
-#### Ensure desired inputs from dependencies
+{ of: "countOf" },                                                   // Change of tested method.  Method-related props are wiped out.
+...
 
-To make code dependencies return what your tests need, just _spoof_ what you want using a `.plus` test property:
-
-```javascript
-        { on: CombinerClass, with: [], 
-          of: "combineResults",
-          plus: [ 
-            { on: ClassA, of: "someMethod", as: 10 },  // Spoofing one method to return 10.
-            { on: ClassB, of: "someMethod" },          // Spoofing one method not to return anything.
-            { on: ClassC, as: [                        // Spoofing two class methods together. 
-                { of: "firstMethod", as: 11 }, 
-                { of: "secondMethod", as: 12 } 
-              ] },
-          ],
-          for: "When called, returns an array of values from sources.",
-          in: [ "green" ], out: [ 7, 8, 9, 10, 10, 11, 12, { color: "green" } ] }
+{ on: SortingClass, with: [ ] },                                     // Change of tested class.  All existing props are wiped out.
 ```
 
-- It's just like _fakes_, _mocks_, or _test doubles_ in other test systems, but easier to write and read.
-
-&cruft, site / section
-- There are many further spoofing options that save effort, including using nonce methods as spoofs and spoofing target-instance properties.   **(2.0.0)**   Check out all your options [here](https://deusware.com/risei-docs/index.html#collapsing-forward).
-
-
-- Spoofed code is fully isolated within tests, even though spoof definitions collapse forward across tests (and within `.plus`).
-
-
-
+- There are more options available, and an exclusion for mutated args.
+- Learn all the details [here](https://deusware.com/risei/index.html#collapsing-forward).
 
-## Using TypeScript with Risei
 
-Testing TypeScript code with Risei basically just means transpiling before running the tests, and pointing Risei to the transpiled JS files.
 
-- Anything beyond those basics is intended to keep JS files separate from TS files and the output of web frameworks' own, complex build processes.
+## Basic spoofing example
 
-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.
+You can use declarative _spoofing_ syntax to define what dependencies of your targeted code return for it to use.
 
+The most basic spoofing looks like this:
 
-
-### 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"
+```javascript
+{ 
+  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.
+    ],
+  ... 
 }
 ```
 
-- 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`.
+- 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).
 
-> You can run Risei manually with the same sequence of operations.
 
 
+## TypeScript with Risei
 
-### In `tsconfig.json`:
+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.
 
-You set up the transpiler to output files to a directory with these settings:
+- Learn all about it [here](https://deusware.com/risei/index.html#typescript-with-risei).
 
-```json
-{
-  "outDir": "dist/out-tsc",
-  "noEmit": false
-}
-```
 
-- The `outDir` can be any location.   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.
 
+## Troubleshooting
 
+If problems cause test files not to load, a gold bar appears and tests in those files disappear from output:
 
-### In test files:
+![https://deusware.com/risei/images/Gold-bar-example.png](https://deusware.com/risei/images/Gold-bar-example.png)
 
-All `import` statements have to point to the Javascript (`.js`) files in the `outDir` path or subfolders there, using relative-path syntax:
+- Those and other problems can be solved with the help of this [troubleshooting guide](https://deusware.com/risei/index.html#troubleshooting).
 
-```javascript
-import { TestedClass } from "../../dist/out-tsc/SubPath/TestedClass.js";
-```
 
-- Output files may be in a folder tree parallel to the originals (Angular), or may all be in the `outDir` folder itself (React).
+## 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)**   The actual for throw tests is now the entire thrown object (usually an `Error`), rather than the `Error`'s message text.
+  - **(Breaking change)**   `ATestSource` is now a default export, changing its imports from `import { ATestSource } from` to `import ATestSource from`.
 
+> Risei has been massively re-engineered internally along with these improvements.
 
 
-## What's new in Risei
 
-- Release **2.0.0** (month, 2024) introduces many [improvements](#using-risei), including new capabilities, bug fixes, and two breaking changes with only minor impacts on consuming code.
+<details>
+<summary>
+Older releases
+</summary>
 
+- 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 not listed here, and old releases are dropped progressively over time.&nbsp;  Using the latest release is recommended.
-
-
-
-
-## Troubleshooting
-
-Problems loading tests are almost always a missing or extra comma, brace, or similar.&nbsp;  When a test file can't be loaded, loading continues with the next file.&nbsp;  The number of tests drops (or doesn't increase as expected), and a gold bar appears naming the file and problem:
-
-![https://deusware.com/Gold-bar-example.png](https://deusware.com/Gold-bar-example.png)
-
-- Unfortunately, there is no way to list the problem line number.
-- A sudden fail of many test files is usually due to a problem in the tested code, not the tests themselves.
-
-Problems with test results themselves are usually due to omissions or other mistakes in test definitions.
-
-For far more information about troubleshooting, including some specific error messages, check out the documentation [here](https://deusware.com/risei-docs/index.html#troubleshooting).
-
+> The oldest releases are no longer listed here, and old releases are dropped progressively over time.&nbsp;  Using the latest release is recommended.
 
+</details>
 
 
 ## Known issues and workarounds
 
-At present, there are two known issues, both with simple workarounds:
-
-- When tested code mutates its args, the mutated forms are used in subsequent tests if collapsed forward.
-  - To avoid this, simply restate the args for each test that mutates them.
+The only issue at present is reuse of method args mutated by tested code when collapsing forward. 
 
+- The workaround is just to restate those args for each test.
 
-- When a few properties are changed in separate objects, they are treated as whole new tests, which usually fail because of their unintended mix of old and new properties.
-  - To avoid this problem, just add a `.just` or `.only` property, of any value, in the same objects as those tests.change properties as part of whole new tests, or else restate `.of` along with the changed properties.
-  - You can also clear existing properties with `.on` or `.of` and then do this, since then there aren't enough test properties present yet to comprise a full test.
 
+## 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.
 
-## Limitations in Risei
+- 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.
 
-The following are not supported at present:
-- Use of `async` syntax
-- Code written in ESM `export` modules, but not within classes
-- Standalone functions and other functionality not built into classes, AKA _loose code_
-- CJS syntax using `require()`
-- Debugging model code during tests
-- Comparing rare JS object types like `Proxy` or `ArrayBuffer` in test assertions
 
-Some of these are on the tentative future-development list.
-- In the meantime, Risei can be used to save development time for most of your JavaScript code, while these cases can be tested using another framework invoked alongside Risei.
 
-
-
-
-## 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.
 
@@ -381,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:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "risei",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Risei allows you to write unit tests as simple JavaScript objects, so it's easy and fast, with no drag on redesign.",
   "keywords": [
     "unit test",