TypeScript library & unit tests

Guide

In this guide, we will use the Jest testing framework in conjunction with the the "Basic TS Package" template (found in OXIDE) to create a reusable library that is also fully tested.

In the end, the package structure will look like this:

1. Add the basic TS template package to your app

Navigate to the Packages workspace, or open the Packages panel, and create a new package. In the Package template dropdown, select "Basic TS Package" and proceed to follow the prompts. This created an app package with a basic framework to generate custom PDF reports.

Note: you can also use the command palette to find the Create package action.

2. Export a function

Since this package represents a library, we will export a simple sum function inside the src/index.ts file

export function sum(a: number, b: number) {
    return a + b;
}

3. Add a test

Now we create a new file called tests/sum.test.ts (OXIDE will create a new tests folder) and insert the following Jest code:

import { sum } from "../src";

test('adds 1 + 2 to equal 3', () => {
    expect(sum(1, 2)).toBe(3);
});

4. Update the package.json file

To run Jest, we need to first add a few dependencies and make some changes in our package.json file. Tip: if you cannot see the package.json file, ensure that the Show configuration files setting in OXIDE is toggled on.

{
    ...

    "scripts": {
      "build": "tsc -b && jest"
    },
    "main": "dist/src/index.js",
    "dependencies": {
      "jest": "^27.2.0",
      "@types/jest": "^22.2.3",
      "@babel/core": "7.15.5",
      "@babel/preset-env": "7.15.6",
      "@babel/preset-typescript": "7.15.0"
    },
    "jest": {
        "testMatch": [ "**/tests/**/*.test.ts" ]
    },

    ...
}

1. The "build" command is changed.

2. Our "main" entry now contains the 'src'

3. We add the latest versions of all the dependencies.

4. We add a "jest" field which tells Jest to find our tests correctly

5. Update the yarn lockfile

Because changes have been made to the package.json file, we must update the lock file using yarn.

In OXIDE, right click on the package, and select the update action as shown:

6. We configure Babel

When writing Jest tests using TypeScript, Jest will use Babel to transpile the files. For this reason we need to add a babel.config.js file with the following configuration:

module.exports = {
    presets: [
        ["@babel/preset-env", { targets: { node: "current" } }],
        "@babel/preset-typescript",
    ]
};

7. We configure TypeScript

Since we now have TypeScript code in a tests folder, and have added a the @types/jest package, we need to make a few changes to the tsconfig.json file:

{
    "extends": "@journeyapps/runtime-build/app-package.tsconfig.json",
    "compilerOptions": {
        "outDir": "dist",
        "types": ["jest"]
    },
    "include": [
        "./tests/*.test.ts",
        "./src/**/*.ts"
    ]
}

8. Use a function from the library within a view

Next we want to use the function that we've defined in the package library within a view. The below is an example of how to achieve this, by importing the relevant function(s) from the package into the view's TypeScript.

import { sum } from "@local/unit_test"

// This function is called when the app navigates to this view (using a link)
async function init() {
    // initialize any data here that should be available when the view is shown
}

// This function is called when the user returns to this view from another view
async function resume(from: ResumeFrom) {}

async function calculateSum() {
    const a:number = 2;
    const b:number = 3;

    console.log(`Sum: ${sum(a, b)}`);
    // Sum: 5
}

9. Deploy!

Now when a testing deploy is triggered, not only will the library be built and accessible in your views, but the build will also only succeed if all tests pass.