Risei Home Page

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 coded tests with simple declarative syntax.

• Risei works with object-oriented JavaScript in modules.
• Risei works with TypeScript after just a few tweaks.

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 was under active development until recently, but its major features are now complete.  New enhancements or fixes may appear from time to time.

The latest releases, 3.0.0 and 2.0.0 / 2.0.1, brought major improvements, including the ability to test async code, to test properties, and much more.

Check out the list of these changes.

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

• To run, a test must have .on, .with, .of, .for, .in, and .out defined.
• When there are no constructor or method args, you can use empty arrays for .in or .with.
• Some of these properties' names are harmlessly the same as JS keywords.  Long names exist if you want to use them instead.

Asynchronous code with async and await keywords can tested with no changes at all to this syntax.

Collapsing forward for lighter tests

You can write more tests with less syntax by stating test properties once and letting them collapse forward across subsequent tests.

Risei collapses values together until it has a full test to run, as seen in this typical example:

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

Every property collapses forward until it is set to something else or wiped out with a target shift:

• Changing .on (the target class) wipes out all other test properties.
• Changing .of (the target method) wipes out all except .on, .with, and .plus (described later).
• To drop any optional property starting with the current test, you can set it to an empty array [].

Preventing extra tests using .just:

You may want to pre-set a property for an upcoming group of tests, even when fully defined tests already exist.  However, this creates an accidental extra test (which often fails), because Risei always collapses old and new values together to make a new fully defined test.

It's easy to avoid this problem with the .just property:

{ on: ContainerClass, with: [ "a", "b", "c", ] },  // A section of tests using these values.
{ ... },
{ ... },

{ just: true, with: [ "t", "u", "v" ] },           // Changing .with without creating an extra test.
{ ... },                                           // Tests using the new .with start here.
{ ... },

• The value of .just doesn't have to be true, or any value in particular.  The property just has to be defined.

Avoiding mutable-arg problems by restating them:

Collapsing forward reuses test property contents directly.  Tests are isolated unless your code mutates its arguments.  If so, the mutated values are used, throwing off test results.

To prevent this problem, simply restate mutable args in each test to keep them independent.

Testing properties and static methods

To test properties of instances, or to test static methods and properties, you use exactly the same syntax you would for instance methods, and Risei figures out the rest:

tests = [
    { on: VariegatedClass, with: [ ] },
    { of: "instanceMethod", for: "Returns true.", in: [ ], out: true },  // Typical use: instance method.
    { of: "staticMethod", for: "Returns false.", in: [ ], out: false },  // Static method: same syntax.  Empty .with needed.
    { of: "instanceProperty", for: "Returns 47.", in: [ ], out: 47 },    // Instance prop: same.  Empty .in needed.
    { of: "staticProperty", for: "Returns 98.", in: [ ], out: 98 }       // Static prop: same.  Empty .in needed.
];

• When testing statics or properties, tests still need a .with and .in.  You can set them to empty arrays [] if needed.

Although Risei figures out what it needs to, you can explicitly indicate member types if you want, and Risei then treats the code as you specify:

{ of: "instanceMethod()", ... },                            // Trailing parens specify method.
{ of: ".someProperty", ... }, { of: "someProperty:", ... }  // Leading dot or trailing colon specify property.
{ of: "something", and: "static", ... },                    // You add an .and of "static" for statics.

• This syntax can be used in .of, .plus (covered here), and .from (covered here).
• When a property is tested directly, it is listed in test output with a leading dot, like .name.

Spoofing for test isolation using .plus

To make code dependencies return what your tests need, just spoof what you want using a .plus test property:

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

There are many options available for spoofing, all laid out together in this example:

{ on: CombinerClass, 
  ...
  plus: [ 
    /* Mono-spoofing. */
    { 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 the tested class not to do anything.

    { on: ClassC,                                // Spoof this ClassC method to be this nonce code using a runtime arg.
      of: "someMethod",
      as: (arg) => { return { color: arg }; } }, 

    /* Poly-spoofing. */
    { on: ClassD, as: [                          // Spoof two methods on ClassD at the same time.
        { of: "firstMethod", as: 11 }, 
        { of: "secondMethod", as: 12 } 
      ] },
    { as: [                                      // Spoof two methods on the tested class at the same time.
        { of: "firstMethod", as: 11 }, 
        { of: "secondMethod", as: 12 } 
      ] },
  ],
  ...
}

• These individual types of spoofing can be mixed however needed.
• You can spoof multiple class methods at the same time with either mono- or poly-spoofing syntax.
• A spoof nonce function can use args provided to it, but not this of the tested instance.
• You can spoof properties only for the class under test.

Special test conditions

Testing throws with .and of "throws":

You can test for a value thrown in code by adding an .and property of "throw" or "throws":

{ 
  on: TestedClass, of: "throwsWhenNoArgsGiven", and: "throws", 
  for: "When not given any args, throws an Error stating \"Argless.\".",
  in: [ ], out: new Error("Argless.") 
}

• The .and property is an extension point for special test conditions.
• A test's .and can contain any mix of valid .and values.

Testing for undefined actuals with this.undef:

You can test for an undefined value by setting .out to this.undef (or ATestSource.undefSymbol):

{
  on: TestedClass, of: "returnsArgGiven", 
  for: "When the arg is undefined, returns undefined.",
  in: [ undefined ], out: this.undef 
}

• You can't use undefined itself directly for .out, because Risei treats it as a missing property.

Changing actual with .from:

You can refine or replace the test's actual using the .from property, for instance for method side-effects or derivatives of the original actual.

Property-name .from:

The .from can be the name of a property on the target class or its instance created for the test:

{
  on: TestedClass, of: "makeInstanceReady", 
  for: "When method is run, the .ready flag is set.", 
  in: [ ], out: true, 
  from: "ready"
}

• Both instance and static props can be retrieved this way.
• You can't retrieve an instance property for a test of a static method, because no instance is created.

Nonce-function .from:

The .from can be a nonce function, which must always return a new actual value:

{
  on: TestedClass, of: "initDerivedObject", 
  for: "When method is run, output's .flag is cleared.",
  in: [ ], out: false,
  from: (test, actual) => { return actual.flag; }
}

• The actual parameter (found second) is the original actual value from running your targeted code.
• The test parameter (found first) is the assemblage of test properties you provided, plus others that Risei sets.  Here are the properties you'll most likely want to use in .from:
• test.target — The instance created for the test, or the class for a static test.
• test.in — An array, most useful for methods that mutate their arguments.
• test.out — To replace the original expected value using test-time values.
• Other provided test properties exist, with predictable names, but are rarely needed.
• It's best not to address properties calculated by Risei apart from test.target, as this might cause problems.
• Risei uses the return value of .from to set test.actual, so even though you can set the latter in .from, it has no effect.
• Although you can perform arbitrary operations in .from, in general it's better (and more flexible) to use .do and .undo for that.

Changing external state with .do.early, .do.late, and .undo:

If test state you need can't be created declaratively, you can set it up and then tear it down using .do and .undo.  The .do property has two stages, .early and .late.

You set these properties to nonce functions:

{
  on: TestedClass, for: "When the file to read is not text, returns first ten bytes as hex.",
  do: { 
    early: () => { writeRandomTestFile(); },              // Steps before any test target instance is created.
    late: (test) => { test.out = readTestFileHex(10); }   // Steps after any instance is created, here altering a test property.
  },
  undo: { () => { eraseRandomTestFile(); },               // Steps after everything else in the test.
  in: [ ... ], out: 0x00,                                 // .out is replaced with varying data in .undo.
}

• You're better off using Risei's declarative syntax whenever it can do what you need.
• You don't need to include both do.early and do.late if you only need one, which is normally the case.
• You can use the test parameter to alter the test itself if needed, though this is rare.
• If you do, it's best not to change any properties set at runtime by Risei.

Running a method repeatedly in one test with .and of "poly":

You can call a method or property repeatedly in one test (poly-call it) by adding an .and property of "poly", with changes to what's in .in and .out:

{ 
  on: TestedClass, of: "sumSoFar", and: "poly", 
  for: "When called repeatedly, sums all args provided so far.",
  in: [ [ 1 ], [ 5 ], [ 8 ], [ 6 ], [ 4 ] ],  // An inner array for each call of the method (each empty if no args or property test).
  out: [ 1, 6, 14, 20, 24 ]                   // An array for the outputs of all calls, unless .from is used to customize output.
}

• When poly-calling, the actual parameter / test.actual parameter in .from is an array of all the outputs.
• The number of inner input arrays in .in and arrayed outputs in .out should be the same when testing all outputs.
• To look at one output from the calls, you provide a single value for .out, and use .from to return the value you want.
• The .and property can contain any mix of valid .and values.
• This feature allows you to test certain kinds of algorithms and situations, but dissimilar cases are generally better handled with individual tests.

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

In tsconfig.json:

You set up the transpiler to output files to a separate directory with these two settings:

{
  "outDir": "dist/out-tsc",
  "noEmit": false
}

• Any folder can be outDir, but it's best to avoid dist, which can interfere with frameworks' build steps.

In package.json:

In the test script, add transpilation before the test run, and file deletion after it, each one conditional on the previous:

"scripts": {
  "test": "tsc && node ./node_modules/risei/index.js && rm -r ./dist/out-tsc"
}

• Using tsc or an equivalent produces individually testable JavaScript files.
• Deleting 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.

In test files:

All import statements have to point to the JavaScript (.js) files in the outDir path or its subfolders:

import { TestedClass } from "../../dist/out-tsc/SubPath/TestedClass.js";

• Output files may be in a folder tree parallel to the TypeScript originals (Angular), or may all be in the outDir folder itself (React).

Troubleshooting

When a gold bar appears and some tests disappear:

When problems cause test files not to load, you see a gold bar listing the syntax errors at fault:

• Test files without syntax errors are still loaded and run, so you also see a lower total number of tests.

Here are the most common problems:

When the listed tests or their results are unexpected:

Property long names

Test properties have longer names that you can use interchangeably with their short names.

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) 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 the sigils ., :, and () in .of, .plus, and .from, though it isn't necessary to do so.
• (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.

Known issues and workarounds

The only issue at present is the use of mutated args when tested code mutates them, when collapsing forward.

• The workaround is simply to restate the args for each test.

Exclusions from Risei

The following are not supported at present:

• Any code not in classes, even in ESM export modules, AKA loose code
• CJS syntax using require()
• Performing step-through debugging of tests and tested code
• Comparing rare JS object types like Proxy or ArrayBuffer in test assertions
• Testing for inequality of values

Some of these may be supported in the future.

• You can save a lot of time by using Risei for most of your code, but 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 riseimaker@gmail.com.

License

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