Risei Read-Me

Overview

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.
• Risei works with object-oriented JavaScript in modules.
• Risei works with TypeScript after just a few tweaks.

You can find a longer version of this read-me at https://deusware.com/risei.  It expands greatly on the information here.

Examples

Here are two example tests, in which SortModel.countSort() is being tested using the inputs from .in and the expected output from .out:

Here are the example test results for those two tests:

• 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 have a title bar so the starting point is easy to find:

And they have a summary bar at the bottom:

• This bar is red when any tests fail, much as you'd expect.

Status

Risei is under active development and new enhancements appear often.  The latest release, 3.0.0, brings major improvements, starting with the ability to test async code, and builds on many major improvements in 2.0.0, including broader capabilities and simpler syntax, and a few minor breaking changes.

Check out the full list of changes.

Features of Risei

• Declarative syntax to write tests simply and quickly.    ►  Writing tests  (basics below)

• Easy-to-read test definitions and test outputs.    ►  Test and output examples  (also above)

• Even less to write by stating reused test properties only once.    ►  Collapsing forward  (basics below)

• Built-in declarative syntax to fake test-time values from dependencies.    ►  Spoofing using .plus  (basics below)

• Full support for async code with no special syntax needed.    ►  Writing tests  (basics below)

• Testing properties and methods, static and instance members all the same way.    ►  Properties and statics

• Testing throw paths effortlessly.    ►  Using .and: "throws"

• Deriving actual values to test from raw outputs or property retrieval.    ►  Using .from

• Setting up and tearing down arbitrary test state.    ►  Using .do and .undo

• Testing for undefined as output.    ►  Using this.undef

• Running a method repeatedly in one test.    ►  Using .and: "poly"

• And more!  Check out the full Risei home page.

Installation

Install Risei for development time only:

npm install --save-dev risei

Ensure that package.json specifies ECMAScript modules:

"type": "module"

And add Risei's metadata to package.json:

"risei": {
  "tests": "**.rt.js"
}

Running Tests

Once you have some tests written, you can run them manually:

node ./node_modules/risei/index.js

Or write a script in package.json that does the same:

"scripts": {
  "test": "node ./node_modules/risei/index.js"
}

And then run that script:

npm test

Writing Tests

You write tests in .rt.js files like this:

import ATestSource from "risei/ATestSource";
import ClassToTest from "ClassToTest.js";

export class SomeTests extends ATestSource {
    tests = [ ... ];
}

Write individual tests as plain JavaScript objects with Risei's simple syntax:

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.
... ];

• Asynchronous code with async and await keywords can tested with no changes at all to this syntax.
• Use empty arrays for .in or .with when there are no args to pass.
• You can use long names for properties if you want.

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.

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:

{ 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.

{ of: "countOf" },                                                   // Change of tested method.  Method-related props are wiped out.
...

{ on: SortingClass, with: [ ] },                                     // Change of tested class.  All existing props are wiped out.

• There are more options available, and an exclusion for mutated args.
• Learn all the details here.

Basic spoofing example

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:

{ 
  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.
    ],
  ... 
}

• It's just like fakes, mocks, or test doubles in other test systems, but easier to write and read.
• Numerous additional capabilities, as well as compressed syntax, can be mixed freely in many ways.
• Learn more here.

TypeScript with 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.

Troubleshooting

If problems cause test files not to load, a gold bar appears and tests in those files disappear from output:

• Those and other problems can be solved with the help of this troubleshooting guide.

Version history

• Release 3.0.0 (August, 2024) contains all of these changes:
  • Asynchronous code with async syntax is now fully supported, with no special test syntax required.
  • (Breaking change)  .from functions now take test and actual as parameters, rather than target and test.
    • If you need to work with the target of the test (usually an instance of the class being tested), it's available as test.target.
  • You can now call target code more than once in one test using an .and of "poly" (AKA poly-calling).

• Release 2.0.1 (August, 2024) contained 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 any of .of, .plus, and .from, though it isn'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.
  • Major internal re-engineering.

• Release 2.0.0 (August, 2024) was 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.  Using the latest release is recommended.

Known issues and workarounds

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.

Exclusions from Risei

At present, there are a few things Risei doesn't support.  Some of these may be supported in the future.

• You can see the whole list here.
• You can save a lot of time by using Risei for most of your code, and another framework for whatever it doesn't support.

Maker

Risei is written by myself, Ed Fallin.  I'm a longtime software developer who likes to find better ways to do things.

If you find Risei useful, consider spreading the word to other devs, making a donation, suggesting enhancements, or proposing sponsorships.

You can get in touch about Risei at [email protected].

License

Risei is published for use under the terms of the MIT license:

Risei Copyright © 2023–2024 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.