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 class-based 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's major features are now complete, but new enhancements or fixes may appear from time to time.

The latest release, 3.3.2, adds async capabilities to the .from feature.

Check out the full list of 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"
}

Testing Risei Itself

To test Risei itself, you clone it from a parallel repository, install dependencies with npm, and run its self-tests.

• There are several options for which set of tests to run (covered later).
• A dependency update after installation (as seen in the example) is advisable, due to anomalous warnings.

git clone https://gitlab.com/riseimaker/risei-public.git risei

cd risei

npm install

npm update

npm run mixedtest

• Risei is tested in part using Risei itself (AKA dog-fooding and/or bootstrapping).
• Certain key elements are also tested using mocha with chai.
• Recommended test-set options:
  • mixedtest:  (Seen in example.)  Runs all mocha / chai unit tests, then all of Risei's unit tests for itself.
  • alltest:  Runs everything mixedtest does, plus trial tests (Risei tests mostly of other code, as a sort of double-check).
• There are several other, less general options, like test / npm test (which runs only Risei's unit tests of itself).

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 / awaitable code can tested with no changes at all to this syntax.

If you use .plus or more advanced features like .from, you define asynchronous / awaitable
functions using async and await normally.  (See later sections for more details.)

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

Collapsing forward for lighter tests

You can write more tests with less syntax by stating repeated test properties just 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 / .only 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 in almost all cases, 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 can add an .and of "static" for static memberss.
{ of: "something", and: "instance", ... },                  // You can add an .and of "instance" for instance members.

• Property vs. method 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.

If you have static and instance members with the same names, you have to use an .and of "instance" to test the instance methods.

Apart from a very few built-in JavaScript methods like toString(), this is a rare situation.  Identical static and instance names are
the only case where specifying static / instance type in .and is actually necessary.

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 use awaitable code with async and await when spoofing methods.
• 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.
• The nonce function can be awaitable code, written using normal async and awaitsyntax.

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.
• All of these properties can be awaitable code, written using normal async and awaitsyntax.
• 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

• In Risei, a throw during a test is not automatically a fail.

When a gold bar appears saying that a test file failed to load, 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 gold bars appear stating there were throws:

If errors are thrown while testing, gold bars listing them appear at the bottom, and full stack traces appear amid the test output.  Errors that you
indicate you expect with an .and of "throw" or "throws" are not included.

There are two scopes for these throws: tested code, and framing code.  The former is the code you're testing.  Throws here can include anything
resulting from spoofing you define in .plus.

The latter is code used to test your code.  If you see a throw from framing code, most likely you have made a mistake in .do, .undo, or .from.

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.3.2 (September, 2025) contains this change:
• You can now use asynchronous / awaitable code in .from, using async and await normally.
• You already could use awaitable code with the normal syntax in .plus, .do, and .undo.


• Release 3.3.1 (February, 2025) contains this change:
• You can now spoof and otherwise address value properties (formally data descriptors) that don't have an initial value,
  whether they are static or instance class members.


• Release 3.3.0 (January, 2025) adds this change to those of other recent releases:
• You can now test instance members with the same names as static members using a new .and option of "instance".

Known issues and workarounds

These are the known minor issues:

• If args for a test are mutated by tested code, the mutated args are used when collapsing forward.
• The workaround is just to restate those args for each test.

• Spoofing accessor properties only works when they have both a getter and a setter.
• The workaround is to find another way to produce the property values you need.

• Predefined JavaScript methods like toString() may not be recognized, nor any instance method that has
  the same name as a static method.
• The workaround is to use an .and value of "instance" for any methods like these that you 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().
• 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: