Product module tests

Make product module changes with confidence


The Root platform is designed to allow you to build product modules and make changes with confidence. We provide a suite of testing tools that enable you to understand the effects of your changes on your customers' experience, and verify that your custom product logic and configurations function as expected.

To test your product module changes effectively, it's important to understand which platform features are configurable, and how they relate to each other as well as standard platform functionality. We recommend that you start with a good understanding of the product modules overview guide. It's also important to understand the distinction between the sandbox and production environments, as well as the draft and live version of a product module. Read more in the workbench dashboard guide.

The rest of this guide covers the following:

  • What to test - A primer on how to think about configurable product module features, and how changing one feature can effect other features.
  • How to test - The various product module testing tools and methods, including unit tests, API tests and visual tests.

What to test

Product module features are interdependent, and changes to one feature can affect other features. For any change, it's important to need to understand and test all possible side-effects.

The diagram below answers the question, "If I make a change to Feature X, which other features could be affected?" Note: The diagram includes only configurable features and omits standard features like policyholders and payment methods. API docs and Embed are also omitted.

The diagram divides features into four categories:

  • Workflows - Frontend components, typically form elements, that can be configured to capture data from the user. This information is sent over the API to be processed by event hooks (except for claims blocks, which interact with the policy object directly).
  • Event hooks - JavaScript functions that process information received over the API. Some hooks
    like the policy issue hook, scheduled functions and lifecycle hooks, do not accept new input data, but use existing data as their inputs.
  • Data objects - These are the objects returned or changed by the event hooks, and are stored on the Root platform.
  • Externalisations - These are external representations of data stored on the platform.

Dependencies between configurable product module features

To further explain how to interpret this diagram, we'll use the example of adding a new benefit to an existing product from the Add a new benefit tutorial. In this case, the insurer wants to add a new optional benefit to the product, and customers should be able to choose at the quote step whether they want to include this benefit on the policy.

  1. In order to implement this change, we start with the quote hook, and add a new parameter that indicates whether the customer has chosen the optional benefit. This parameter will be present on the returned quote package object.
  2. The quote package is passed to the application hook where the new parameter will also be added to the application object.
  3. The application object is an input to the policy issue hook, and the new parameter will be stored on the policy object.
  4. Since the policy object has changed, we need to update the policy schedule to show the new benefit, as well as any customer notifications templates that reference policy benefits. We may also need to update scheduled functions, lifecycle hooks and alteration hooks, which accept the policy object as a parameter. Finally, we may need to update any data export templates that reference policy benefits.
  5. The policy object is an input into the claims blocks, which we need to update to indicate whether the customer is claiming for the new benefit. If we have any data exports relying on the claims data source, we may need to update those templates in turn.

How to test

Product module tests can be divided into three main categories: unit tests, API tests and visual tests. The table below provides a summary.

Unit testsUse unit tests to verify that individual product module code functions work as expected.- All event hooks & actions (product module code functions).

- Product module code helper functions.
- Write tests using mocha and chai libraries

- Run tests using the rp test Workbench CLI command
API testsAPI tests allow you to test the policy lifecycle end-to-end, from quote and policy issuing, through to claims and payouts.

These are the most important tests. They ensure that the API endpoints you have configured for your product work as expected. You can also test the cumulative effect of many events applied sequentially over the policy lifecycle.
- Policy issuing: Quote, application and policy issue steps

- Policy management: Alteration hooks, lifecycle hooks, scheduled functions, cancellation and reactivation
- Claims: Creating claims, assessing claims, and generating claim payouts
- Billing config: Selected functionality can be tested via the API
- API platforms like Postman

- Scripts in any language or framework capable of making HTTP requests (Node.js, Python, Ruby, Java, etc.)
Visual testsSome product module features need to be checked visually, since they involve configuring documents, emails and user interface elements.- Quote schema

- Application schema
- Alteration hook schema
- Embed workflows
- Claims workflow
- Policy documents
- Policy view on the Root management dashboard
- Customer notifications(email and SMS templates)
- Data export templates
- Root management dashboard

- rp render Workbench CLI command(for policy documents)

Unit tests

Unit tests allow you to test that individual product module code functions work as expected. You can write and execute unit tests for your product module using the Workbench CLI tool.

Unit tests will run on your local machine. They are not executed in the Root platform environment. This means that unit tests are best suited to testing individual code functions. If you want to test integrated platform functionality, we recommend using API tests.

This is an example of a unit test for the validateQuoteRequest function.

describe('validateQuoteRequest', function () {
  it('Valid data should pass validation', function () {
    const quoteData = { <YOUR QUOTE DATA OBJECT HERE> };
    const validationResult = validateQuoteRequest(quoteData);

  it('Invalid data should not pass validation', function () {
    const invalidQuoteData = { <YOUR INVALID QUOTE DATA HERE> };
    const validationResult = validateQuoteRequest(rejectedQuoteData);
    expect(validationResult.error.details[0].message).to.equal('<parameter specific error message>');

API tests

Root is an API-first platform, and the API represents the most comprehensive and flexible tool to test your product module. By sending API requests to the platform's sandbox environment, you can issue policies and simulate the policy lifecycle to test your product module logic and configuration.


Use the API to create stub policy data

You can use the sandbox-only Update a policy endpoint to update the policy module data and other policy fields. This allows you to create "stub" policies that represent different points in the policy lifecycle, and can then be referenced in further API calls.

Using the sandbox API, you can test the following product module features.

DomainProduct module features
Policy issuing - Generating quotes: use the Create a quote endpoint
- Adding / updating policyholder details: use the Upsert a policyholder endpoint
- Create and manage an application: Use the Create an application and Requote an application endpoints
- Issuing a policy: Use the Issue a policy endpoint
Policy management & lifecycle - Alteration hooks: Use the Create an alteration package and Apply alteration package endpoints
- Lifecycle hooks: Lifecycle hooks are typically triggered automatically by other policy actions. For example, applying an alteration package will trigger the afterAlterationPackageApplied lifecycle hook
- Scheduled functions: Use the Trigger policy scheduled function endpoint
- Reactivation: Use the Reactivate policy endpoint
Claims - Opening a claim: Use the Create a claim endpoint
- Updating claim information: Use the Update multiple Block states endpoint
- Claim assessment process: Use the endpoints for claims assessor and claims supervisor decisions
Billing - Adding a payment method: Use the Create payment method endpoint and specify the relevant policy_id to link the payment method to.
- Creating payments: Use the Create policy payment endpoint
- Payment coupons: Use the Create payment coupons for a policy endpoint

You can interact with the API using any tool, framework or programming language that can make HTTP requests. For example, you could create a Postman collection or Python script that you run every time you make a change to your product module. This collection or script can make sequential requests to create a quote, issue a policy and perform lifecycle actions against the policy.


API testing should start with creating a new quote

To test product module definition changes, you should start by creating a new quote. The policy issued from this new quote (and any further entities associated with the policy) will be associated with the latest product module definition.

You can use this Postman collection as a starting point. It is used to test the pricing logic of the Dinosure template product module in the Update pricing tutorial.

Visual tests

Quote, application and alteration hook schemas

Schemas allow you to configure user interface (UI) elements for selected workflows on the Root management dashboard. As such, you should test any changes by completing the corresponding workflow, and confirm visually the appearance and functionality for both happy and unhappy paths .

Claims workflow

As part of the claims workflow, you can configure claims blocks, document labels and the claims assessor checklist. You should test any changes to these features by completing the corresponding workflow(s) on the Root management dashboard, and confirm visually their appearance and functionality for both happy and unhappy paths.

Embed workflows

Root Embed allows you to configure customer-facing self-help workflows for policy issuing (Embed | Sales) and policy management (Embed | Management). Changes to many product module features are likely to affect the Embed workflow. If you have these add-ons enabled, you should visually confirm that the workflows still look and function as expected after making any changes.

Policy documents

On Root, you can configure templates for a range of policy documents, which are attached to customer notifications. The document templates are built in HTML, and are converted to PDF by the Root platform.

When making changes to the HTML document templates, you should visually check the resulting PDFs. It's important to remember that policyholder and policy data can vary across entities. For example, one policyholder's address could occupy two lines, while another policyholder's address could occupy four lines. One policy may have three nominated beneficiaries, while another policy may have none. These differences can affect the structure and layout of the resulting PDF document, and you should take such differences into account when you test.

You can test changes to policy document templates using the rp render command in the Workbench CLI tool, or by opening the relevant documents for a sandbox policy on the Root management dashboard.

Customer notification templates

Root allows you to customise email and SMS templates for a range of policy lifecycle events, and dynamically inject policy and policyholder data into the message body. These templates may be affected by changes to other product module features, such as changing or removing custom policy fields. The Root management dashboard allows you to preview and test changes to these templates.

Policy view on the Root management dashboard

The way policies appear when they are opened on the dashboard depends on how you have configured the policy module object. This means that, when you make changes to the policy module, you should visually check the appearance of policies on the dashboard.

Data exports

Any data export templates you have configured for your product module are likely to reference policy, claim and other product module specific data. If you make any changes to the underlying structure of these data objects, such as changing the name of a property on the policy object, you should create a data export run and visually verify that the relevant data are exported correctly.