risei 1.0.1 → 1.0.3

package/README.md

@@ -22,7 +22,7 @@ Here are two example tests.   `SortModel.countSort()` is being tested with
 
 </div>
 
-Here is the terminal output of these two example tests.&nbsp;  Tests are grouped by class and method.&nbsp;  Both expected and actual values are displayed for all tests, to make intended usage obvious at a glance:
+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;">
 
@@ -30,9 +30,9 @@ Here is the terminal output of these two example tests.&nbsp;  Tests are grouped
 
 </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 a light red.&nbsp;
+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, plus a summary bar at the bottom:
+Test runs also feature a title bar, as well as a summary bar at the bottom:
 
 <div style="padding-left: 1.5rem;">
 
@@ -59,10 +59,10 @@ npm install --save-dev risei
 </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
+- 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 they can for other test frameworks).
+- 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>
 
@@ -86,8 +86,8 @@ npm install --save-dev risei
 </summary>
 <br>
 
-- If you prefer another extension for your unit-test files, you can use it instead here.
-- As mentioned earlier, be sure to choose a unique extension for test files.
+- 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>
 
@@ -101,8 +101,7 @@ npm install --save-dev risei
 </summary>
 <br>
 
-- The extension `.rt.js` is standard, but you can actually use any extension you want, as long as you provide the same extension in the RiseiJs-specific node in `package.json` (covered earlier).
-- Whether you use the standard extension or not, use a unique one to avoid scanning all of your files for tests at each test run.
+- If you chose another extension for your unit-test files (covered earlier), use that instead here.
 
 </details>
 
@@ -129,16 +128,16 @@ export TargetClassTests extends ATestSource {
 </summary>
 <br>
 
-- Files of tests must be subclasses of `ATestSource`.
+- 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 under test in the matching test class.
+- 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 with RiseiJs' simple, light syntax: 
+5. Write each test as a JavaScript object literal in the array, using RiseiJs' simple, light syntax: 
 
 <div style="padding-left: 1.5rem;">
 
@@ -165,7 +164,7 @@ export TargetClassTests extends ATestSource {
 |--------|--------------------------------------------------------------------------|
 | `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 `()` used             |
+| `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                               |
@@ -176,8 +175,7 @@ export TargetClassTests extends ATestSource {
 - 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.&nbsp;  Some of them overlap with JavaScript keywords, but this causes no harm.
-- There are different, long names available to use for each property if wanted (covered later).&nbsp;  None of them are JavaScript keywords.
+- The property names were chosen to be easy to remember and type, but longer alternatives are available (covered later).
 
 </div>
 
@@ -185,7 +183,7 @@ export TargetClassTests extends ATestSource {
 
 
 
-6. Write more tests with less syntax by defining parts of what is used in upcoming tests and/or repeating only the properties that are different from the previous test/s:
+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;">
 
@@ -212,17 +210,18 @@ export TargetClassTests extends ATestSource {
 </summary>
 <br>
 
-- 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 change individual test properties such as `.with` whenever you want, but by design, they don't revert in the next test.
-- This simplification tactic, called _collapsing forward_, saves a lot of typing and reading.
+- 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>
 
 
 
-7. To isolate any tests with dependencies, spoof the methods depended on, in any objects, with the `.plus` property:
+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;">
 
@@ -261,11 +260,11 @@ export TargetClassTests extends ATestSource {
 
 </div>
 
-- You can leave out `.as` when you don't need a return value.&nbsp;  An empty method is used (that is, `() => { }`).
+- 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`.
 
 
-- This example uses both syntax options:
+- This example uses all three syntax options:
 
 <div style="padding-left: 1.5rem;">
 
@@ -283,9 +282,22 @@ export TargetClassTests extends ATestSource {
 
 </div>
 
-- Spoofed types (like `ArraySource` in the example) have to be imported normally.
-- The properties in the spoof objects within `.plus` don't collapse forward within the array, but must be repeated for each one.
-- You can spoof methods of objects in `.with` and `.in` as well, although you usually don't need to.
+- You can spoof methods nested inside of other objects  using `.` syntax in the `.of` property:
+
+<div style="padding-left: 1.5rem;">
+
+```javascript
+          plus: [
+            { on: SimpleObject, of: "getText", as: "Text" }, 
+            { on: DeepObject, of: "root.branch.leaf.getOptimum", as: 100 }
+          ]
+```
+
+</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>
@@ -294,7 +306,7 @@ export TargetClassTests extends ATestSource {
 </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:
+- You can spoof many methods on a class at the same time with an array of partial spoof objects for the `.as` property:
 
 <div style="padding-left: 1.5rem;">
 
@@ -310,21 +322,9 @@ export TargetClassTests extends ATestSource {
 
 </div>
 
-  - As with simple object-method spoof definitions, `.as` can be omitted in the nested partial spoof objects, with the same effect.
-  - You can use this syntax or list multiple full `.on`-`.as`-`.of` objects for a class, with the same effect either way.
-
-  - You can spoof methods and properties nested inside of other objects  using `.` syntax in the `.of` property:
-
-<div style="padding-left: 1.5rem;">
-
-```javascript
-          plus: [
-            { on: SimpleObject, of: "getText", as: "Text" }, 
-            { on: DeepObject, of: "root.branch.leaf.getOptimum", as: 100 }
-          ]
-```
-
-</div>
+- 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.
 
 </details>
 
@@ -383,7 +383,7 @@ node ./node_modules/risei/index.js
 
 </div>
 
-- You can define your test script to include the RiseiJs tests alongside other tests if you wish to mix framework usages, which may be appropriate for some scenarios:
+- 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:
 
 <div style="padding-left: 1.5rem;">
 
@@ -464,7 +464,7 @@ To test a static method, you add an `.and` property to a test, with the value `"
 
 ### Testing object properties and other non-`return` results
 
-To test a value that isn't the exercised code's return value, you add a `.from` property to a test, which can be one of two things:
+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">
 
@@ -473,10 +473,11 @@ To test a value that isn't the exercised code's return value, you add a `.from`
 | 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 `[ ]`.
 
-</div>
 
 <details>
 <summary>
@@ -519,7 +520,7 @@ When the contents of `.from` are a function, these are the two parameters:
 - 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.
 
 
-- Another usage of `.from` function is to look at an input to see if it was changed as expected:
+- 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">
 
@@ -541,7 +542,9 @@ When the contents of `.from` are a function, these are the two parameters:
 
 ### Property long names
 
-Test properties have long names that you can use instead of the short ones if you prefer, mixing together as much as you want.
+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>
@@ -602,25 +605,29 @@ The following are not supported at present:
 - 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.
 
 ## Troubleshooting
 
 Most problems with using RiseiJs are minor mistakes in syntax, or omissions in test definitions:
 
-| Error text                                                                       | Probable cause / fix                                                  |
-|----------------------------------------------------------------------------------|-----------------------------------------------------------------------|
-| `"Test loading failed for...  SyntaxError: Unexpected token ':'"`                | A comma is missing in your tests in the file named.                   |
-| `"Test loading failed for...  SyntaxError: Unexpected token '.'" often means ""` | You used `this.tests = []` instead of `tests = []` in the file named. |
-| Other `... Unexpected token ...` errors                                          | There is some other syntax error in the file named.  |
-| Unexpected actual values / passes / fails in test runs                  | Spoofs, retrievals, or other special conditions from previous tests haven't been replaced / reset.
+| 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.
+
 
-Usually when something is wrong in one test file, other test files still load and run, so a good sign of problems is a sudden decrease in the number of run tests reported.
+## Who is behind RiseiJs
 
+RiseiJs is made by Ed Fallin, a longtime software developer proficient in many technologies, with a knack for finding new answers to old questions.
 
-## Expanding the RiseiJs world
+If you find RiseiJs useful, consider spreading the word to other devs, making a donation, suggesting enhancements, or proposing sponsorships.
 
-If you find RiseiJs useful, consider spreading the word to other devs, making a donation, making suggestions for improvements, or proposing sponsorships.
+You can get in touch about Rjs using **riseijsmaker@gmail.com**.
 
 
 ## What the RiseiJs license is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "risei",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "RiseiJs is the framework that allows you to write unit tests as collections of values in JavaScript objects, so it's easy and fast, and tests don't serve as a drag on redesigns.",
   "keywords":[ "unit test", "test", "values", "objects", "easy", "fast" ],
   "author": "Ed Fallin <riseijsmaker@gmail.com>",