Migrate to electron-vite and electron-builder

- Switch from deprecated Vue CLI plugin to `electron-vite` (see
  nklayman/vue-cli-plugin-electron-builder#1982)
- Update main/preload scripts to use `index.cjs` filenames to support
  `"type": "module"`, resolving crash issue (#233). This crash was
  related to Electron not supporting ESM (see electron/asar#249,
  electron/electron#21457).
- This commit completes migration to Vite from Vue CLI (#230).

Structure changes:

- Introduce separate folders for Electron's main and preload processes.
- Move TypeHelpers to `src/` to mark tit as accessible by the rest of
  the code.

Config changes:

- Make `vite.config.ts` reusable by Electron configuration.
- On electron-builder, use `--publish` flag instead of `-p` for clarity.

Tests:

- Add log for preload script loading verification.
- Implement runtime environment sanity checks.
- Enhance logging in `check-desktop-runtime-errors`.

.github/workflows/checks.build.yaml

@@ -32,12 +32,15 @@ jobs:
         name: Build
         run: npm run build -- --mode ${{ matrix.mode }}
 
-  # A new job is used due to environments/modes different from Vue CLI, https://github.com/nklayman/vue-cli-plugin-electron-builder/issues/1626
   build-desktop:
     strategy:
       matrix:
         os: [ macos, ubuntu, windows ]
-        mode: [ development, production ] # "test" is not supported https://github.com/nklayman/vue-cli-plugin-electron-builder/issues/1627
+        mode: [
+          # electron-vite modes: https://electron-vite.org/guide/env-and-mode.html#global-env-variables
+          development,  # Used by `dev` command
+          production,   # Used by `build` and `preview` commands
+        ]
       fail-fast: false # Allows to see results from other combinations
     runs-on: ${{ matrix.os }}-latest
     steps:
@@ -51,14 +54,11 @@ jobs:
         name: Install dependencies
         run: npm ci
       -
-        name: Install cross-env
+        name: Prebuild
-        # Used to set NODE_ENV due to https://github.com/nklayman/vue-cli-plugin-electron-builder/issues/1626
+        run: npm run electron:prebuild -- --mode ${{ matrix.mode }}
-        run: npm install --global cross-env
       -
         name: Build
-        run: |-  
+        run: npm run electron:build -- --publish never
-          cross-env-shell NODE_ENV=${{ matrix.mode }}
-          npm run electron:build -- --publish never --mode ${{ matrix.mode }}
 
   create-icons:
     strategy:

.github/workflows/release.desktop.yaml

@@ -13,20 +13,29 @@ jobs:
       fail-fast: false # So publish runs for other OSes if one fails
     runs-on: ${{ matrix.os }}-latest
     steps:
-      - uses: actions/checkout@v2
+      -
+        uses: actions/checkout@v2
         with:
           ref: master # otherwise it defaults to the version tag missing bump commit
           fetch-depth: 0 # fetch all history
-      - name: Checkout to bump commit
+      -
+        name: Checkout to bump commit
         run: git checkout "$(git rev-list "${{ github.event.release.tag_name }}"..master | tail -1)"
-      - name: Setup node
+      -
+        name: Setup node
         uses: ./.github/actions/setup-node
-      - name: Install dependencies
+      -
+        name: Install dependencies
         run: npm ci
-      - name: Run unit tests
+      -
+        name: Run unit tests
         run: npm run test:unit
-      - name: Publish desktop app
+      -
-        run: npm run electron:build -- -p always # https://nklayman.github.io/vue-cli-plugin-electron-builder/guide/recipes.html#upload-release-to-github
+        name: Prebuild
+        run: npm run electron:prebuild
+      -
+        name: Build and publish
+        run: npm run electron:build -- --publish always
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           EP_GH_IGNORE_TIME: true # Otherwise publishing fails if GitHub release is more than 2 hours old https://github.com/electron-userland/electron-builder/issues/2074

docs/development.md

@@ -43,6 +43,13 @@ You could run other types of tests as well, but they may take longer time and ov
   - Start a local web server that serves the built solution from `./dist`.
   - 💡 Run `npm run build` before `npm run preview`.
 
+**Desktop apps:**
+
+- `npm run electron:dev`: The command will build the main process and preload scripts source code, and start a dev server for the renderer, and start the Electron app.
+- `npm run electron:preview`: The command will build the main process, preload scripts and renderer source code, and start the Electron app to preview.
+- `npm run electron:prebuild`: The command will build the main process, preload scripts and renderer source code. Usually before packaging the Electron application, you need to execute this command.
+- `npm run electron:build`: Prebuilds the Electron application, packages and publishes it through `electron-builder`.
+
 **Docker:**
 
 1. Build: `docker build -t undergroundwires/privacy.sexy:latest .`

docs/presentation.md

@@ -24,8 +24,10 @@ The presentation layer uses an event-driven architecture for bidirectional react
       - [**`main.scss`**](./../src/presentation/assets/styles/main.scss): Main Sass file, imported by other components as single entrypoint.
   - [**`main.ts`**](./../src/presentation/main.ts): Starts Vue app.
   - [**`electron/`**](./../src/presentation/electron/): Contains Electron code.
-    - [**`main.ts`**](./../src/presentation/main.ts): Starts Electron app.
+    - [`/main/` **`index.ts`**](./../src/presentation/main.ts): Main entry for Electron, managing application windows and lifecycle events.
+    - [`/preload/` **`index.ts`**](./../src/presentation/main.ts): Script executed before the renderer, securing Node.js features for renderer use.
 - [**`/vite.config.ts`**](./../vite.config.ts): Contains Vite configurations for building web application.
+- [**`/electron.vite.config.ts`**](./../electron.vite.config.ts): Contains Vite configurations for building desktop applications.
 - [**`/postcss.config.cjs`**](./../postcss.config.cjs): Contains PostCSS configurations for Vite.
 
 ## Visual design best-practices

electron-builder.yml

@@ -0,0 +1,31 @@
+# -------
+# Windows
+# -------
+win:
+  target: nsis
+nsis:
+  artifactName: ${name}-${version}-Setup.${ext}
+
+# -----
+# Linux
+# -----
+linux:
+  target: AppImage
+appImage:
+  artifactName: ${name}-${version}.${ext}
+
+# -----
+# macOS
+# -----
+mac:
+  target: dmg
+dmg:
+  artifactName: ${name}-${version}.${ext}
+
+# ----------------
+# Publish options
+# ----------------
+publish:
+  provider: 'github'
+  vPrefixedTagName: false # default: true
+  releaseType: release # default: draft

electron.vite.config.ts

@@ -0,0 +1,69 @@
+import { resolve } from 'path';
+import { mergeConfig, UserConfig } from 'vite';
+import { defineConfig, externalizeDepsPlugin } from 'electron-vite';
+import { getAliasesFromTsConfig, getClientEnvironmentVariables } from './vite-config-helper';
+import { createVueConfig } from './vite.config';
+
+const MAIN_ENTRY_FILE = resolvePathFromProjectRoot('src/presentation/electron/main/index.ts');
+const PRELOAD_ENTRY_FILE = resolvePathFromProjectRoot('src/presentation/electron/preload/index.ts');
+const WEB_INDEX_HTML_PATH = resolvePathFromProjectRoot('src/presentation/index.html');
+const DIST_DIR = resolvePathFromProjectRoot('dist_electron/');
+
+export default defineConfig({
+  main: getSharedElectronConfig({
+    distDirSubfolder: 'main',
+    entryFilePath: MAIN_ENTRY_FILE,
+  }),
+  preload: getSharedElectronConfig({
+    distDirSubfolder: 'preload',
+    entryFilePath: PRELOAD_ENTRY_FILE,
+  }),
+  renderer: mergeConfig(
+    createVueConfig({
+      supportLegacyBrowsers: false,
+    }),
+    {
+      build: {
+        outDir: resolve(DIST_DIR, 'renderer'),
+        rollupOptions: {
+          input: {
+            index: WEB_INDEX_HTML_PATH,
+          },
+          external: ['os', 'child_process', 'fs', 'path'],
+        },
+      },
+    },
+  ),
+});
+
+function getSharedElectronConfig(options: {
+  readonly distDirSubfolder: string;
+  readonly entryFilePath: string;
+}): UserConfig {
+  return {
+    build: {
+      outDir: resolve(DIST_DIR, options.distDirSubfolder),
+      lib: {
+        entry: options.entryFilePath,
+      },
+      rollupOptions: {
+        output: {
+          entryFileNames: '[name].cjs', // This is needed so `type="module"` works
+        },
+      },
+    },
+    plugins: [externalizeDepsPlugin()],
+    define: {
+      ...getClientEnvironmentVariables(),
+    },
+    resolve: {
+      alias: {
+        ...getAliasesFromTsConfig(),
+      },
+    },
+  };
+}
+
+function resolvePathFromProjectRoot(pathSegment: string) {
+  return resolve(__dirname, pathSegment);
+}

package.json

@@ -17,8 +17,10 @@
     "test:cy:open": "start-server-and-test \"vite --port 7070 --mode production\" http://localhost:7070 \"cypress open --config baseUrl=http://localhost:7070\"",
     "lint": "npm run lint:md && npm run lint:md:consistency && npm run lint:md:relative-urls && npm run lint:eslint && npm run lint:yaml",
     "icons:build": "node scripts/logo-update.js",
-    "electron:build": "vue-cli-service electron:build",
+    "electron:dev": "electron-vite dev",
-    "electron:serve": "vue-cli-service electron:serve",
+    "electron:preview": "electron-vite preview",
+    "electron:prebuild": "electron-vite build",
+    "electron:build": "electron-builder",
     "lint:eslint": "eslint .",
     "lint:md": "markdownlint **/*.md --ignore node_modules",
     "lint:md:consistency": "remark . --frail --use remark-preset-lint-consistent",
@@ -27,7 +29,7 @@
     "postinstall": "electron-builder install-app-deps",
     "postuninstall": "electron-builder install-app-deps"
   },
-  "main": "index.js",
+  "main": "./dist_electron/main/index.cjs",
   "dependencies": {
     "@fortawesome/fontawesome-svg-core": "^6.4.0",
     "@fortawesome/free-brands-svg-icons": "^6.4.0",
@@ -87,15 +89,9 @@
     "typescript": "~4.6.2",
     "vite": "^4.4.9",
     "vitest": "^0.34.2",
-    "vue-cli-plugin-electron-builder": "^3.0.0-alpha.4",
     "vue-tsc": "^1.8.8",
     "yaml-lint": "^1.7.0"
   },
-  "overrides": {
-    "vue-cli-plugin-electron-builder": {
-      "electron-builder": "^24.6.3"
-    }
-  },
   "//devDependencies": {
     "terser": "Used by @vitejs/plugin-legacy for minification",
     "typescript": [

scripts/check-desktop-runtime-errors/app/check-for-errors.js

@@ -2,9 +2,13 @@ import { splitTextIntoLines, indentText } from '../utils/text.js';
 import { die } from '../utils/log.js';
 import { readAppLogFile } from './app-logs.js';
 
-const LOG_ERROR_MARKER = '[error]'; // from electron-log
 const ELECTRON_CRASH_TITLE = 'Error'; // Used by electron for early crashes
-const APP_INITIALIZED_MARKER = '[APP_INIT_SUCCESS]'; // Logged by application on successful initialization
+const LOG_ERROR_MARKER = '[error]'; // from electron-log
+const EXPECTED_LOG_MARKERS = [
+  '[WINDOW_INIT]',
+  '[PRELOAD_INIT]',
+  '[APP_MOUNT_INIT]',
+];
 
 export async function checkForErrors(stderr, windowTitles, projectDir) {
   if (!projectDir) { throw new Error('missing project directory'); }
@@ -19,7 +23,8 @@ async function gatherErrors(stderr, windowTitles, projectDir) {
   const logContent = await readAppLogFile(projectDir);
   return [
     verifyStdErr(stderr),
-    verifyApplicationInitializationLog(logContent),
+    verifyApplicationLogsExist(logContent),
+    ...EXPECTED_LOG_MARKERS.map((marker) => verifyLogMarkerExistsInLogs(logContent, marker)),
     verifyWindowTitle(windowTitles),
     verifyErrorsInLogs(logContent),
   ].filter(Boolean);
@@ -45,17 +50,24 @@ function formatError(error) {
   return message;
 }
 
-function verifyApplicationInitializationLog(logContent) {
+function verifyApplicationLogsExist(logContent) {
   if (!logContent || !logContent.length) {
     return describeError(
       'Missing application logs',
       'Application logs are empty not were not found.',
     );
   }
-  if (!logContent.includes(APP_INITIALIZED_MARKER)) {
+  return undefined;
+}
+
+function verifyLogMarkerExistsInLogs(logContent, marker) {
+  if (!marker) {
+    throw new Error('missing marker');
+  }
+  if (!logContent?.includes(marker)) {
     return describeError(
-      'Unexpected application logs',
+      'Incomplete application logs',
-      `Missing identifier "${APP_INITIALIZED_MARKER}" in application logs.`,
+      `Missing identifier "${marker}" in application logs.`,
     );
   }
   return undefined;
@@ -104,7 +116,7 @@ function verifyErrorsInLogs(logContent) {
 function describeError(reason, description) {
   return {
     reason,
-    description: `${description}\nThis might indicate an early crash or significant runtime issue.`,
+    description: `${description}\n\nThis might indicate an early crash or significant runtime issue.`,
   };
 }
 

scripts/check-desktop-runtime-errors/config.js

@@ -1,7 +1,7 @@
 import { join } from 'path';
 
-export const DESKTOP_BUILD_COMMAND = 'npm run electron:build -- -p never';
+export const DESKTOP_BUILD_COMMAND = 'npm run electron:prebuild && npm run electron:build -- --publish never';
 export const PROJECT_DIR = process.cwd();
-export const DESKTOP_DIST_PATH = join(PROJECT_DIR, 'dist_electron');
+export const DESKTOP_DIST_PATH = join(PROJECT_DIR, 'dist');
 export const APP_EXECUTION_DURATION_IN_SECONDS = 60; // Long enough for CI runners
 export const SCREENSHOT_PATH = join(PROJECT_DIR, 'screenshot.png');

scripts/check-desktop-runtime-errors/utils/npm.js

@@ -15,7 +15,7 @@ export async function npmInstall(projectDir) {
   if (!projectDir) { throw new Error('missing project directory'); }
   const npmModulesPath = join(projectDir, 'node_modules');
   if (!await isDirMissingOrEmpty(npmModulesPath)) {
-    log(`Directory "${npmModulesPath}" exists and has content. Skipping 'npm install'.`);
+    log(`Directory "${npmModulesPath}" exists and has content. Skipping \`npm install\`.`);
     return;
   }
   log('Starting dependency installation...');

src/TypeHelpers.ts

@@ -6,3 +6,6 @@ export type Constructible<T, TArgs extends unknown[] = never> = {
 export type PropertyKeys<T> = {
   [K in keyof T]: T[K] extends (...args: unknown[]) => unknown ? never : K;
 }[keyof T];
+
+export type ConstructorArguments<T> =
+  T extends new (...args: infer U) => unknown ? U : never;

src/application/Parser/ApplicationParser.ts

@@ -8,17 +8,18 @@ import LinuxData from '@/application/collections/linux.yaml';
 import { parseProjectInformation } from '@/application/Parser/ProjectInformationParser';
 import { Application } from '@/domain/Application';
 import { IAppMetadata } from '@/infrastructure/Metadata/IAppMetadata';
-import { ViteAppMetadata } from '@/infrastructure/Metadata/Vite/ViteAppMetadata';
+import { AppMetadataFactory } from '@/infrastructure/Metadata/AppMetadataFactory';
 import { parseCategoryCollection } from './CategoryCollectionParser';
 
 export function parseApplication(
-  parser = parseCategoryCollection,
+  categoryParser = parseCategoryCollection,
-  metadata: IAppMetadata = new ViteAppMetadata(),
+  informationParser = parseProjectInformation,
+  metadata: IAppMetadata = AppMetadataFactory.Current,
   collectionsData = PreParsedCollections,
 ): IApplication {
   validateCollectionsData(collectionsData);
-  const information = parseProjectInformation(metadata);
+  const information = informationParser(metadata);
-  const collections = collectionsData.map((collection) => parser(collection, information));
+  const collections = collectionsData.map((collection) => categoryParser(collection, information));
   const app = new Application(information, collections);
   return app;
 }

src/application/Parser/ProjectInformationParser.ts

@@ -2,14 +2,20 @@ import { IProjectInformation } from '@/domain/IProjectInformation';
 import { ProjectInformation } from '@/domain/ProjectInformation';
 import { IAppMetadata } from '@/infrastructure/Metadata/IAppMetadata';
 import { Version } from '@/domain/Version';
+import { AppMetadataFactory } from '@/infrastructure/Metadata/AppMetadataFactory';
+import { ConstructorArguments } from '@/TypeHelpers';
 
-export function parseProjectInformation(
+export function
-  metadata: IAppMetadata,
+parseProjectInformation(
+  metadata: IAppMetadata = AppMetadataFactory.Current,
+  createProjectInformation: ProjectInformationFactory = (
+    ...args
+  ) => new ProjectInformation(...args),
 ): IProjectInformation {
   const version = new Version(
     metadata.version,
   );
-  return new ProjectInformation(
+  return createProjectInformation(
     metadata.name,
     version,
     metadata.slogan,
@@ -17,3 +23,7 @@ export function parseProjectInformation(
     metadata.homepageUrl,
   );
 }
+
+export type ProjectInformationFactory = (
+  ...args: ConstructorArguments<typeof ProjectInformation>
+) => IProjectInformation;

src/infrastructure/Metadata/AppMetadataFactory.ts

@@ -0,0 +1,16 @@
+import { IAppMetadata } from './IAppMetadata';
+import { ViteAppMetadata } from './Vite/ViteAppMetadata';
+
+export class AppMetadataFactory {
+  public static get Current(): IAppMetadata {
+    if (!this.instance) {
+      this.instance = new ViteAppMetadata();
+    }
+    return this.instance;
+  }
+
+  private static instance: IAppMetadata;
+
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  private constructor() {}
+}

src/infrastructure/RuntimeSanity/ISanityCheckOptions.ts

@@ -0,0 +1,3 @@
+export interface ISanityCheckOptions {
+  readonly validateMetadata: boolean;
+}

src/infrastructure/RuntimeSanity/ISanityValidator.ts

@@ -0,0 +1,6 @@
+import { ISanityCheckOptions } from './ISanityCheckOptions';
+
+export interface ISanityValidator {
+  shouldValidate(options: ISanityCheckOptions): boolean;
+  collectErrors(): Iterable<string>;
+}

src/infrastructure/RuntimeSanity/SanityChecks.ts

@@ -0,0 +1,28 @@
+import { ISanityCheckOptions } from './ISanityCheckOptions';
+import { ISanityValidator } from './ISanityValidator';
+import { MetadataValidator } from './Validators/MetadataValidator';
+
+const SanityValidators: ISanityValidator[] = [
+  new MetadataValidator(),
+];
+
+export function validateRuntimeSanity(
+  options: ISanityCheckOptions,
+  validators: readonly ISanityValidator[] = SanityValidators,
+): void {
+  if (!options) {
+    throw new Error('missing options');
+  }
+  if (!validators?.length) {
+    throw new Error('missing validators');
+  }
+  const errorMessages = validators.reduce((errors, validator) => {
+    if (validator.shouldValidate(options)) {
+      errors.push(...validator.collectErrors());
+    }
+    return errors;
+  }, new Array<string>());
+  if (errorMessages.length > 0) {
+    throw new Error(`Sanity check failed.\n${errorMessages.join('\n---\n')}`);
+  }
+}

src/infrastructure/RuntimeSanity/Validators/MetadataValidator.ts

@@ -0,0 +1,66 @@
+import { IAppMetadata } from '@/infrastructure/Metadata/IAppMetadata';
+import { AppMetadataFactory } from '@/infrastructure/Metadata/AppMetadataFactory';
+import { ISanityCheckOptions } from '../ISanityCheckOptions';
+import { ISanityValidator } from '../ISanityValidator';
+
+export class MetadataValidator implements ISanityValidator {
+  private readonly metadata: IAppMetadata;
+
+  constructor(metadataFactory: () => IAppMetadata = () => AppMetadataFactory.Current) {
+    this.metadata = metadataFactory();
+  }
+
+  public shouldValidate(options: ISanityCheckOptions): boolean {
+    return options.validateMetadata;
+  }
+
+  public* collectErrors(): Iterable<string> {
+    if (!this.metadata) {
+      yield 'missing metadata';
+      return;
+    }
+    const keyValues = capturePropertyValues(this.metadata);
+    if (!Object.keys(keyValues).length) {
+      yield 'Unable to capture metadata key/value pairs';
+      return;
+    }
+    const keysMissingValue = getMissingMetadataKeys(keyValues);
+    if (keysMissingValue.length > 0) {
+      yield `Metadata keys missing: ${keysMissingValue.join(', ')}`;
+    }
+  }
+}
+
+function getMissingMetadataKeys(keyValuePairs: Record<string, unknown>): string[] {
+  return Object.entries(keyValuePairs)
+    .reduce((acc, [key, value]) => {
+      if (!value) {
+        acc.push(key);
+      }
+      return acc;
+    }, new Array<string>());
+}
+
+/**
+ * Captures values of properties and getters from the provided instance.
+ * Necessary because code transformations can make class getters non-enumerable during bundling.
+ * This ensures that even if getters are non-enumerable, their values are still captured and used.
+ */
+function capturePropertyValues(instance: unknown): Record<string, unknown> {
+  const obj: Record<string, unknown> = {};
+  const descriptors = Object.getOwnPropertyDescriptors(instance.constructor.prototype);
+
+  // Capture regular properties from the instance
+  for (const [key, value] of Object.entries(instance)) {
+    obj[key] = value;
+  }
+
+  // Capture getter properties from the instance's prototype
+  for (const [key, descriptor] of Object.entries(descriptors)) {
+    if (typeof descriptor.get === 'function') {
+      obj[key] = descriptor.get.call(instance);
+    }
+  }
+
+  return obj;
+}

src/presentation/components/App.vue

@@ -18,6 +18,7 @@ import TheCodeButtons from '@/presentation/components/Code/CodeButtons/TheCodeBu
 import TheScriptArea from '@/presentation/components/Scripts/TheScriptArea.vue';
 import TheSearchBar from '@/presentation/components/TheSearchBar.vue';
 import { buildContext } from '@/application/Context/ApplicationContextFactory';
+import { validateRuntimeSanity } from '@/infrastructure/RuntimeSanity/SanityChecks';
 import { provideDependencies } from '../bootstrapping/DependencyProvider';
 
 const singletonAppContext = await buildContext();
@@ -32,6 +33,9 @@ export default defineComponent({
   },
   setup() {
     provideDependencies(singletonAppContext); // In Vue 3.0 we can move it to main.ts
+    validateRuntimeSanity({
+      validateMetadata: true,
+    });
   },
 });
 </script>

src/presentation/electron/main/ElectronConfig.ts

@@ -0,0 +1,16 @@
+/**
+ * Abstraction for electron-vite specific logic and other Electron CLI helpers/wrappers.
+ * Allows for agnostic application design and centralizes adjustments when switching wrappers.
+ */
+
+/// <reference types="electron-vite/node" />
+import { join } from 'path';
+import appIcon from '@/presentation/public/icon.png?asset';
+
+export const APP_ICON_PATH = appIcon;
+
+export const RENDERER_URL = process.env.ELECTRON_RENDERER_URL;
+
+export const RENDERER_HTML_PATH = join('file://', __dirname, '../renderer/index.html');
+
+export const PRELOADER_SCRIPT_PATH = join(__dirname, '../preload/index.cjs');

src/presentation/electron/main/Update/ManualUpdater.ts

@@ -6,8 +6,8 @@ import log from 'electron-log';
 import fetch from 'cross-fetch';
 import { ProjectInformation } from '@/domain/ProjectInformation';
 import { OperatingSystem } from '@/domain/OperatingSystem';
-import { Version } from '@/domain/Version';
 import { ViteAppMetadata } from '@/infrastructure/Metadata/Vite/ViteAppMetadata';
+import { Version } from '@/domain/Version';
 import { parseProjectInformation } from '@/application/Parser/ProjectInformationParser';
 import { UpdateProgressBar } from './UpdateProgressBar';
 

src/presentation/electron/main/index.ts

@@ -1,21 +1,17 @@
-// This is main process of Electron, started as first thing when app starts.
+// Initializes Electron's main process, always runs in the background, and manages the main window.
-// This script is running through entire life of the application.
-// It doesn't have any windows which you can see on screen, opens the main window from here.
 
-import path from 'path';
 import {
   app, protocol, BrowserWindow, shell, screen,
 } from 'electron';
-import { createProtocol } from 'vue-cli-plugin-electron-builder/lib';
 import installExtension, { VUEJS_DEVTOOLS } from 'electron-devtools-installer';
 import log from 'electron-log';
+import { validateRuntimeSanity } from '@/infrastructure/RuntimeSanity/SanityChecks';
 import { setupAutoUpdater } from './Update/Updater';
+import {
+  APP_ICON_PATH, PRELOADER_SCRIPT_PATH, RENDERER_HTML_PATH, RENDERER_URL,
+} from './ElectronConfig';
 
-const isDevelopment = process.env.NODE_ENV !== 'production';
+const isDevelopment = !app.isPackaged;
-
-// Path of static assets, magic variable populated by electron
-// eslint-disable-next-line @typescript-eslint/naming-convention, no-underscore-dangle
-declare const __static: string; // https://github.com/electron-userland/electron-webpack/issues/172
 
 // Keep a global reference of the window object, if you don't, the window will
 // be closed automatically when the JavaScript object is garbage collected.
@@ -27,6 +23,9 @@ protocol.registerSchemesAsPrivileged([
 ]);
 
 setupLogger();
+validateRuntimeSanity({
+  validateMetadata: true,
+});
 
 function createWindow() {
   // Create the browser window.
@@ -35,14 +34,11 @@ function createWindow() {
     width: size.width,
     height: size.height,
     webPreferences: {
-      contextIsolation: false, // To reach node https://github.com/nklayman/vue-cli-plugin-electron-builder/issues/1285
+      nodeIntegration: true,
-      // Use pluginOptions.nodeIntegration, leave this alone
+      contextIsolation: false,
-      // See https://nklayman.github.io/vue-cli-plugin-electron-builder/guide/security.html#node-integration
+      preload: PRELOADER_SCRIPT_PATH,
-      nodeIntegration: (process.env
-        .ELECTRON_NODE_INTEGRATION as unknown) as boolean,
     },
-    // https://nklayman.github.io/vue-cli-plugin-electron-builder/guide/recipes.html#set-tray-icon
+    icon: APP_ICON_PATH,
-    icon: path.join(__static, 'icon.png'),
   });
 
   win.setMenuBarVisibility(false);
@@ -83,17 +79,12 @@ app.on('activate', () => {
   }
 });
 
-// This method will be called when Electron has finished
-// initialization and is ready to create browser windows.
-// Some APIs can only be used after this event occurs.
 app.on('ready', async () => {
-  if (isDevelopment && !process.env.IS_TEST) {
+  if (isDevelopment) {
-    // Install Vue Devtools
     try {
       await installExtension(VUEJS_DEVTOOLS);
     } catch (e) {
-      // eslint-disable-next-line no-console
+      log.error('Vue Devtools failed to install:', e.toString());
-      console.error('Vue Devtools failed to install:', e.toString());
     }
   }
   createWindow();
@@ -115,22 +106,19 @@ if (isDevelopment) {
 }
 
 function loadApplication(window: BrowserWindow) {
-  if (process.env.WEBPACK_DEV_SERVER_URL) {
+  if (RENDERER_URL) { // Populated in a dev server during development
-    // Load the url of the dev server if in development mode
+    loadUrlWithNodeWorkaround(win, RENDERER_URL);
-    loadUrlWithNodeWorkaround(win, process.env.WEBPACK_DEV_SERVER_URL as string);
+  } else {
-    if (!process.env.IS_TEST) {
+    loadUrlWithNodeWorkaround(win, RENDERER_HTML_PATH);
-      window.webContents.openDevTools();
+  }
-    }
+  if (isDevelopment) {
+    window.webContents.openDevTools();
   } else {
-    createProtocol('app');
-    // Load the index.html when not in development
-    loadUrlWithNodeWorkaround(win, 'app://./index.html');
     const updater = setupAutoUpdater();
     updater.checkForUpdates();
   }
-  // Do not remove [APP_INIT_SUCCESS]; it's a marker used in tests to verify
+  // Do not remove [WINDOW_INIT]; it's a marker used in tests.
-  // app initialization.
+  log.info('[WINDOW_INIT] Main window initialized and content loading.');
-  log.info('[APP_INIT_SUCCESS] Main window initialized and content loading.');
 }
 
 function configureExternalsUrlsOpenBrowser(window: BrowserWindow) {
@@ -158,7 +146,7 @@ function getWindowSize(idealWidth: number, idealHeight: number) {
 
 function setupLogger(): void {
   log.transports.file.level = 'silly';
-  if (!process.env.IS_TEST) {
+  if (!isDevelopment) {
     Object.assign(console, log.functions); // override console.log, console.warn etc.
   }
 }

src/presentation/electron/preload/index.ts

@@ -0,0 +1,11 @@
+// This preload script serves as a placeholder to securely expose Electron APIs to the application.
+// As of now, the application does not utilize any specific Electron APIs through this script.
+import log from 'electron-log';
+import { validateRuntimeSanity } from '@/infrastructure/RuntimeSanity/SanityChecks';
+
+validateRuntimeSanity({
+  validateMetadata: true,
+});
+
+// Do not remove [PRELOAD_INIT]; it's a marker used in tests.
+log.info('[PRELOAD_INIT] Preload script successfully initialized and executed.');

tests/integration/infrastructure/Metadata/Vite/ViteAppMetadata.spec.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect } from 'vitest';
 import { ViteAppMetadata } from '@/infrastructure/Metadata/Vite/ViteAppMetadata';
 import packageJson from '@/../package.json' assert { type: 'json' };
-import { PropertyKeys } from '@tests/shared/TypeHelpers';
+import { PropertyKeys } from '@/TypeHelpers';
 
 describe('ViteAppMetadata', () => {
   describe('populates from package.json', () => {

tests/unit/application/Parser/ApplicationParser.spec.ts

@@ -1,4 +1,3 @@
-/* eslint-disable max-classes-per-file */
 import { describe, it, expect } from 'vitest';
 import type { CollectionData } from '@/application/collections/';
 import { parseProjectInformation } from '@/application/Parser/ProjectInformationParser';
@@ -7,28 +6,28 @@ import { IAppMetadata } from '@/infrastructure/Metadata/IAppMetadata';
 import WindowsData from '@/application/collections/windows.yaml';
 import MacOsData from '@/application/collections/macos.yaml';
 import LinuxData from '@/application/collections/linux.yaml';
-import { IProjectInformation } from '@/domain/IProjectInformation';
-import { ProjectInformation } from '@/domain/ProjectInformation';
-import { ICategoryCollection } from '@/domain/ICategoryCollection';
 import { OperatingSystem } from '@/domain/OperatingSystem';
-import { getEnumValues } from '@/application/Common/Enum';
 import { CategoryCollectionStub } from '@tests/unit/shared/Stubs/CategoryCollectionStub';
 import { CollectionDataStub } from '@tests/unit/shared/Stubs/CollectionDataStub';
 import { getAbsentCollectionTestCases, AbsentObjectTestCases } from '@tests/unit/shared/TestCases/AbsentTests';
 import { AppMetadataStub } from '@tests/unit/shared/Stubs/AppMetadataStub';
+import { AppMetadataFactory } from '@/infrastructure/Metadata/AppMetadataFactory';
+import { CategoryCollectionParserStub } from '@tests/unit/shared/Stubs/CategoryCollectionParserStub';
+import { ProjectInformationParserStub } from '@tests/unit/shared/Stubs/ProjectInformationParserStub';
+import { ProjectInformationStub } from '@tests/unit/shared/Stubs/ProjectInformationStub';
 
 describe('ApplicationParser', () => {
   describe('parseApplication', () => {
-    describe('parser', () => {
+    describe('categoryParser', () => {
       it('returns result from the parser', () => {
         // arrange
         const os = OperatingSystem.macOS;
         const data = new CollectionDataStub();
         const expected = new CategoryCollectionStub()
           .withOs(os);
-        const parser = new CategoryCollectionParserSpy()
+        const parser = new CategoryCollectionParserStub()
-          .setUpReturnValue(data, expected)
+          .withReturnValue(data, expected)
-          .mockParser();
+          .getStub();
         const sut = new ApplicationParserBuilder()
           .withCategoryCollectionParser(parser)
           .withCollectionsData([data]);
@@ -39,20 +38,63 @@ describe('ApplicationParser', () => {
         expect(expected).to.equal(actual);
       });
     });
-    describe('processEnv', () => {
+    describe('project information', () => {
-      it('used to parse expected project information', () => {
+      it('informationParser is used to create application info', () => {
         // arrange
-        const env = new AppMetadataStub();
+        const expectedInformation = new ProjectInformationStub();
-        const expected = parseProjectInformation(env);
+        const informationParserStub = new ProjectInformationParserStub()
-        const parserSpy = new CategoryCollectionParserSpy();
+          .withReturnValue(expectedInformation);
-        const parserMock = parserSpy.mockParser();
         const sut = new ApplicationParserBuilder()
-          .withCategoryCollectionParser(parserMock);
+          .withProjectInformationParser(informationParserStub.getStub());
         // act
         const app = sut.parseApplication();
         // assert
-        expect(expected).to.deep.equal(app.info);
+        const actualInformation = app.info;
-        expect(parserSpy.arguments.map((arg) => arg.info).every((info) => info === expected));
+        expect(expectedInformation).to.deep.equal(actualInformation);
+      });
+      it('informationParser is used to parse collection info', () => {
+        // arrange
+        const expectedInformation = new ProjectInformationStub();
+        const informationParserStub = new ProjectInformationParserStub()
+          .withReturnValue(expectedInformation);
+        const collectionParserStub = new CategoryCollectionParserStub();
+        const sut = new ApplicationParserBuilder()
+          .withProjectInformationParser(informationParserStub.getStub())
+          .withCategoryCollectionParser(collectionParserStub.getStub());
+        // act
+        sut.parseApplication();
+        // assert
+        expect(collectionParserStub.arguments).to.have.length.above(0);
+        const actualyUsedInfos = collectionParserStub.arguments.map((arg) => arg.info);
+        expect(actualyUsedInfos.every((info) => info === expectedInformation));
+      });
+    });
+    describe('metadata', () => {
+      it('used to parse expected metadata', () => {
+        // arrange
+        const expectedMetadata = new AppMetadataStub();
+        const infoParserStub = new ProjectInformationParserStub();
+        // act
+        new ApplicationParserBuilder()
+          .withMetadata(expectedMetadata)
+          .withProjectInformationParser(infoParserStub.getStub())
+          .parseApplication();
+        // assert
+        expect(infoParserStub.arguments).to.have.lengthOf(1);
+        expect(infoParserStub.arguments[0]).to.equal(expectedMetadata);
+      });
+      it('defaults to metadata from factory', () => {
+        // arrange
+        const expectedMetadata = AppMetadataFactory.Current;
+        const infoParserStub = new ProjectInformationParserStub();
+        // act
+        new ApplicationParserBuilder()
+          .withMetadata(undefined) // force using default
+          .withProjectInformationParser(infoParserStub.getStub())
+          .parseApplication();
+        // assert
+        expect(infoParserStub.arguments).to.have.lengthOf(1);
+        expect(infoParserStub.arguments[0]).to.equal(expectedMetadata);
       });
     });
     describe('collectionsData', () => {
@@ -79,12 +121,13 @@ describe('ApplicationParser', () => {
         // act
         for (const testCase of testCases) {
           it(testCase.name, () => {
-            let parserSpy = new CategoryCollectionParserSpy();
+            let categoryParserStub = new CategoryCollectionParserStub();
             for (let i = 0; i < testCase.input.length; i++) {
-              parserSpy = parserSpy.setUpReturnValue(testCase.input[i], testCase.output[i]);
+              categoryParserStub = categoryParserStub
+                .withReturnValue(testCase.input[i], testCase.output[i]);
             }
             const sut = new ApplicationParserBuilder()
-              .withCategoryCollectionParser(parserSpy.mockParser())
+              .withCategoryCollectionParser(categoryParserStub.getStub())
               .withCollectionsData(testCase.input);
             // act
             const app = sut.parseApplication();
@@ -96,14 +139,14 @@ describe('ApplicationParser', () => {
       it('defaults to expected data', () => {
         // arrange
         const expected = [WindowsData, MacOsData, LinuxData];
-        const parserSpy = new CategoryCollectionParserSpy();
+        const categoryParserStub = new CategoryCollectionParserStub();
         const sut = new ApplicationParserBuilder()
           .withCollectionsData(undefined)
-          .withCategoryCollectionParser(parserSpy.mockParser());
+          .withCategoryCollectionParser(categoryParserStub.getStub());
         // act
         sut.parseApplication();
         // assert
-        const actual = parserSpy.arguments.map((args) => args.data);
+        const actual = categoryParserStub.arguments.map((args) => args.data);
         expect(actual).to.deep.equal(expected);
       });
       describe('throws when data is invalid', () => {
@@ -136,10 +179,13 @@ describe('ApplicationParser', () => {
 });
 
 class ApplicationParserBuilder {
-  private categoryCollectionParser: CategoryCollectionParserType = new CategoryCollectionParserSpy()
+  private categoryCollectionParser
-    .mockParser();
+  : CategoryCollectionParserType = new CategoryCollectionParserStub().getStub();
 
-  private environment: IAppMetadata = new AppMetadataStub();
+  private projectInformationParser
+  : typeof parseProjectInformation = new ProjectInformationParserStub().getStub();
+
+  private metadata: IAppMetadata = new AppMetadataStub();
 
   private collectionsData: CollectionData[] = [new CollectionDataStub()];
 
@@ -150,10 +196,17 @@ class ApplicationParserBuilder {
     return this;
   }
 
-  public withEnvironment(
+  public withProjectInformationParser(
+    projectInformationParser: typeof parseProjectInformation,
+  ): this {
+    this.projectInformationParser = projectInformationParser;
+    return this;
+  }
+
+  public withMetadata(
     environment: IAppMetadata,
   ): this {
-    this.environment = environment;
+    this.metadata = environment;
     return this;
   }
 
@@ -165,39 +218,9 @@ class ApplicationParserBuilder {
   public parseApplication(): ReturnType<typeof parseApplication> {
     return parseApplication(
       this.categoryCollectionParser,
-      this.environment,
+      this.projectInformationParser,
+      this.metadata,
       this.collectionsData,
     );
   }
 }
-
-class CategoryCollectionParserSpy {
-  public arguments = new Array<{
-    data: CollectionData,
-    info: ProjectInformation,
-  }>();
-
-  private returnValues = new Map<CollectionData, ICategoryCollection>();
-
-  public setUpReturnValue(
-    data: CollectionData,
-    collection: ICategoryCollection,
-  ): CategoryCollectionParserSpy {
-    this.returnValues.set(data, collection);
-    return this;
-  }
-
-  public mockParser(): CategoryCollectionParserType {
-    return (data: CollectionData, info: IProjectInformation) => {
-      this.arguments.push({ data, info });
-      if (this.returnValues.has(data)) {
-        return this.returnValues.get(data);
-      }
-      // Get next OS with a unique OS so mock does not result in an invalid app due to duplicated OS
-      // collections.
-      const currentRun = this.arguments.length - 1;
-      const nextOs = getEnumValues(OperatingSystem)[currentRun];
-      return new CategoryCollectionStub().withOs(nextOs);
-    };
-  }
-}

tests/unit/application/Parser/ProjectInformationParser.spec.ts

@@ -1,60 +1,111 @@
 import { describe, it, expect } from 'vitest';
-import { parseProjectInformation } from '@/application/Parser/ProjectInformationParser';
+import { parseProjectInformation, ProjectInformationFactory } from '@/application/Parser/ProjectInformationParser';
-import { IProjectInformation } from '@/domain/IProjectInformation';
 import { AppMetadataStub } from '@tests/unit/shared/Stubs/AppMetadataStub';
+import { PropertyKeys } from '@/TypeHelpers';
+import { ProjectInformationStub } from '@tests/unit/shared/Stubs/ProjectInformationStub';
+import { Version } from '@/domain/Version';
 
 describe('ProjectInformationParser', () => {
   describe('parseProjectInformation', () => {
-    interface IEnvironmentParsingTestCase {
+    it('returns expected information', () => {
-      readonly testCaseName: string;
+      // arrange
-      readonly setMetadata: (appMetadataStub: AppMetadataStub, value: string) => AppMetadataStub;
+      const expectedInformation = new ProjectInformationStub();
-      readonly expectedValue: string;
+      const factoryMock = () => expectedInformation;
-      readonly getActualValue: (info: IProjectInformation) => string;
+      // act
-    }
+      const actualInformation = parseProjectInformation(new AppMetadataStub(), factoryMock);
-    const testCases: readonly IEnvironmentParsingTestCase[] = [
+      // assert
-      {
+      expect(expectedInformation).to.equal(actualInformation);
-        testCaseName: 'version',
+    });
-        setMetadata: (metadata, value) => metadata.withVersion(value),
+    describe('default behavior does not throw', () => {
-        expectedValue: '0.11.3',
+      it('without metadataFactory', () => {
-        getActualValue: (info) => info.version.toString(),
+        // arrange
-      },
+        const metadataFactory = undefined;
-      {
+        const informationFactory = new ProjectInformationFactoryStub().getStub();
-        testCaseName: 'name',
-        setMetadata: (metadata, value) => metadata.witName(value),
-        expectedValue: 'expected-app-name',
-        getActualValue: (info) => info.name,
-      },
-      {
-        testCaseName: 'homepage',
-        setMetadata: (metadata, value) => metadata.withHomepageUrl(value),
-        expectedValue: 'https://expected.sexy',
-        getActualValue: (info) => info.homepage,
-      },
-      {
-        testCaseName: 'repositoryUrl',
-        setMetadata: (metadata, value) => metadata.withRepositoryUrl(value),
-        expectedValue: 'https://expected-repository.url',
-        getActualValue: (info) => info.repositoryUrl,
-      },
-      {
-        testCaseName: 'slogan',
-        setMetadata: (metadata, value) => metadata.withSlogan(value),
-        expectedValue: 'expected-slogan',
-        getActualValue: (info) => info.slogan,
-      },
-    ];
-    for (const {
-      expectedValue, testCaseName, setMetadata, getActualValue,
-    } of testCases) {
-      it(testCaseName, () => {
         // act
-        const metadata = setMetadata(new AppMetadataStub(), expectedValue);
+        const act = () => parseProjectInformation(metadataFactory, informationFactory);
-        // act
+        // expectS
-        const info = parseProjectInformation(metadata);
+        expect(act).to.not.throw();
-        // assert
-        const actual = getActualValue(info);
-        expect(actual).to.be.equal(expectedValue);
       });
-    }
+      it('without projectInformationFactory', () => {
+        // arrange
+        const metadataFactory = new AppMetadataStub();
+        const informationFactory = undefined;
+        // act
+        const act = () => parseProjectInformation(metadataFactory, informationFactory);
+        // expect
+        expect(act).to.not.throw();
+      });
+    });
+    describe('parses metadata to project information', () => {
+      interface IMetadataTestCase {
+        readonly setMetadata: (appMetadataStub: AppMetadataStub, value: string) => AppMetadataStub;
+        readonly expectedValue: string;
+        readonly getActualValue: (info: ProjectInformationFactoryStub) => string;
+      }
+      const testCases: { [K in PropertyKeys<ProjectInformationFactoryStub>]: IMetadataTestCase } = {
+        name: {
+          setMetadata: (metadata, value) => metadata.witName(value),
+          expectedValue: 'expected-app-name',
+          getActualValue: (info) => info.name,
+        },
+        version: {
+          setMetadata: (metadata, value) => metadata.withVersion(value),
+          expectedValue: '0.11.3',
+          getActualValue: (info) => info.version.toString(),
+        },
+        slogan: {
+          setMetadata: (metadata, value) => metadata.withSlogan(value),
+          expectedValue: 'expected-slogan',
+          getActualValue: (info) => info.slogan,
+        },
+        repositoryUrl: {
+          setMetadata: (metadata, value) => metadata.withRepositoryUrl(value),
+          expectedValue: 'https://expected-repository.url',
+          getActualValue: (info) => info.repositoryUrl,
+        },
+        homepage: {
+          setMetadata: (metadata, value) => metadata.withHomepageUrl(value),
+          expectedValue: 'https://expected.sexy',
+          getActualValue: (info) => info.homepage,
+        },
+      };
+      Object.entries(testCases).forEach(([propertyName, {
+        expectedValue, setMetadata, getActualValue,
+      }]) => {
+        it(propertyName, () => {
+          // act
+          const metadata = setMetadata(new AppMetadataStub(), expectedValue);
+          const factoryStub = new ProjectInformationFactoryStub();
+          // act
+          parseProjectInformation(metadata, factoryStub.getStub());
+          // assert
+          const actual = getActualValue(factoryStub);
+          expect(actual).to.be.equal(expectedValue);
+        });
+      });
+    });
   });
 });
+
+class ProjectInformationFactoryStub {
+  public name: string;
+
+  public version: Version;
+
+  public slogan: string;
+
+  public repositoryUrl: string;
+
+  public homepage: string;
+
+  public getStub(): ProjectInformationFactory {
+    return (name, version, slogan, repositoryUrl, homepage) => {
+      this.name = name;
+      this.version = version;
+      this.slogan = slogan;
+      this.repositoryUrl = repositoryUrl;
+      this.homepage = homepage;
+      return new ProjectInformationStub();
+    };
+  }
+}

tests/unit/domain/ProjectInformation.spec.ts

@@ -4,7 +4,7 @@ import { OperatingSystem } from '@/domain/OperatingSystem';
 import { EnumRangeTestRunner } from '@tests/unit/application/Common/EnumRangeTestRunner';
 import { VersionStub } from '@tests/unit/shared/Stubs/VersionStub';
 import { Version } from '@/domain/Version';
-import { PropertyKeys } from '@tests/shared/TypeHelpers';
+import { PropertyKeys } from '@/TypeHelpers';
 
 describe('ProjectInformation', () => {
   describe('retrieval of property values', () => {

tests/unit/infrastructure/Metadata/AppMetadataFactory.spec.ts

@@ -0,0 +1,15 @@
+import {
+  describe,
+} from 'vitest';
+import { itIsSingleton } from '@tests/unit/shared/TestCases/SingletonTests';
+import { AppMetadataFactory } from '@/infrastructure/Metadata/AppMetadataFactory';
+import { ViteAppMetadata } from '@/infrastructure/Metadata/Vite/ViteAppMetadata';
+
+describe('AppMetadataFactory', () => {
+  describe('instance', () => {
+    itIsSingleton({
+      getter: () => AppMetadataFactory.Current,
+      expectedType: ViteAppMetadata,
+    });
+  });
+});

tests/unit/infrastructure/Metadata/ViteAppMetadata.spec.ts

@@ -3,7 +3,7 @@ import {
 } from 'vitest';
 import { ViteAppMetadata } from '@/infrastructure/Metadata/Vite/ViteAppMetadata';
 import { VITE_ENVIRONMENT_KEYS } from '@/infrastructure/Metadata/Vite/ViteEnvironmentKeys';
-import { PropertyKeys } from '@tests/shared/TypeHelpers';
+import { PropertyKeys } from '@/TypeHelpers';
 
 describe('ViteAppMetadata', () => {
   describe('reads values from import.meta.env', () => {

tests/unit/infrastructure/RuntimeSanity/SanityChecks.spec.ts

@@ -0,0 +1,155 @@
+import { describe, it, expect } from 'vitest';
+import { validateRuntimeSanity } from '@/infrastructure/RuntimeSanity/SanityChecks';
+import { ISanityCheckOptions } from '@/infrastructure/RuntimeSanity/ISanityCheckOptions';
+import { SanityCheckOptionsStub } from '@tests/unit/shared/Stubs/SanityCheckOptionsStub';
+import { ISanityValidator } from '@/infrastructure/RuntimeSanity/ISanityValidator';
+import { SanityValidatorStub } from '@tests/unit/shared/Stubs/SanityValidatorStub';
+import { itEachAbsentObjectValue } from '@tests/unit/shared/TestCases/AbsentTests';
+
+describe('SanityChecks', () => {
+  describe('validateRuntimeSanity', () => {
+    describe('parameter validation', () => {
+      describe('options', () => {
+        itEachAbsentObjectValue((absentValue) => {
+          // arrange
+          const expectedError = 'missing options';
+          const context = new TestContext()
+            .withOptions(absentValue);
+          // act
+          const act = () => context.validateRuntimeSanity();
+          // assert
+          expect(act).to.throw(expectedError);
+        });
+      });
+      it('throws when validators are empty', () => {
+        // arrange
+        const expectedError = 'missing validators';
+        const context = new TestContext()
+          .withValidators([]);
+        // act
+        const act = () => context.validateRuntimeSanity();
+        // assert
+        expect(act).to.throw(expectedError);
+      });
+    });
+
+    describe('aggregates validators', () => {
+      it('does not throw if all validators pass', () => {
+        // arrange
+        const context = new TestContext()
+          .withValidators([
+            new SanityValidatorStub()
+              .withShouldValidateResult(false),
+            new SanityValidatorStub()
+              .withShouldValidateResult(false),
+          ]);
+        // act
+        const act = () => context.validateRuntimeSanity();
+        // assert
+        expect(act).to.not.throw();
+      });
+      it('does not throw if a validator return errors but pass', () => {
+        // arrange
+        const context = new TestContext()
+          .withValidators([
+            new SanityValidatorStub()
+              .withErrorsResult(['should be ignored'])
+              .withShouldValidateResult(false),
+          ]);
+        // act
+        const act = () => context.validateRuntimeSanity();
+        // assert
+        expect(act).to.not.throw();
+      });
+      it('does not throw if validators return no errors', () => {
+        // arrange
+        const context = new TestContext()
+          .withValidators([
+            new SanityValidatorStub()
+              .withShouldValidateResult(true)
+              .withErrorsResult([]),
+            new SanityValidatorStub()
+              .withShouldValidateResult(true)
+              .withErrorsResult([]),
+          ]);
+        // act
+        const act = () => context.validateRuntimeSanity();
+        // assert
+        expect(act).to.not.throw();
+      });
+      it('throws if single validator has errors', () => {
+        // arrange
+        const firstError = 'first-error';
+        const secondError = 'second-error';
+        let actualError = '';
+        const context = new TestContext()
+          .withValidators([
+            new SanityValidatorStub()
+              .withShouldValidateResult(true)
+              .withErrorsResult([firstError, secondError]),
+          ]);
+        // act
+        try {
+          context.validateRuntimeSanity();
+        } catch (err) {
+          actualError = err.toString();
+        }
+        // assert
+        expect(actualError).to.have.length.above(0);
+        expect(actualError).to.include(firstError);
+        expect(actualError).to.include(secondError);
+      });
+      it('accumulates error messages from validators', () => {
+        // arrange
+        const errorFromFirstValidator = 'first-error';
+        const errorFromSecondValidator = 'second-error';
+        let actualError = '';
+        const context = new TestContext()
+          .withValidators([
+            new SanityValidatorStub()
+              .withShouldValidateResult(true)
+              .withErrorsResult([errorFromFirstValidator]),
+            new SanityValidatorStub()
+              .withShouldValidateResult(true)
+              .withErrorsResult([errorFromSecondValidator]),
+          ]);
+        // act
+        try {
+          context.validateRuntimeSanity();
+        } catch (err) {
+          actualError = err.toString();
+        }
+        // assert
+        expect(actualError).to.have.length.above(0);
+        expect(actualError).to.include(errorFromFirstValidator);
+        expect(actualError).to.include(errorFromSecondValidator);
+      });
+    });
+  });
+});
+
+class TestContext {
+  private options: ISanityCheckOptions = new SanityCheckOptionsStub();
+
+  private validators: ISanityValidator[] = [new SanityValidatorStub()];
+
+  public withOptionsSetup(
+    setup: (stub: SanityCheckOptionsStub) => SanityCheckOptionsStub,
+  ) {
+    return this.withOptions(setup(new SanityCheckOptionsStub()));
+  }
+
+  public withOptions(options: ISanityCheckOptions): this {
+    this.options = options;
+    return this;
+  }
+
+  public withValidators(validators: ISanityValidator[]): this {
+    this.validators = validators;
+    return this;
+  }
+
+  public validateRuntimeSanity(): ReturnType<typeof validateRuntimeSanity> {
+    return validateRuntimeSanity(this.options, this.validators);
+  }
+}

tests/unit/infrastructure/RuntimeSanity/Validators/MetadataValidator.spec.ts

@@ -0,0 +1,133 @@
+import { describe, it, expect } from 'vitest';
+import { MetadataValidator } from '@/infrastructure/RuntimeSanity/Validators/MetadataValidator';
+import { SanityCheckOptionsStub } from '@tests/unit/shared/Stubs/SanityCheckOptionsStub';
+import { itEachAbsentObjectValue } from '@tests/unit/shared/TestCases/AbsentTests';
+import { AppMetadataStub } from '@tests/unit/shared/Stubs/AppMetadataStub';
+import { IAppMetadata } from '@/infrastructure/Metadata/IAppMetadata';
+
+describe('MetadataValidator', () => {
+  describe('shouldValidate', () => {
+    it('returns true when validateMetadata is true', () => {
+      // arrange
+      const expectedValue = true;
+      const options = new SanityCheckOptionsStub()
+        .withValidateMetadata(true);
+      const validator = new TestContext()
+        .createSut();
+      // act
+      const actualValue = validator.shouldValidate(options);
+      // assert
+      expect(actualValue).to.equal(expectedValue);
+    });
+
+    it('returns false when validateMetadata is false', () => {
+      // arrange
+      const expectedValue = false;
+      const options = new SanityCheckOptionsStub()
+        .withValidateMetadata(false);
+      const validator = new TestContext()
+        .createSut();
+      // act
+      const actualValue = validator.shouldValidate(options);
+      // assert
+      expect(actualValue).to.equal(expectedValue);
+    });
+  });
+  describe('collectErrors', () => {
+    describe('yields "missing metadata" if metadata is not provided', () => {
+      itEachAbsentObjectValue((absentValue) => {
+        // arrange
+        const expectedError = 'missing metadata';
+        const validator = new TestContext()
+          .withMetadata(absentValue)
+          .createSut();
+        // act
+        const errors = [...validator.collectErrors()];
+        // assert
+        expect(errors).to.have.lengthOf(1);
+        expect(errors[0]).to.equal(expectedError);
+      });
+    });
+    it('yields missing keys if metadata has keys without values', () => {
+      // arrange
+      const expectedError = 'Metadata keys missing: name, homepageUrl';
+      const metadata = new AppMetadataStub()
+        .witName(undefined)
+        .withHomepageUrl(undefined);
+      const validator = new TestContext()
+        .withMetadata(metadata)
+        .createSut();
+      // act
+      const errors = [...validator.collectErrors()];
+      // assert
+      expect(errors).to.have.lengthOf(1);
+      expect(errors[0]).to.equal(expectedError);
+    });
+    it('yields missing keys if metadata has getters instead of properties', () => {
+      /*
+        This test may behave differently in unit testing vs. production due to how code
+        is transformed, especially around class getters and their enumerability during bundling.
+      */
+      // arrange
+      const expectedError = 'Metadata keys missing: name, homepageUrl';
+      const stubWithGetters: Partial<IAppMetadata> = {
+        get name() {
+          return undefined;
+        },
+        get homepageUrl() {
+          return undefined;
+        },
+      };
+      const stub: IAppMetadata = {
+        ...new AppMetadataStub(),
+        ...stubWithGetters,
+      };
+      const validator = new TestContext()
+        .withMetadata(stub)
+        .createSut();
+      // act
+      const errors = [...validator.collectErrors()];
+      // assert
+      expect(errors).to.have.lengthOf(1);
+      expect(errors[0]).to.equal(expectedError);
+    });
+    it('yields unable to capture metadata if metadata has no getter values', () => {
+      // arrange
+      const expectedError = 'Unable to capture metadata key/value pairs';
+      const stub = {} as IAppMetadata;
+      const validator = new TestContext()
+        .withMetadata(stub)
+        .createSut();
+      // act
+      const errors = [...validator.collectErrors()];
+      // assert
+      expect(errors).to.have.lengthOf(1);
+      expect(errors[0]).to.equal(expectedError);
+    });
+    it('does not yield errors if all metadata keys have values', () => {
+      // arrange
+      const metadata = new AppMetadataStub();
+      const validator = new TestContext()
+        .withMetadata(metadata)
+        .createSut();
+      // act
+      const errors = [...validator.collectErrors()];
+      // assert
+      expect(errors).to.have.lengthOf(0);
+    });
+  });
+});
+
+class TestContext {
+  public metadata: IAppMetadata = new AppMetadataStub();
+
+  public withMetadata(metadata: IAppMetadata): this {
+    this.metadata = metadata;
+    return this;
+  }
+
+  public createSut(): MetadataValidator {
+    const mockFactory = () => this.metadata;
+    return new MetadataValidator(mockFactory);
+  }
+}

tests/unit/presentation/components/App.spec.ts

@@ -0,0 +1,14 @@
+import { describe, it, expect } from 'vitest';
+import { shallowMount } from '@vue/test-utils';
+import App from '@/presentation/components/App.vue';
+
+describe('App.vue', () => {
+  it('should be successfully mounted', () => {
+    // arrange
+    const component = App;
+    // act
+    const act = () => shallowMount(component);
+    // assert
+    expect(act).to.not.throw();
+  });
+});

tests/unit/shared/Stubs/CategoryCollectionParserStub.ts

@@ -0,0 +1,40 @@
+import { IProjectInformation } from '@/domain/IProjectInformation';
+import { ProjectInformation } from '@/domain/ProjectInformation';
+import { ICategoryCollection } from '@/domain/ICategoryCollection';
+import { getEnumValues } from '@/application/Common/Enum';
+import type { CollectionData } from '@/application/collections/';
+import { CategoryCollectionParserType } from '@/application/Parser/ApplicationParser';
+import { OperatingSystem } from '@/domain/OperatingSystem';
+import { CategoryCollectionStub } from './CategoryCollectionStub';
+
+export class CategoryCollectionParserStub {
+  public readonly arguments = new Array<{
+    data: CollectionData,
+    info: ProjectInformation,
+  }>();
+
+  private readonly returnValues = new Map<CollectionData, ICategoryCollection>();
+
+  public withReturnValue(
+    data: CollectionData,
+    collection: ICategoryCollection,
+  ): this {
+    this.returnValues.set(data, collection);
+    return this;
+  }
+
+  public getStub(): CategoryCollectionParserType {
+    return (data: CollectionData, info: IProjectInformation) => {
+      this.arguments.push({ data, info });
+      if (this.returnValues.has(data)) {
+        return this.returnValues.get(data);
+      }
+      // Get next OS with a unique OS so mock does not result in an invalid app due to duplicated OS
+      // collections.
+      const currentRun = this.arguments.length - 1;
+      const nextOs = getEnumValues(OperatingSystem)[currentRun];
+      return new CategoryCollectionStub()
+        .withOs(nextOs);
+    };
+  }
+}

tests/unit/shared/Stubs/CodeValidatorStub.ts

@@ -1,5 +1,5 @@
 import { expect } from 'vitest';
-import { Constructible } from '@tests/shared/TypeHelpers';
+import { Constructible } from '@/TypeHelpers';
 import { ICodeValidationRule } from '@/application/Parser/Script/Validation/ICodeValidationRule';
 import { ICodeValidator } from '@/application/Parser/Script/Validation/ICodeValidator';
 

tests/unit/shared/Stubs/ProjectInformationParserStub.ts

@@ -0,0 +1,22 @@
+import { parseProjectInformation } from '@/application/Parser/ProjectInformationParser';
+import { IAppMetadata } from '@/infrastructure/Metadata/IAppMetadata';
+import { IProjectInformation } from '@/domain/IProjectInformation';
+import { ProjectInformationStub } from './ProjectInformationStub';
+
+export class ProjectInformationParserStub {
+  public readonly arguments = new Array<IAppMetadata>();
+
+  private returnValue: IProjectInformation = new ProjectInformationStub();
+
+  public withReturnValue(value: IProjectInformation): this {
+    this.returnValue = value;
+    return this;
+  }
+
+  public getStub(): typeof parseProjectInformation {
+    return (metadata) => {
+      this.arguments.push(metadata);
+      return this.returnValue;
+    };
+  }
+}

tests/unit/shared/Stubs/SanityCheckOptionsStub.ts

@@ -0,0 +1,10 @@
+import { ISanityCheckOptions } from '@/infrastructure/RuntimeSanity/ISanityCheckOptions';
+
+export class SanityCheckOptionsStub implements ISanityCheckOptions {
+  public validateMetadata = false;
+
+  public withValidateMetadata(value: boolean): this {
+    this.validateMetadata = value;
+    return this;
+  }
+}

tests/unit/shared/Stubs/SanityValidatorStub.ts

@@ -0,0 +1,29 @@
+import { ISanityCheckOptions } from '@/infrastructure/RuntimeSanity/ISanityCheckOptions';
+import { ISanityValidator } from '@/infrastructure/RuntimeSanity/ISanityValidator';
+
+export class SanityValidatorStub implements ISanityValidator {
+  public shouldValidateArgs = new Array<ISanityCheckOptions>();
+
+  private errors: readonly string[] = [];
+
+  private shouldValidateResult = true;
+
+  public shouldValidate(options: ISanityCheckOptions): boolean {
+    this.shouldValidateArgs.push(options);
+    return this.shouldValidateResult;
+  }
+
+  public collectErrors(): Iterable<string> {
+    return this.errors;
+  }
+
+  public withErrorsResult(errors: readonly string[]): this {
+    this.errors = errors;
+    return this;
+  }
+
+  public withShouldValidateResult(shouldValidate: boolean): this {
+    this.shouldValidateResult = shouldValidate;
+    return this;
+  }
+}

tests/unit/shared/TestCases/SingletonTests.ts

@@ -1,5 +1,5 @@
 import { it, expect } from 'vitest';
-import { Constructible } from '@tests/shared/TypeHelpers';
+import { Constructible } from '@/TypeHelpers';
 
 interface ISingletonTestData<T> {
   getter: () => T;

vite.config.ts

@@ -1,6 +1,6 @@
 /// <reference types="vitest" />
 import { resolve } from 'path';
-import { defineConfig } from 'vite';
+import { defineConfig, UserConfig } from 'vite';
 import legacy from '@vitejs/plugin-legacy';
 import vue from '@vitejs/plugin-vue2';
 import ViteYaml from '@modyfi/vite-plugin-yaml';
@@ -10,45 +10,53 @@ const WEB_DIRECTORY = resolve(getSelfDirectoryAbsolutePath(), 'src/presentation'
 const TEST_INITIALIZATION_FILE = resolve(getSelfDirectoryAbsolutePath(), 'tests/shared/bootstrap/setup.ts');
 const NODE_CORE_MODULES = ['os', 'child_process', 'fs', 'path'];
 
-export default defineConfig({
+export function createVueConfig(options?: {
-  root: WEB_DIRECTORY,
+  readonly supportLegacyBrowsers: boolean,
-  plugins: [
+}): UserConfig {
-    vue(),
+  return {
-    ViteYaml(),
+    root: WEB_DIRECTORY,
-    legacy(),
+    plugins: [
-  ],
+      vue(),
-  esbuild: {
+      ViteYaml(),
-    supported: {
+      ...[options?.supportLegacyBrowsers ? legacy() : undefined],
-      'top-level-await': true, // Exclude browsers not supporting top-level-await
+    ],
-    },
+    esbuild: {
-  },
+      supported: {
-  define: {
+        'top-level-await': true, // Exclude browsers not supporting top-level-await
-    ...getClientEnvironmentVariables(),
-  },
-  resolve: {
-    alias: {
-      ...getAliasesFromTsConfig(),
-    },
-  },
-  build: {
-    rollupOptions: {
-      // Ensure Node core modules are externalized and don't trigger warnings in browser builds
-      external: {
-        ...NODE_CORE_MODULES,
       },
     },
-  },
+    define: {
-  server: {
+      ...getClientEnvironmentVariables(),
-    port: 3169,
-  },
-  test: {
-    globals: true,
-    environment: 'jsdom',
-    alias: {
-      ...getAliasesFromTsConfig(),
     },
-    setupFiles: [
+    resolve: {
-      TEST_INITIALIZATION_FILE,
+      alias: {
-    ],
+        ...getAliasesFromTsConfig(),
-  },
+      },
-});
+    },
+    build: {
+      rollupOptions: {
+        // Ensure Node core modules are externalized and don't trigger warnings in browser builds
+        external: {
+          ...NODE_CORE_MODULES,
+        },
+      },
+    },
+    server: {
+      port: 3169,
+    },
+    test: {
+      globals: true,
+      environment: 'jsdom',
+      alias: {
+        ...getAliasesFromTsConfig(),
+      },
+      setupFiles: [
+        TEST_INITIALIZATION_FILE,
+      ],
+    },
+  };
+}
+
+export default defineConfig(createVueConfig({
+  supportLegacyBrowsers: true,
+}));