HPC-8232, HPC-7811, HPC-8130 - setup testing environment with jest and docker

.github/workflows/ci.yml

@@ -21,3 +21,17 @@ jobs:
         run: npm run check-types
       - name: Linting checks
         run: npm run lint
+  unit-tests:
+    name: Unit Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - name: Install packages
+        run: yarn install --frozen-lockfile
+      - name: Run Unit Tests
+        run: ./bin/test.sh

.gitignore

@@ -4,6 +4,4 @@
 /index.d.ts
 /yarn-error.log
 package-lock.json
-
-# IDE artifacts
-.vscode
+tests/data/*

.vscode/launch.json

@@ -0,0 +1,19 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Debug Jest Tests",
+      "type": "node",
+      "preLaunchTask": "start-containers",
+      "request": "launch",
+      "runtimeArgs": [
+        "--inspect-brk",
+        "${workspaceRoot}/node_modules/.bin/jest",
+        "--runInBand",
+        "--detectOpenHandles"
+      ],
+      "console": "integratedTerminal",
+      "internalConsoleOptions": "neverOpen"
+    }
+  ]
+}

.vscode/tasks.json

@@ -0,0 +1,13 @@
+{
+  // See https://go.microsoft.com/fwlink/?LinkId=733558
+  // for the documentation about the tasks.json format
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "start-containers",
+      "type": "shell",
+      "command": "${workspaceRoot}/bin/test.sh",
+      "args": ["-oc"]
+    }
+  ]
+}

README.md

@@ -34,6 +34,29 @@ particular:
 If you are contributing to the development of this library,
 more information can be found in our [CONTRIBUTING](CONTRIBUTING.md) document.
 
+## Testing
+
+Unit tests are essential for the stability of the project. They should be written
+using `ContextProvider` singleton, which gives access to models.
+
+To avoid the need for providing tables to clear in each test suite, we use
+transaction approach. There is `getTransaction` utility function and all
+tests should access DB using the transaction, which is reverted after each test case.
+
+### Running the tests
+
+The test can be run with the bash script: `bin/test.sh`
+
+This will compose up the docker containers needed to run the tests, then will run the test suites.
+After the tests, will set down the containers.
+
+### Debug the tests
+
+Assuming the use of VSCode, you can find two files inside `.vscode` folder.
+These tasks describe the behaviour needed to debug the tests.
+
+Just simply add the breakpoints in the code editor and run 'Debug Jest Tests' inside 'Debug and Run' tab.
+
 ## License
 
 Copyright 2020 United Nations Office for the Coordination of Humanitarian Affairs

bin/test.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+
+root=$(pwd)
+
+# Global variables
+USAGE="$(basename "$0") [-h] [-oc] [-k] [-w ${ALL_CONFIGS:1}]
+
+where:
+    -oc, --only-containers: Only start docker containers
+    -sc, --stop-containers: Stop docker containers
+    -k, --keep            : Keep Jest runing after the completion of the tests suites
+    -c                    : Run tests with coverage
+    -h, --help            : Show this help text
+    --[a1] [a2]...        : Pass additional arguments to test script"
+KEEP=0
+FORCE_STOP_JEST='--forceExit'
+ONLY_CONTAINERS=0
+COMMAND_ARGS=''
+
+function moveToTestDir {
+  cd ${root}/tests
+}
+
+function moveToRootDir {
+  cd ${root}
+}
+
+# Obtain options
+while [ "$1" != "" ]; do
+  case $1 in
+    -oc | --only-containers )  ONLY_CONTAINERS=1
+                          ;;
+    -sc | --stop-containers )  STOP_CONTAINERS=1
+                          ;;
+    -k | --keep )         KEEP=1
+                          ;;
+    -c)                   shift
+                          COMMAND_ARGS="${COMMAND_ARGS} --coverage"
+                          ;;
+    -h | --help )         echo "$USAGE"
+                          exit
+                          ;;
+    --)                   shift
+                          while [ "$1" != "" ]; do
+                            COMMAND_ARGS="${COMMAND_ARGS} -- $1"
+                            shift
+                          done
+                          ;;
+    * )                   echo "$USAGE"
+                          exit 1
+  esac
+  shift
+done
+
+# STOP_CONTAINERS is a final option
+if [ "$STOP_CONTAINERS" -eq 1 ]; then
+  echo 'Stopping Docker containers'
+  moveToTestDir
+  docker compose down
+  exit 0
+fi
+
+# ONLY_CONTAINERS must be 1 and STOP must be 0
+if [ $ONLY_CONTAINERS -eq 1 ] && [ "$STOP" -eq 1 ]; then
+  echo 'Invalid options - when using option -oc, option -ns must be used as well'
+  echo "$USAGE"
+  exit 1
+fi
+
+echo 'Starting Docker containers'
+moveToTestDir
+docker compose up -d
+
+if [ $ONLY_CONTAINERS -eq 1 ]; then
+  exit 0
+fi
+
+# Run tests
+echo 'Running tests'
+moveToRootDir
+
+if [ $KEEP -eq 0 ]; then
+  FORCE_STOP_JEST=''
+fi
+
+yarn jest "$COMMAND_ARGS" $FORCE_STOP_JEST
+
+if [ $KEEP -eq 0 ]; then
+  # Stop Docker containers
+  echo 'Stopping docker containers'
+  moveToTestDir
+  docker compose down
+fi

jest.config.ts

@@ -0,0 +1,20 @@
+import type { Config } from '@jest/types';
+
+const config: Config.InitialOptions = {
+  verbose: true,
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testPathIgnorePatterns: ['<rootDir>/node_modules/'],
+  testMatch: ['<rootDir>/**/*.spec.ts'],
+  coveragePathIgnorePatterns: ['<rootDir>/node_modules/', '<rootDir>/test/'],
+  clearMocks: true,
+  transform: {
+    '^.+\\.ts?$': 'ts-jest',
+  },
+  transformIgnorePatterns: ['node_modules/(?!(@unocha)/)'],
+  modulePathIgnorePatterns: ['<rootDir>/test/'],
+  setupFilesAfterEnv: ['<rootDir>/tests/test-environment-setup.ts'],
+  testTimeout: 100_000,
+};
+
+export default config;

package.json

@@ -23,15 +23,20 @@
     "knex": "0.21.1",
     "lodash": "^4.17.21",
     "node-fetch": "2.6.9",
-    "pg": "^8.11.3"
+    "pg": "^8.11.3",
+    "ts-node": "^10.9.2"
   },
   "devDependencies": {
+    "@types/jest": "^29.5.12",
     "@types/node": "^20.8.10",
+    "@types/pg": "^8.11.2",
     "@unocha/hpc-repo-tools": "^4.0.0",
     "eslint": "^8.52.0",
     "husky": "^8.0.3",
+    "jest": "^29.7.0",
     "lint-staged": "^15.0.2",
     "prettier": "3.0.3",
+    "ts-jest": "^29.1.2",
     "typescript": "^5.2.2"
   },
   "lint-staged": {

tests/compose.yml

@@ -0,0 +1,12 @@
+services:
+  db:
+    image: postgres:14.8-alpine3.18
+    container_name: hpc-postgres-test-api-core
+    ports:
+      - 6432:5432
+    environment:
+      - POSTGRES_DB=hpc-test
+      - POSTGRES_USER=postgres
+      - POSTGRES_HOST_AUTH_METHOD=trust
+    volumes:
+      - ./migration/schema-2024-02-29.sql:/docker-entrypoint-initdb.d/init.sql