risei 1.0.0

package/LICENSE.txt

@@ -0,0 +1,8 @@
+
+Copyright © 2023 Ed Fallin
+
+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:
+
+The above copyright notice and this permission notice (including the next paragraph) shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,642 @@
+
+# RiseiJs
+
+## What RiseiJs is
+
+**RiseiJs 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.
+
+### Basics of the RiseiJs approach
+
+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">
+
+![./usage-examples/Syntax-example.png](./usage-examples/Syntax-example.png)
+
+</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:
+
+<div style="padding-left: 1.5rem;">
+
+![./usage-examples/Output-example.png](./usage-examples/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 a light red.&nbsp;
+
+Test runs also feature a title bar, plus a summary bar at the bottom:
+
+<div style="padding-left: 1.5rem;">
+
+![./usage-examples/Summary-example.png](./usage-examples/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`:
+
+<div style="padding-left: 1.5rem;">
+
+```bash
+npm install --save-dev risei
+```
+
+</div>
+
+<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 they can for 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:
+
+<div style="padding-left: 1.5rem;">
+
+```json
+"risei": {
+  "tests": "**.rt.js"
+}
+```
+
+</div>
+
+<details>
+<summary>
+&nbsp; More options
+</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.
+
+</details>
+
+
+
+3. Create test files with a `.rt.js` extension.
+
+<details>
+<summary>
+&nbsp; More options
+</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.
+
+</details>
+
+
+
+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;">
+
+```javascript
+import { ATestSource } from "risei/ATestSource";
+import { TargetClass } from "your/path/and/file.js";
+
+export TargetClassTests extends ATestSource {
+    tests = [ ];    // Not `this.tests`.  This array is where test definitions are written.
+}
+```
+
+</div>
+
+<details>
+<summary>
+&nbsp; More information
+</summary>
+<br>
+
+- Files of tests must be 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.
+- 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: 
+
+<div style="padding-left: 1.5rem;">
+
+```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.
+    ... ];
+```
+
+</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 `()` used             |
+| `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.&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.
+
+</div>
+
+</details>
+
+
+
+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:
+
+<div style="padding-left: 1.5rem;">
+
+```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 }
+```
+
+</div>
+
+<details>
+<summary>
+&nbsp; More information
+</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.
+- Individual tests remain isolated because class instances, spoofed methods (covered later) and so on are all created anew for each test.
+
+</details>
+
+
+
+7. To isolate any tests with dependencies, spoof the methods depended on, in any objects, with the `.plus` property:
+
+<div style="padding-left: 1.5rem;">
+
+```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" } }
+          ]
+          for: "When called, returns an array of values from sources.",
+          in: [ ], out: [ 7, 8, 9, 10, 12, { color: "green" } ] }
+```
+
+- Spoofing definitions collapse forward across tests unless they're replaced with new definitions, or are erased by setting `.plus` to an empty array `[ ]`.
+- Defining new spoofing wipes out all old definitions.
+
+</div>
+
+<details>
+<summary>
+&nbsp; Spoofing syntax and options
+</summary>
+<br>
+
+- Each object in `.plus` consists of the following:
+
+<div style="padding-left: 1.5rem;">
+
+| 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 |
+
+</div>
+
+- You can leave out `.as` when you don't need a return value.&nbsp;  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:
+
+<div style="padding-left: 1.5rem;">
+
+```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>
+
+- 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.
+- 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:
+
+<div style="padding-left: 1.5rem;">
+
+```javascript
+          plus: [
+            { on: SimpleObject, of: "getText", as: "Text" }, 
+            { on: ComplexObject, 
+                as: [ { of: "getIntegers", as: [ 6, 7, 8 ] }, 
+                      { of: "getDoubles", as: [ 6.0, 7.0, 8.0 ] } ]
+            }
+          ]
+```
+
+</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>
+
+</details>
+
+</details>
+
+
+
+8. Run your tests by invoking RiseiJs' `index.js` file:
+
+<div style="padding-left: 1.5rem;">
+
+```bash
+node ./node_modules/risei/index.js
+```
+
+</div>
+
+<details>
+<summary>
+&nbsp; More information
+</summary>
+<br>
+
+- 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>
+
+
+
+9. Or write the `test` script in `package.json` to invoke `index.js`, to make your life easier:
+
+<div style="padding-left: 1.5rem;">
+
+```json
+"scripts": {
+  "test": "node ./node_modules/risei/index.js"
+}
+```
+</div>
+
+<details>
+<summary>
+&nbsp; More options
+</summary>
+<br>
+
+- You can instead write a unique script for Rjs, though this takes more syntax to call later:
+
+<div style="padding-left: 1.5rem;">
+
+```json
+"scripts": {
+  "risei": "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:
+
+<div style="padding-left: 1.5rem;">
+
+```json
+"risei": "node ./node_modules/risei/index.js"
+"test": "mocha **/* && risei" 
+```
+
+</div>
+
+- Of course, if you are used to Linux / Unix scripting, you may also find other techniques to make running tests easier.
+
+</details>
+
+
+
+7. Run that script whenever you want to run tests:
+
+<div style="padding-left: 1.5rem;">
+
+```bash
+npm test
+```
+
+</div>
+
+<details>
+<summary>
+&nbsp; More options
+</summary>
+<br>
+
+- Or run a custom script with longer syntax like this:
+
+<div style="padding-left: 1.5rem;">
+
+```bash
+npm run risei
+```
+
+</div>
+
+</details>
+
+
+
+## Advanced RiseiJs usage
+
+### Testing static methods
+
+To test a static method, you add an `.and` property to a test, with the value `"static"`:
+
+<div style="padding-left: 1.5rem">
+
+```javascript
+{ on: StaticModel, 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 }
+}
+```
+
+</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.
+
+</details>
+
+
+### 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:
+
+<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       |
+
+- 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>
+&nbsp; More information
+</summary>
+<br>
+
+- Use of `.from` with a property name looks like this: 
+
+<div style="padding-left: 1.5rem">
+
+```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" },
+```
+
+</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 |
+
+</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). 
+- The `test.on` property always references the class under test, rather than an instance of it.
+
+
+- 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:
+
+<div style="padding-left: 1.5rem">
+
+```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]; } 
+},
+```
+
+</div>
+
+</details>
+
+
+### 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.
+
+
+<details>
+<summary>
+&nbsp; Test properties' short and long names
+</summary>
+
+<div style="padding-left: 1.5rem;">
+
+| Short Name | Long Name |
+|------------|-----------|
+| `on`       | `type`    |
+| `with`     | `initors` |
+| `of`       | `method`  |
+| `for`      | `nature`  |
+| `in`       | `inputs`  |
+| `out`      | `output`  |
+| `plus`     | `spoofed` |
+| `from`     | `source`  |
+| `and`      | `factors` |
+
+</div>
+
+</details>
+
+<br>
+
+<details>
+<summary>
+&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
+
+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 `[ ]`.
+
+
+### Limitations in RiseiJs
+
+The following are not supported at present:
+- Use of `async` syntax
+- 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`
+
+
+## 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.
+
+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.
+
+
+## Expanding the RiseiJs world
+
+If you find RiseiJs useful, consider spreading the word to other devs, making a donation, making suggestions for improvements, or proposing sponsorships.
+
+
+## What the RiseiJs license is
+
+RiseiJs 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>
+
+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:
+
+The above copyright notice and this permission notice (including the next paragraph) shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.&nbsp;  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+</div>
+
+
+&nbsp;