Testing Interfaces

Overview

Testing interfaces in AntelopeJS is crucial to ensure that your modules work as expected, so it doesn't limit refactoring and evolution of your codebase. This guide covers how to create, update, and test interfaces effectively.

Defining tests

Environment setup

To tell AntelopeJS how to run your tests, you need to add a test attribute in the AntelopeJS configuration, usually located in package.json:

{
  "name": "my-module",
  "version": "0.0.1",
  "scripts": {
    "test": "npx tsc && ajs module test"
  },
  "antelopeJs": {
    "test": {
      "project": "src/loader.test.js",
      "folder": "dist/test"
    },
    [...other antelopeJS configs...]
  }
  [...other package.json properties...]
}

In the test configuration, there are two attributes:

• project: This is the entry point for your tests. It should point to a JavaScript file that sets up the testing environment. For this documentation, we will use src/loader.test.js as an example.
• folder: This is the directory where your compiled test files will be generated. For this documentation, we will use dist/test as an example.

Test loader

The test loader is responsible for setting up the testing environment and cleaning up the artifacts that might be left after the tests are run.

It consists of two main parts:

module.exports.setup = async function() { }
module.exports.cleanup = async function() { }

Setup function

Testing requires a list of modules used by the interfaces being tested. This is done by injecting the configuration in the module setup.

module.exports.setup = async function() {
  return {
    cacheFolder: '.antelope/cache',
    modules: {
      local: {                // Module being tested
        source: {
          type: 'local',
          path: '.',
        },
      },
      mongodb: {              // Dependency module
        source: {
          type: 'git',
          remote: '[email protected]:AntelopeJS/mongodb.git',
          branch: 'main',
          installCommand: ['pnpm i', 'npx tsc'],
        },
        config: {
          url: mongod.getUri(),
        },
      },
      //[...other dependencies...]
    },
  }
};

If needed, you can also add additional setup logic, such as starting a MongoDB instance or other services required for your tests.

const { MongoMemoryServer } = require('mongodb-memory-server-core');

let mongod;
module.exports.setup = async function() {
  mongod = await MongoMemoryServer.create();

  //[...dependencies setup ...]
}

Cleanup function

The cleanup function is responsible for cleaning up any resources used during the tests, such as stopping the MongoDB instance.

module.exports.cleanup = async function() {
  await mongod.stop();
};

Writing tests

Place your tests in the src/test directory (or the directory specified in the folder attribute of the AntelopeJS configuration).

Every test file from this directory or subdirectories will be executed by the AntelopeJS test runner.

Tests are written using Mocha to create the test suite, and Chai for assertions.

Here is an example of a simple test file, operations.test.ts:

import { expect } from 'chai';

describe('Math - Basic operations', () => {
  it('add 2 to 10', async () => addTwoToTen());
  it('divide 0 by 0', async () => divideZeroByZero());
});

async function addTwoToTen() {
  const result = 10 + 2;
  expect(result).to.equal(12);
}

async function divideZeroByZero() {
    const result = 0 / 0;
    expect(result).to.be.NaN;
}

Running tests

To run your tests, use the following command:

ajs module test

This command will compile your TypeScript files and execute the tests defined in the src/test directory.

Test output

After running the tests, you will see the output in the console, indicating which tests passed and which failed. The output will look something like this:

  Math - Basic operations
    ✓ add 2 to 10
    ✓ divide 0 by 0

  2 passing (10ms)