test: add Jest config and utils tests (#3031)

* test: add Jest config and utils tests

- Added GitHub Actions workflow to run `npm test` on push and pull requests to master.
- Introduced Jest configuration (jest.config.js) for unit testing.
- Added new test files under js/utils for common utility modules:
  - AutoBind.test.js
  - BemHelper.test.js
  - CommonUtils.test.js
  - DataTypeConverterUtils.test.js
  - ExceptionUtils.test.js
- Updated package.json to include Jest test script and dependencies.

use no-package-json install in ci
update deprecated babel plugin

Author: watilde

.github/workflows/ci.yaml

@@ -12,7 +12,7 @@ env:
   DOCKER_IMAGE: ohdsi/atlas
 
 jobs:
-  # Build and test the code
+  # Build the code
   build:
     # The type of runner that the job will run on
     runs-on: ubuntu-latest
@@ -38,6 +38,25 @@ jobs:
       - name: Build code
         run: npm run build
 
+  # Run the test suite
+  test:
+    runs-on: ubuntu-latest
+    needs: build
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Use Node.js 18
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+
+      - name: Install dependencies
+        run: npm install --no-package-lock
+
+      - name: Run tests
+        run: npm test -- --runInBand
+
   # Check that the docker image builds correctly
   # Push to ohdsi/atlas:master for commits on master.
   docker:

build/optimize.js

@@ -26,7 +26,7 @@ const settings = {
 	out: bundleName,
 	onBuildRead(moduleName, path, content) {
 		return babel.transform(content, {
-				plugins: [ "@babel/plugin-proposal-object-rest-spread" ],
+				plugins: [ "@babel/plugin-transform-object-rest-spread" ],
 				presets: [ "@babel/preset-env" ],
 			}
 		).code;
@@ -36,4 +36,4 @@ const settings = {
 	optimize: "none",
 };
 
-r.optimize(settings);
+r.optimize(settings);

jest.config.js

@@ -0,0 +1,25 @@
+const path = require('path');
+const requirejs = require('requirejs');
+
+/** @type {import('jest').Config} */
+module.exports = {
+  testEnvironment: 'node',
+  testMatch: ['**/*.test.js'],
+  moduleFileExtensions: ['js', 'json'],
+  clearMocks: true,
+};
+
+requirejs.config({
+  baseUrl: path.resolve(__dirname, 'js'),
+  nodeRequire: require,
+});
+
+globalThis.requirejsInstance = requirejs;
+globalThis.requireAmd = (deps) =>
+  new Promise((resolve, reject) => {
+    requirejs(
+      deps,
+      (...mods) => resolve(mods.length === 1 ? mods[0] : mods),
+      reject
+    );
+  });

package.json

@@ -10,7 +10,8 @@
     "build:dev": "node build/optimize.js && npm run compress",
     "build:docker": "npm run clean && npm run genversion && npm run build:dev && npm prune --production",
     "compress": "terser ./js/assets/bundle/bundle.js -o ./js/assets/bundle/bundle.js -c --source-map",
-    "genversion": "genversion -s js/version/version.js && r_js -convert js/version js/ && rimraf js/version"
+    "genversion": "genversion -s js/version/version.js && r_js -convert js/version js/ && rimraf js/version",
+    "test": "jest --runInBand --watchman=false"
   },
   "repository": {
     "type": "git",
@@ -34,12 +35,13 @@
   },
   "homepage": "https://github.com/OHDSI/Atlas#readme",
   "devDependencies": {
-    "@babel/core": "7.21.0",
-    "@babel/plugin-proposal-object-rest-spread": "7.20.7",
+    "@babel/core": "7.24.7",
+    "@babel/plugin-transform-object-rest-spread": "7.24.7",
     "@babel/polyfill": "7.12.1",
-    "@babel/preset-env": "7.20.2",
+    "@babel/preset-env": "7.24.7",
     "genversion": "2.2.0",
     "html-document": "0.8.1",
+    "jest": "29.7.0",
     "requirejs": "2.3.6",
     "rimraf": "2.6.2",
     "terser": "5.16.4"

tests/utils/AutoBind.test.js

@@ -0,0 +1,45 @@
+let AutoBind;
+
+beforeAll(async () => {
+	AutoBind = await requireAmd(['utils/AutoBind']);
+});
+
+describe('AutoBind', () => {
+	test('binds prototype methods to the instance context', () => {
+		class Example extends AutoBind() {
+			constructor() {
+				super();
+				this.counter = 1;
+			}
+
+			increment() {
+				return ++this.counter;
+			}
+		}
+
+		const instance = new Example();
+		const { increment } = instance;
+
+		expect(increment()).toBe(2);
+		expect(instance.counter).toBe(2);
+	});
+
+	test('leaves non-function prototype properties untouched', () => {
+		class Sample extends AutoBind() {
+			constructor() {
+				super();
+			}
+
+			getName() {
+				return this.componentName;
+			}
+		}
+
+		Sample.prototype.componentName = 'sample-component';
+
+		const instance = new Sample();
+
+		expect(instance.componentName).toBe('sample-component');
+		expect(instance.getName()).toBe('sample-component');
+	});
+});

tests/utils/BemHelper.test.js

@@ -0,0 +1,26 @@
+let BemHelper;
+
+beforeAll(async () => {
+	BemHelper = await requireAmd(['utils/BemHelper']);
+});
+
+describe('BemHelper', () => {
+	test('builds block classes with modifiers and extra entries', () => {
+		const helper = new BemHelper('atlas-block');
+
+		const classes = helper.run({
+			modifiers: ['active', 'wide'],
+			extra: ['bg-blue'],
+		});
+
+		expect(classes).toBe('atlas-block atlas-block--active atlas-block--wide bg-blue');
+	});
+
+	test('builds element classes from positional arguments', () => {
+		const helper = new BemHelper('atlas-block');
+
+		const classes = helper.run('item', ['selected', 'highlighted'], 'is-visible');
+
+		expect(classes).toBe('atlas-block__item atlas-block__item--selected atlas-block__item--highlighted is-visible');
+	});
+});

tests/utils/CommonUtils.test.js

@@ -0,0 +1,114 @@
+const appConfigStub = {
+	commonDataTableOptions: {
+		pageLength: {
+			XS: 5,
+			M: 25,
+		},
+		lengthMenu: {
+			XS: [[5, 10], ['5', '10']],
+			M: [[10, 25, 50], ['10', '25', '50']],
+		},
+	},
+};
+
+let commonUtils;
+let ko;
+let appConfig;
+
+beforeAll(() => {
+	if (!requirejsInstance.defined('atlas-state')) {
+		requirejsInstance.define('atlas-state', [], () => ({
+			selectedConceptsIndex: {},
+			localeSettings: {},
+		}));
+	}
+	if (!requirejsInstance.defined('appConfig')) {
+		requirejsInstance.define('appConfig', [], () => appConfigStub);
+	}
+	if (!requirejsInstance.defined('pages/Page')) {
+		requirejsInstance.define('pages/Page', [], () => class MockPage {});
+	}
+	if (!requirejsInstance.defined('services/MomentAPI')) {
+		requirejsInstance.define('services/MomentAPI', [], () => ({
+			DESIGN_DATE_TIME_FORMAT: 'YYYY-MM-DD H:mm',
+			formatDateTimeWithFormat: (value, format) => `${value}:${format}`,
+		}));
+	}
+	if (!requirejsInstance.defined('const')) {
+		requirejsInstance.define('const', [], () => ({
+			maxEntityNameLength: 255,
+		}));
+	}
+});
+
+beforeAll(async () => {
+	[commonUtils, ko, appConfig] = await requireAmd(['utils/CommonUtils', 'knockout', 'appConfig']);
+});
+
+describe('CommonUtils', () => {
+	test('normalizeUrl combines segments without duplicate slashes', () => {
+		expect(commonUtils.normalizeUrl('/path/', '/to/', 'resource')).toBe('/path/to/resource');
+	});
+
+	test('cartesian produces all permutations across multiple arrays', () => {
+		const result = commonUtils.cartesian([1, 2], ['a'], ['x', 'y']);
+		expect(result).toEqual([
+			[1, 'a', 'x'],
+			[1, 'a', 'y'],
+			[2, 'a', 'x'],
+			[2, 'a', 'y'],
+		]);
+	});
+
+	test('escapeTooltip escapes both single and double quotes', () => {
+		const escaped = commonUtils.escapeTooltip(`Bob's "quote"`);
+		expect(escaped).toBe(`Bob\\'s "quote"`);
+	});
+
+	test('getSelectedConcepts returns copies of selected items without selection flag', () => {
+		const concepts = ko.observableArray([
+			{ id: 1, name: 'A', isSelected: () => true },
+			{ id: 2, name: 'B', isSelected: () => false },
+		]);
+
+		const result = commonUtils.getSelectedConcepts(concepts);
+		expect(result).toEqual([{ id: 1, name: 'A' }]);
+		expect(result[0]).not.toHaveProperty('isSelected');
+	});
+
+	test('clearConceptsSelectionState resets observable selection flags', () => {
+		const first = { id: 1, isSelected: ko.observable(true) };
+		const second = { id: 2, isSelected: ko.observable(false) };
+		const conceptList = ko.observableArray([first, second]);
+
+		commonUtils.clearConceptsSelectionState(conceptList);
+
+		expect(first.isSelected()).toBe(false);
+		expect(second.isSelected()).toBe(false);
+	});
+
+	test('buildConceptSetItems merges shared options into each entry', () => {
+		const options = ko.observable({
+			includeDescendants: true,
+			isExcluded: false,
+		});
+		const concepts = [
+			{ conceptId: 1 },
+			{ conceptId: 2 },
+		];
+
+		const items = commonUtils.buildConceptSetItems(concepts, options);
+
+		expect(items).toEqual([
+			{ concept: concepts[0], includeDescendants: true, isExcluded: false },
+			{ concept: concepts[1], includeDescendants: true, isExcluded: false },
+		]);
+	});
+
+	test('getTableOptions returns variant specific datatable preferences', () => {
+		expect(commonUtils.getTableOptions('XS')).toEqual({
+			pageLength: appConfig.commonDataTableOptions.pageLength.XS,
+			lengthMenu: appConfig.commonDataTableOptions.lengthMenu.XS,
+		});
+	});
+});

tests/utils/DataTypeConverterUtils.test.js

@@ -0,0 +1,29 @@
+let utils;
+
+beforeAll(async () => {
+	utils = await requireAmd(['utils/DataTypeConverterUtils']);
+});
+
+describe('DataTypeConverterUtils', () => {
+	test('splits comma delimited values into arrays and numbers', () => {
+		expect(utils.commaDelimitedListToArray('A,B,C')).toEqual(['A', 'B', 'C']);
+		expect(utils.commaDelimitedListToArray('')).toEqual([]);
+
+		expect(utils.commaDelimitedListToNumericArray('1,2,3')).toEqual([1, 2, 3]);
+	});
+
+	test('converts comma delimited percents into normalized fractions', () => {
+		expect(utils.commaDelimitedListToPercentArray('50,1,0.25')).toEqual([0.5, 0.01, 0.25]);
+		expect(utils.percentArrayToCommaDelimitedList([0.5, 0.01, 2])).toBe('50,1,2');
+	});
+
+	test('converts to and from YYYYMMDD R date format', () => {
+		const date = new Date(2023, 4, 7); // Month is 0-based
+		expect(utils.convertToDateForR(date)).toBe('20230507');
+
+		const converted = utils.convertFromRDateToDate('20230507');
+		expect(converted.getFullYear()).toBe(2023);
+		expect(converted.getMonth()).toBe(4);
+		expect(converted.getDate()).toBe(7);
+	});
+});

tests/utils/ExceptionUtils.test.js

@@ -0,0 +1,24 @@
+let exceptionUtils;
+
+beforeAll(async () => {
+	exceptionUtils = await requireAmd(['utils/ExceptionUtils']);
+});
+
+describe('ExceptionUtils', () => {
+	test('translates 403 errors into a permission message', () => {
+		expect(exceptionUtils.translateException({ status: 403 })).toBe('You have insufficient permissions!');
+	});
+
+	test('translates other errors into a generic message', () => {
+		expect(exceptionUtils.translateException({ status: 500 })).toBe('Oops, Something went wrong!');
+	});
+
+	test('extracts messages from server payloads', () => {
+		const payload = { data: { payload: { message: 'Something broke' } } };
+		expect(exceptionUtils.extractServerMessage(payload)).toBe('Something broke');
+	});
+
+	test('falls back to default server message when payload missing', () => {
+		expect(exceptionUtils.extractServerMessage({})).toBe('Error! Please see server logs for details.');
+	});
+});