@avimate/msfs-jest-utils 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Ivan Slepchenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,170 @@
+# MSFS Unit Test Framework
+
+Unit testing framework for MSFS HTML/JS instruments (Jest + JSDOM).
+
+Фреймворк для unit-тестирования MSFS инструментов с поддержкой DOM через jsdom.
+
+## Особенности
+
+- ✅ **Полная поддержка DOM** - использует jsdom для рендеринга компонентов
+- ✅ **FSComponent.render()** - можно рендерить компоненты и тестировать DOM элементы
+- ✅ **Моки SimVar и Coherent** - полная эмуляция API симулятора
+- ✅ **Jest интеграция** - готовые утилиты для тестирования
+- ✅ **TypeScript поддержка** - полная типизация
+
+## Установка
+
+### As a library (recommended)
+
+```bash
+npm install --save-dev @avimate/msfs-jest-utils
+```
+
+### Local development
+
+```bash
+npm install
+npm run build
+```
+
+## Использование
+
+### Базовый пример
+
+```typescript
+import { TestEnvironment, ComponentTestHelper } from './msfs-unit-test-framework';
+import { MyComponent } from '../html_ui/MyComponent';
+
+describe('MyComponent', () => {
+  let env: TestEnvironment;
+  let helper: ComponentTestHelper;
+
+  beforeEach(() => {
+    env = new TestEnvironment();
+    env.setup();
+    helper = new ComponentTestHelper(env);
+  });
+
+  afterEach(() => {
+    helper.cleanup();
+    env.teardown();
+  });
+
+  test('should render component', () => {
+    const { element } = helper.renderComponent(MyComponent, {
+      value: 42
+    });
+
+    expect(element).toBeTruthy();
+    expect(element.textContent).toContain('42');
+  });
+
+  test('should update when SimVar changes', () => {
+    env.setSimVar('L:MY_VALUE', 'number', 10);
+    
+    const { element } = helper.renderComponent(MyComponent, {
+      valueSource: env.getSubject('L:MY_VALUE', 'number')
+    });
+
+    expect(helper.getTextContent('.value')).toBe('10');
+    
+    env.setSimVar('L:MY_VALUE', 'number', 20);
+    // Wait for subscription update
+    await helper.waitForUpdate(50);
+    
+    expect(helper.getTextContent('.value')).toBe('20');
+  });
+});
+```
+
+### Тестирование DOM элементов
+
+```typescript
+test('should have correct CSS classes', () => {
+  const { element } = helper.renderComponent(MyComponent, {});
+  
+  expect(helper.hasClass('.my-component', 'active')).toBe(true);
+  expect(helper.getAttribute('.my-component', 'data-state')).toBe('ready');
+});
+
+test('should apply styles correctly', () => {
+  const { element } = helper.renderComponent(MyComponent, {
+    width: 100,
+    height: 200
+  });
+  
+  expect(helper.getStyle('.my-component', 'width')).toBe('100px');
+});
+```
+
+### Работа с SimVar
+
+```typescript
+test('should read SimVar values', () => {
+  env.setSimVar('L:TEST_VALUE', 'number', 42);
+  
+  const value = env.getSimVar('L:TEST_VALUE', 'number');
+  expect(value).toBe(42);
+});
+
+test('should track SimVar access', () => {
+  env.setSimVar('L:TEST', 'number', 10);
+  SimVar.GetSimVarValue('L:TEST', 'number');
+  
+  const log = env.getSimVarAccessLog();
+  expect(log).toHaveLength(1);
+  expect(log[0].operation).toBe('get');
+});
+```
+
+## API
+
+### TestEnvironment
+
+- `setup()` - настройка тестового окружения
+- `teardown()` - очистка после тестов
+- `reset()` - сброс моков
+- `setSimVar(name, unit, value)` - установить SimVar
+- `getSimVar(name, unit)` - получить SimVar
+- `getDocument()` - получить jsdom document
+- `getWindow()` - получить jsdom window
+
+### ComponentTestHelper
+
+- `renderComponent(ComponentClass, props)` - рендерить компонент
+- `querySelector(selector)` - найти элемент
+- `getTextContent(selector)` - получить текст
+- `hasClass(selector, className)` - проверить класс
+- `getAttribute(selector, attrName)` - получить атрибут
+- `getStyle(selector, property)` - получить стиль
+- `waitForUpdate(ms)` - подождать обновления
+- `cleanup()` - очистка
+
+## Структура
+
+```
+msfs-unit-test-framework/
+├── src/
+│   ├── mocks/
+│   │   ├── SimVarMock.ts      # Мок SimVar API
+│   │   ├── CoherentMock.ts     # Мок Coherent API
+│   │   └── index.ts
+│   ├── test-utils/
+│   │   ├── TestEnvironment.ts  # Настройка окружения
+│   │   ├── ComponentTestHelper.ts # Утилиты для компонентов
+│   │   └── index.ts
+│   ├── setupTests.ts           # Jest setup
+│   └── index.ts                # Главный экспорт
+├── tests/                      # Примеры тестов
+├── jest.config.js
+├── tsconfig.json
+└── package.json
+```
+
+## Примеры
+
+Смотрите папку `tests/` для примеров использования.
+
+
+
+

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * MSFS Unit Test Framework
+ *
+ * A comprehensive testing framework for MSFS HTML/JS instruments.
+ * Supports DOM testing via jsdom and FSComponent.render()
+ */
+export * from './mocks';
+export * from './test-utils';

package/dist/index.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * MSFS Unit Test Framework
+ *
+ * A comprehensive testing framework for MSFS HTML/JS instruments.
+ * Supports DOM testing via jsdom and FSComponent.render()
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./mocks"), exports);
+__exportStar(require("./test-utils"), exports);

package/dist/mocks/CoherentMock.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Mock implementation of Coherent Browser API for testing MSFS instruments.
+ *
+ * Coherent is the embedded browser used by MSFS. This mock provides:
+ * - Coherent.call() for calling simulator functions
+ * - Event system simulation
+ * - Browser API compatibility
+ */
+export interface CoherentCall {
+    method: string;
+    args: any[];
+    timestamp: number;
+    resolve?: (value: any) => void;
+    reject?: (error: any) => void;
+}
+/**
+ * Mock Coherent Browser implementation
+ */
+export declare class CoherentMock {
+    private static instance;
+    private callHistory;
+    private eventListeners;
+    private callHandlers;
+    private maxHistorySize;
+    private constructor();
+    /**
+     * Get singleton instance
+     */
+    static getInstance(): CoherentMock;
+    /**
+     * Initialize default call handlers for common MSFS functions
+     */
+    private initializeDefaultHandlers;
+    /**
+     * Mock Coherent.call() - calls a function in the simulator
+     */
+    call(method: string, ...args: any[]): Promise<any>;
+    /**
+     * Register a handler for a specific Coherent call
+     */
+    registerHandler(method: string, handler: (...args: any[]) => any): void;
+    /**
+     * Trigger an event (simulates simulator events)
+     */
+    triggerEvent(eventName: string, data: any): void;
+    /**
+     * Add event listener
+     */
+    on(eventName: string, callback: (data: any) => void): void;
+    /**
+     * Remove event listener
+     */
+    off(eventName: string, callback: (data: any) => void): void;
+    /**
+     * Get call history
+     */
+    getCallHistory(): CoherentCall[];
+    /**
+     * Get calls for a specific method
+     */
+    getCallsForMethod(method: string): CoherentCall[];
+    /**
+     * Clear call history
+     */
+    clearHistory(): void;
+    /**
+     * Reset all handlers and history
+     */
+    reset(): void;
+}
+/**
+ * Global Coherent mock instance
+ */
+export declare const coherentMock: CoherentMock;

package/dist/mocks/CoherentMock.js

@@ -0,0 +1,148 @@
+"use strict";
+/**
+ * Mock implementation of Coherent Browser API for testing MSFS instruments.
+ *
+ * Coherent is the embedded browser used by MSFS. This mock provides:
+ * - Coherent.call() for calling simulator functions
+ * - Event system simulation
+ * - Browser API compatibility
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.coherentMock = exports.CoherentMock = void 0;
+/**
+ * Mock Coherent Browser implementation
+ */
+class CoherentMock {
+    constructor() {
+        this.callHistory = [];
+        this.eventListeners = new Map();
+        this.callHandlers = new Map();
+        this.maxHistorySize = 10000;
+        this.initializeDefaultHandlers();
+    }
+    /**
+     * Get singleton instance
+     */
+    static getInstance() {
+        if (!CoherentMock.instance) {
+            CoherentMock.instance = new CoherentMock();
+        }
+        return CoherentMock.instance;
+    }
+    /**
+     * Initialize default call handlers for common MSFS functions
+     */
+    initializeDefaultHandlers() {
+        // SimVar set handlers - will be connected to SimVarMock in setup
+        this.registerHandler('setValueReg_Number', (id, value) => {
+            // This will be connected to SimVarMock in TestEnvironment
+            return Promise.resolve();
+        });
+        this.registerHandler('setValueReg_String', (id, value) => {
+            return Promise.resolve();
+        });
+        this.registerHandler('setValueReg_Bool', (id, value) => {
+            return Promise.resolve();
+        });
+    }
+    /**
+     * Mock Coherent.call() - calls a function in the simulator
+     */
+    call(method, ...args) {
+        const call = {
+            method,
+            args,
+            timestamp: Date.now()
+        };
+        this.callHistory.push(call);
+        // Keep history size manageable
+        if (this.callHistory.length > this.maxHistorySize) {
+            this.callHistory = this.callHistory.slice(-this.maxHistorySize);
+        }
+        // Check if we have a registered handler
+        const handler = this.callHandlers.get(method);
+        if (handler) {
+            try {
+                const result = handler(...args);
+                return Promise.resolve(result);
+            }
+            catch (error) {
+                return Promise.reject(error);
+            }
+        }
+        // Default: return resolved promise
+        return Promise.resolve(null);
+    }
+    /**
+     * Register a handler for a specific Coherent call
+     */
+    registerHandler(method, handler) {
+        this.callHandlers.set(method, handler);
+    }
+    /**
+     * Trigger an event (simulates simulator events)
+     */
+    triggerEvent(eventName, data) {
+        const listeners = this.eventListeners.get(eventName);
+        if (listeners) {
+            listeners.forEach(listener => {
+                try {
+                    listener(data);
+                }
+                catch (error) {
+                    console.error(`Error in event listener for ${eventName}:`, error);
+                }
+            });
+        }
+    }
+    /**
+     * Add event listener
+     */
+    on(eventName, callback) {
+        if (!this.eventListeners.has(eventName)) {
+            this.eventListeners.set(eventName, new Set());
+        }
+        this.eventListeners.get(eventName).add(callback);
+    }
+    /**
+     * Remove event listener
+     */
+    off(eventName, callback) {
+        const listeners = this.eventListeners.get(eventName);
+        if (listeners) {
+            listeners.delete(callback);
+        }
+    }
+    /**
+     * Get call history
+     */
+    getCallHistory() {
+        return [...this.callHistory];
+    }
+    /**
+     * Get calls for a specific method
+     */
+    getCallsForMethod(method) {
+        return this.callHistory.filter(call => call.method === method);
+    }
+    /**
+     * Clear call history
+     */
+    clearHistory() {
+        this.callHistory = [];
+    }
+    /**
+     * Reset all handlers and history
+     */
+    reset() {
+        this.callHistory = [];
+        this.eventListeners.clear();
+        this.callHandlers.clear();
+        this.initializeDefaultHandlers();
+    }
+}
+exports.CoherentMock = CoherentMock;
+/**
+ * Global Coherent mock instance
+ */
+exports.coherentMock = CoherentMock.getInstance();

package/dist/mocks/GarminSDKAdapter.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Garmin SDK Adapter for Jest testing
+ *
+ * Minimal mocks for @microsoft/msfs-garminsdk required by StormScope components.
+ * Goal: exercise the unit-test framework, not re-implement Garmin SDK.
+ */
+import { DisplayComponent, Subject } from './SDKAdapter';
+export declare enum WeatherRadarOperatingMode {
+    Weather = "Weather"
+}
+export declare enum WeatherRadarScanMode {
+    Horizontal = "Horizontal"
+}
+export declare enum MapTerrainMode {
+    None = "None",
+    Absolute = "Absolute",
+    Relative = "Relative",
+    Ground = "Ground"
+}
+export declare enum MapOrientation {
+    NorthUp = "NorthUp"
+}
+export declare enum UnitsDistanceSettingMode {
+    Nautical = "Nautical"
+}
+export declare const GarminMapKeys: {
+    readonly Units: "Units";
+    readonly Range: "Range";
+    readonly Terrain: "Terrain";
+    readonly Declutter: "Declutter";
+    readonly Orientation: "Orientation";
+    readonly Nexrad: "Nexrad";
+};
+export declare class MapUnitsModule {
+    constructor(_settingManager?: any);
+}
+export declare class MapDeclutterModule {
+}
+export declare class MapNexradModule {
+    readonly showNexrad: Subject<boolean>;
+}
+export declare class MapOrientationModule {
+    readonly orientation: Subject<MapOrientation>;
+}
+export type MapTerrainColorsDefinition = any;
+export declare class MapTerrainModule {
+    readonly terrainMode: Subject<MapTerrainMode>;
+}
+export type MapWxrControllerModules = any;
+export declare class MapWxrController {
+    constructor(_context: any);
+}
+export declare class MapRangeController {
+    private readonly rangeValues;
+    private readonly nominalRange;
+    private rangeIndex;
+    constructor(rangeValues: any[] | undefined, nominalRange: Subject<any>);
+    changeRangeIndex(delta: number): void;
+    setRangeIndex(index: number): void;
+}
+export declare const GarminMapBuilder: {
+    readonly range: symbol;
+    readonly orientation: symbol;
+    readonly declutter: symbol;
+    readonly terrainColors: symbol;
+};
+export interface WeatherRadarProps {
+    bingId: string;
+    bus: any;
+    ref?: any;
+    [key: string]: any;
+}
+export declare class WeatherRadar extends DisplayComponent<WeatherRadarProps> {
+    rootElement: any;
+    update: jest.Mock<any, any, any>;
+    wake: jest.Mock<any, any, any>;
+    sleep: jest.Mock<any, any, any>;
+    render(): any;
+}

package/dist/mocks/GarminSDKAdapter.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * Garmin SDK Adapter for Jest testing
+ *
+ * Minimal mocks for @microsoft/msfs-garminsdk required by StormScope components.
+ * Goal: exercise the unit-test framework, not re-implement Garmin SDK.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WeatherRadar = exports.GarminMapBuilder = exports.MapRangeController = exports.MapWxrController = exports.MapTerrainModule = exports.MapOrientationModule = exports.MapNexradModule = exports.MapDeclutterModule = exports.MapUnitsModule = exports.GarminMapKeys = exports.UnitsDistanceSettingMode = exports.MapOrientation = exports.MapTerrainMode = exports.WeatherRadarScanMode = exports.WeatherRadarOperatingMode = void 0;
+// IMPORTANT: This adapter is part of the test framework and should not depend on
+// the real SDK runtime/types. Import from our own SDKAdapter instead.
+const SDKAdapter_1 = require("./SDKAdapter");
+// -----------------------------
+// Enums / constants
+// -----------------------------
+var WeatherRadarOperatingMode;
+(function (WeatherRadarOperatingMode) {
+    WeatherRadarOperatingMode["Weather"] = "Weather";
+})(WeatherRadarOperatingMode || (exports.WeatherRadarOperatingMode = WeatherRadarOperatingMode = {}));
+var WeatherRadarScanMode;
+(function (WeatherRadarScanMode) {
+    WeatherRadarScanMode["Horizontal"] = "Horizontal";
+})(WeatherRadarScanMode || (exports.WeatherRadarScanMode = WeatherRadarScanMode = {}));
+var MapTerrainMode;
+(function (MapTerrainMode) {
+    MapTerrainMode["None"] = "None";
+    MapTerrainMode["Absolute"] = "Absolute";
+    MapTerrainMode["Relative"] = "Relative";
+    MapTerrainMode["Ground"] = "Ground";
+})(MapTerrainMode || (exports.MapTerrainMode = MapTerrainMode = {}));
+var MapOrientation;
+(function (MapOrientation) {
+    MapOrientation["NorthUp"] = "NorthUp";
+})(MapOrientation || (exports.MapOrientation = MapOrientation = {}));
+var UnitsDistanceSettingMode;
+(function (UnitsDistanceSettingMode) {
+    UnitsDistanceSettingMode["Nautical"] = "Nautical";
+})(UnitsDistanceSettingMode || (exports.UnitsDistanceSettingMode = UnitsDistanceSettingMode = {}));
+exports.GarminMapKeys = {
+    Units: 'Units',
+    Range: 'Range',
+    Terrain: 'Terrain',
+    Declutter: 'Declutter',
+    Orientation: 'Orientation',
+    Nexrad: 'Nexrad',
+};
+// -----------------------------
+// Module stubs used by map manager
+// -----------------------------
+class MapUnitsModule {
+    constructor(_settingManager) { }
+}
+exports.MapUnitsModule = MapUnitsModule;
+class MapDeclutterModule {
+}
+exports.MapDeclutterModule = MapDeclutterModule;
+class MapNexradModule {
+    constructor() {
+        this.showNexrad = SDKAdapter_1.Subject.create(false);
+    }
+}
+exports.MapNexradModule = MapNexradModule;
+class MapOrientationModule {
+    constructor() {
+        this.orientation = SDKAdapter_1.Subject.create(MapOrientation.NorthUp);
+    }
+}
+exports.MapOrientationModule = MapOrientationModule;
+class MapTerrainModule {
+    constructor() {
+        this.terrainMode = SDKAdapter_1.Subject.create(MapTerrainMode.Absolute);
+    }
+}
+exports.MapTerrainModule = MapTerrainModule;
+class MapWxrController {
+    constructor(_context) { }
+}
+exports.MapWxrController = MapWxrController;
+// -----------------------------
+// Range controller used by StormScopeMapManager
+// -----------------------------
+class MapRangeController {
+    constructor(rangeValues = [], nominalRange) {
+        this.rangeValues = rangeValues;
+        this.nominalRange = nominalRange;
+        this.rangeIndex = 0;
+    }
+    changeRangeIndex(delta) {
+        this.setRangeIndex(this.rangeIndex + delta);
+    }
+    setRangeIndex(index) {
+        const clamped = Math.max(0, Math.min(index, this.rangeValues.length - 1));
+        this.rangeIndex = clamped;
+        const val = this.rangeValues[clamped];
+        if (val !== undefined) {
+            this.nominalRange.set(val);
+        }
+    }
+}
+exports.MapRangeController = MapRangeController;
+// -----------------------------
+// GarminMapBuilder tokens (consumed by MapSystemBuilder.with())
+// -----------------------------
+exports.GarminMapBuilder = {
+    range: Symbol('GarminMapBuilder.range'),
+    orientation: Symbol('GarminMapBuilder.orientation'),
+    declutter: Symbol('GarminMapBuilder.declutter'),
+    terrainColors: Symbol('GarminMapBuilder.terrainColors'),
+};
+class WeatherRadar extends SDKAdapter_1.DisplayComponent {
+    constructor() {
+        super(...arguments);
+        this.rootElement = null;
+        this.update = jest.fn();
+        this.wake = jest.fn();
+        this.sleep = jest.fn();
+    }
+    render() {
+        const vnode = SDKAdapter_1.FSComponent.buildComponent('div', {
+            id: `weather-radar-${this.props.bingId}`,
+            class: 'weather-radar',
+        });
+        this.rootElement = vnode?.instance ?? null;
+        return vnode;
+    }
+}
+exports.WeatherRadar = WeatherRadar;

package/dist/mocks/MSFSGlobals.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Mock MSFS global objects and types required by SDK
+ *
+ * These must be set on global object BEFORE any SDK code loads
+ */
+export declare function setupMSFSGlobals(): void;