IBM Think

Introducing Bali Unit Testing Framework

01 Feb 2023

Today we’ve released two projects, one on HCL’s GitHub and a fork on OpenNTF’s GitHub. It will be useful to give a bit of background, as well as an introduction the the project.

Why Two Projects

The version on HCL’s GitHub is the original, Bali Unit Testing Framework, a unit testing framework written in and for VoltScript, the evolution of LotusScript currently in development for Volt MX Go. The documentation, as usual, is available on GitHub. There are a number of places where the code leverages new language functionality from VoltScript. As a result, although the code will be usable from VoltScript, the code cannot be used as-is by Domino developers.

Therefore a fork has also been created on OpenNTF’s GitHub and adapted for LotusScript, Bali Unit Testing Framework. The documentation is available also on GitHub. This can be used by Domino developers. The documetation has also been slightly modified, to be relevant to LotusScript developers.

A corresponding project has been created on OpenNTF’s website, Bali Unit for LotusScript, although this is just points across to the GitHub repo.

Aim of the Project

The aims of the project have been:

  • To make it easy to do unit and integration testing for LotusScript and VoltScript developers.
  • To provide reporting that can be included in your project documentation.
  • To provide output that can be used by CI/CD tooling to fail a build.
  • To allow tests to be written quickly.
  • To ensure it is clear what each test is intended to do.
  • To provide common assertions out-of-the-box.
  • To provide flexibility so that custom tests can be created.
  • To ensure additional code can be run before and after each or all tests.
  • To make writing tests fun.


The documentation should cover everything you need to know, including FAQs, walkthroughs of code samples, full sample scripts, samples outputs and API documentation.

But if you don’t like reading, stay tuned for a video on OpenNTF.

What Is It For?

This may seem to have an obvious answer. Although it can and should be used for integration testing as well as unit testing, it’s actually gained a second purpose. The framework has also proved very useful for validating content.

When using the framework for testing, tests can output HTML files for your project reporting, in a format that will be familiar for users of e.g. JUnit. But it can also output a standard XML format that can be parsed by CI/CD systems like Jenkins.

Why No NSF?

There are a wide variety of reasons why it shouldn’t be in an NSF, many very relevant for VoltScript. If the OpenNTF fork had, instead, moved the code to an NSF then there would be little point in it being a fork, because the differences would be so significant that it would be prohibitive to merging changes.

The current format also gives greater flexibility for version handling.

Yes, it requires copying and pasting the code into an NSF. But that is a common approach for Domino.

What Is The Future for the Projects?

Bali Unit has already been used in a variety of places, so is quite mature. There have not been a huge number of changes since the code was initially written. No additional assertions have been needed for many months, and we don’t anticipate adding others. The more assertions there are, the more a developer has to wade through in documentation and typeahead. An assertTrue() or assertFalse() can often handle more sophisticated checks.

There is also no intention to merge the projects. Until the VoltScript language enhancements are available in Domino, there will always be changes in the core code. There are also some subtle but important differences in documentation.

But where appropriate, fixes and enhancements will be considered for merging between the two projects.

Posted with : LotusScript, VoltScript, Domino