Test an app

libmodulor relies on vitest to run the tests and @vitest/coverage-v8 for the coverage.

Configurator

By default, no tests are executed for an app. First, create a file named src/apps/{AppName}/test/Configurator.ts.

@injectable()
export class Configurator extends SimpleAppTesterConfigurator {}

Generate the automated tests for the app.

pnpm libmodulor GenerateAppsTests

Run the tests.

pnpm libmodulor TestApp --appName {AppName}

 % Coverage report from v8
------------------------|---------|----------|---------|---------|-------------------
File                    | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
------------------------|---------|----------|---------|---------|-------------------
All files               |   98.83 |       80 |      80 |   98.83 |                   
 Trading                |       0 |        0 |       0 |       0 |                   
  index.ts              |       0 |        0 |       0 |       0 | 1                 
 Trading/src            |     100 |      100 |     100 |     100 |                   
  i18n.ts               |     100 |      100 |     100 |     100 |                   
  manifest.ts           |     100 |      100 |     100 |     100 |                   
 Trading/src/ucds       |     100 |      100 |     100 |     100 |                   
  BuyAssetServerMain.ts |     100 |      100 |     100 |     100 |                   
  BuyAssetUCD.ts        |     100 |      100 |     100 |     100 |                   
------------------------|---------|----------|---------|---------|-------------------
2024-12-29T11:00:53.178Z [info] Coverage Report => open src/apps/Trading/test/reports/coverage/index.html
2024-12-29T11:00:53.178Z [info] Simple HTML Report => open src/apps/Trading/test/reports/simple-html/index.html

In addition to running the tests, it also :

• Generates a coverage reports : src/apps/{AppName}/test/reports/coverage/index.html
• Generates a test scenarios report : src/apps/{AppName}/test/reports/simple-html/index.html
• Update the app's README : src/apps/{AppName}/README.md

Coverage report

This is a regular coverage report generated by @vitest/coverage-v8.

Test scenarios report

This is generated by libmodulor providing you an HTML file containing table listing all the scenarios tested.

README.md

This is generated by libmodulor providing an overview of the app with :

• a sequence diagram for each use case
• a technical summary for all the use cases

It gives a great overview of what the app does.

In Create a use case, we mentioned comments starting with // >=> . This is where they enter in action. These comments are displayed in an awesome way in the sequence diragram, giving an overview on what's going on in the "use case box".

Customize

The Configurator class offers a basic setup. But in most advanced apps, it needs to be customized to handle more complex scenarios. It offers methods that can be overriden to achieve this goal.

Auth setters

By default, each use case is tested for multiple auth settings (anonymous, authenticated, etc.). You can override this behavior by providing your own.

Implementations

Some apps need specific bindings. This is the case when they have interfaces/implementations defined in the lib folder, that are used by use cases.

You can bind those implementations and also rebind some default bindings.

Clearing

Some use cases create side effects that can impact others.

You can define the logic to clear these side effects between each test execution.

Flows

Use cases are automatically tested in isolation. But very often we want to test them in a real life scenario.

You can create flows to test a list of use cases one after the other to simulate a real user behavior.

For instance, for an Auth app, you can test the following flow : SignUp > SignIn > SignOut.

Input fillers

Use cases are tested with data from their data types examples and bad data.

You can define other inputs for specific use cases to see how they behave.

Options

Override the default options used by the test runner.

Seed

Some apps need data that has been pre-populated in some data store.

You can seed these data stores.

Side effects

Some use cases perform side effects that we want to monitor. For instance, some of them can send emails.

You can register these side effects and they will be asserted and displayed in reports.

Specific assertions

By default, the tests are asserted via snapshots. But sometimes, use cases return different data at each execution (e.g. the "current" timestamp).

Although we recommended making the tests deterministic by using Fake* implementations, sometimes it's not possible or not acceptable.

In this case, you can override the snapshot assertion by a specific one using the hash of the test execution to identify it.