En-doc-inate

Author: imnasnainaec

.github/workflows/test.yml

@@ -80,7 +80,7 @@ jobs:
         run: npm ci --ignore-scripts --omit=optional
 
       - name: Install system dependencies for Electron
-        run: sudo apt-get update && sudo apt-get install -y xvfb libgbm-dev libnss3 libxss1 libasound2t64
+        run: sudo apt-get update && sudo apt-get install -y --no-install-recommends xvfb libgbm-dev libnss3 libxss1 libasound2t64
 
       - name: Build extension
         working-directory: extension-repo

e2e-tests/fixtures/app.fixture.ts

@@ -25,6 +25,11 @@ export interface TestAppFixtures {
   mainPage: Page;
 }
 
+/**
+ * Playwright test fixture for smoke tests. Launches one Electron instance per worker (shared across
+ * all tests in that worker) and provides `electronApp` and `mainPage`. Attaches a failure
+ * screenshot to the report when a test does not meet its expected status.
+ */
 export const test = base.extend<TestAppFixtures, WorkerAppFixtures>({
   // Worker-scoped: the Electron process is launched once per worker and shared across all tests,
   // avoiding the process startup/teardown cost per test.

e2e-tests/fixtures/cdp.fixture.ts

@@ -18,10 +18,15 @@ export { expect } from '@playwright/test';
 
 const CDP_URL = process.env.CDP_URL || 'http://localhost:9223';
 
+/** Fixtures provided by the CDP test fixture. */
 export interface CdpFixtures {
   mainPage: Page;
 }
 
+/**
+ * Playwright test fixture for feature tests. Connects to an already-running Platform.Bible instance
+ * via CDP and provides `mainPage`. Does not launch or shut down the app.
+ */
 export const test = base.extend<CdpFixtures>({
   // eslint-disable-next-line no-empty-pattern
   mainPage: async ({}, use) => {

e2e-tests/fixtures/helpers.ts

@@ -43,7 +43,14 @@ export interface LaunchElectronAppOptions {
   envOverrides?: Record<string, string>;
 }
 
-/** Wait for the WebSocket server to be ready on the specified port. */
+/**
+ * Wait for the WebSocket server to be ready on the specified port.
+ *
+ * @param port Port number to connect to.
+ * @param timeout Maximum time in milliseconds to wait before throwing.
+ * @returns Resolves when a WebSocket connection to the port succeeds.
+ * @throws {Error} If the WebSocket server is not ready within `timeout` milliseconds.
+ */
 async function waitForWebSocketReady(port: number, timeout: number): Promise<void> {
   const startTime = Date.now();
 
@@ -79,8 +86,12 @@ async function waitForWebSocketReady(port: number, timeout: number): Promise<voi
 
 /**
  * Launch a fresh Electron instance (paranext-core) with the interlinearizer extension loaded via
- * `--extensionDirs`. Returns the app handle, the temp directory path, and a promise that resolves
- * when the app closes.
+ * `--extensions`.
+ *
+ * @param opts Optional launch options (e.g. environment variable overrides).
+ * @returns The app handle, the isolated user-data directory path, and a promise that resolves when
+ *   the app closes.
+ * @throws If Electron fails to launch or the WebSocket server does not become ready.
  */
 export async function launchElectronWithExtension(
   opts: LaunchElectronAppOptions = {},
@@ -161,6 +172,9 @@ export async function launchElectronWithExtension(
 /**
  * Tear down an Electron instance: kill the process group, wait for close, and clean up the isolated
  * user-data directory.
+ *
+ * @param ctx The app context returned by {@link launchElectronWithExtension}.
+ * @returns Resolves when the Electron process has been killed and user-data cleaned up.
  */
 export async function teardownElectronApp(ctx: ElectronAppContext): Promise<void> {
   const { electronApp, userDataDir, appClosed } = ctx;
@@ -218,6 +232,15 @@ export async function teardownElectronApp(ctx: ElectronAppContext): Promise<void
 /**
  * One JSON-RPC 2.0 request over WebSocket: open, send, wait for response id `1`, close. Ignores
  * unrelated messages until the matching response arrives.
+ *
+ * @param method JSON-RPC method name to invoke.
+ * @param timeoutErrorMessage Custom error message on timeout; defaults to a standard timeout
+ *   message.
+ * @param params Positional parameters to send with the request.
+ * @param port WebSocket port to connect to.
+ * @param perRequestTimeoutMs Milliseconds before the request times out.
+ * @returns The `result` field of the JSON-RPC response, typed as `T`.
+ * @throws {Error} If the request times out or the server returns a JSON-RPC error.
  */
 async function sendPapiJsonRpcOnce<T>(
   method: string,
@@ -278,6 +301,13 @@ async function sendPapiJsonRpcOnce<T>(
 /**
  * Send a single JSON-RPC request where `method` is a PAPI request type (e.g. `rpc.discover`). Opens
  * a connection, sends one request, waits for the matching response id, then closes.
+ *
+ * @param method PAPI request type to invoke (e.g. `rpc.discover`).
+ * @param params Positional parameters to send with the request.
+ * @param port WebSocket port to connect to.
+ * @param perRequestTimeoutMs Milliseconds before the request times out.
+ * @returns The `result` field of the JSON-RPC response, typed as `T`.
+ * @throws {Error} If the request times out or the server returns a JSON-RPC error.
  */
 export async function sendPapiRequestOnce<T>(
   method: string,
@@ -288,7 +318,15 @@ export async function sendPapiRequestOnce<T>(
   return sendPapiJsonRpcOnce<T>(method, undefined, params, port, perRequestTimeoutMs);
 }
 
-/** Poll `rpc.discover` until `methodName` appears in `result.methods` or `timeoutMs` elapses. */
+/**
+ * Poll `rpc.discover` until `methodName` appears in `result.methods` or `timeoutMs` elapses.
+ *
+ * @param methodName The fully-qualified PAPI method name to wait for (e.g. `command:foo.bar`).
+ * @param port WebSocket port to connect to.
+ * @param timeoutMs Maximum time in milliseconds to poll before throwing.
+ * @returns Resolves when the method appears in `rpc.discover`.
+ * @throws {Error} If the method is not registered within `timeoutMs` milliseconds.
+ */
 export async function waitForPapiMethodRegistered(
   methodName: string,
   port: number = DEFAULT_WEBSOCKET_PORT,
@@ -320,6 +358,12 @@ export async function waitForPapiMethodRegistered(
 /**
  * Wait for the Platform.Bible UI to be fully ready: dock layout appears and `platform.about`
  * command is registered (dialog service has finished initializing).
+ *
+ * @param page The Playwright `Page` for the Platform.Bible renderer window.
+ * @param timeout Maximum time in milliseconds to wait before throwing.
+ * @returns Resolves when the dock layout is visible and `platform.about` is registered.
+ * @throws If the dock layout or `platform.about` command does not appear within `timeout`
+ *   milliseconds.
  */
 export async function waitForAppReady(page: Page, timeout = 60_000): Promise<void> {
   const start = Date.now();
@@ -334,6 +378,10 @@ export async function waitForAppReady(page: Page, timeout = 60_000): Promise<voi
 /**
  * Wait for the interlinearizer extension to finish activating by polling `rpc.discover` until
  * `interlinearizer.openForWebView` is listed.
+ *
+ * @param timeoutMs Maximum time in milliseconds to poll before throwing.
+ * @returns Resolves when `interlinearizer.openForWebView` is listed in `rpc.discover`.
+ * @throws {Error} If the extension does not register within `timeoutMs` milliseconds.
  */
 export async function waitForInterlinearizerReady(timeoutMs = 90_000): Promise<void> {
   await waitForPapiMethodRegistered(

e2e-tests/global-setup.ts

@@ -8,7 +8,12 @@ import fs from 'fs';
 const WEBSOCKET_PORT = 8876;
 const RENDERER_PORT = 1212;
 
-/** Check if a port is already in use */
+/**
+ * Check if a port is already in use.
+ *
+ * @param port Port number to probe.
+ * @returns Resolves to `true` if the port is occupied, `false` if it is free.
+ */
 function isPortInUse(port: number): Promise<boolean> {
   return new Promise((resolve) => {
     const server = net.createServer();
@@ -24,7 +29,14 @@ function isPortInUse(port: number): Promise<boolean> {
   });
 }
 
-/** Wait until a port is accepting connections */
+/**
+ * Wait until a port is accepting connections.
+ *
+ * @param port Port number to poll.
+ * @param timeout Maximum time in milliseconds to wait before rejecting.
+ * @returns Resolves when a TCP connection to the port succeeds.
+ * @throws {Error} If the port does not become available within `timeout` milliseconds.
+ */
 function waitForPort(port: number, timeout: number): Promise<void> {
   const startTime = Date.now();
   return new Promise((resolve, reject) => {
@@ -47,7 +59,23 @@ function waitForPort(port: number, timeout: number): Promise<void> {
   });
 }
 
-// Playwright global setup requires this signature even though config is unused
+/**
+ * Playwright global setup. Runs once before any test worker starts.
+ *
+ * 1. Fails fast if port 8876 is already in use (a running Platform.Bible would conflict with the
+ *    Electron instance launched by fixtures).
+ * 2. Removes stale Electron singleton lock files left behind by crashes.
+ * 3. Fails fast if the extension dist is missing (directs the developer to run `npm run build`).
+ * 4. Ensures the paranext-core dev main bundle exists, building it via `npm run prestart` if not.
+ * 5. Starts the paranext-core webpack renderer dev server on port 1212 if not already running, and
+ *    stores its PID for {@link globalTeardown} to stop it.
+ *
+ * @param _config Playwright config object — unused; required by Playwright's global-setup
+ *   interface.
+ * @returns Resolves when the renderer dev server is ready.
+ * @throws {Error} If port 8876 is already in use.
+ * @throws {Error} If the extension dist is missing.
+ */
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 export default async function globalSetup(_config: FullConfig): Promise<void> {
   const extensionRoot = path.resolve(__dirname, '..');

e2e-tests/global-teardown.ts

@@ -4,7 +4,16 @@ import { execSync } from 'child_process';
 import path from 'path';
 import fs from 'fs';
 
-// Playwright global teardown requires this signature even though config is unused
+/**
+ * Playwright global teardown. Runs once after all test workers have finished.
+ *
+ * Stops the renderer dev server started by {@link globalSetup} (if any), then runs `npm run stop` in
+ * paranext-core to terminate any lingering Electron processes.
+ *
+ * @param _config Playwright config object — unused; required by Playwright's global-teardown
+ *   interface.
+ * @returns Resolves when all cleanup steps have completed.
+ */
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 export default async function globalTeardown(_config: FullConfig): Promise<void> {
   const extensionRoot = path.resolve(__dirname, '..');

e2e-tests/playwright.config.ts

@@ -4,7 +4,7 @@ import { defineConfig } from '@playwright/test';
 /**
  * Playwright configuration for interlinearizer extension E2E tests.
  *
- * Launches Platform.Bible with the interlinearizer extension loaded via `--extensionDirs`.
+ * Launches Platform.Bible with the interlinearizer extension loaded via `--extensions`.
  *
  * Prerequisites:
  *
@@ -38,9 +38,5 @@ export default defineConfig({
       name: 'smoke',
       testDir: './tests/smoke',
     },
-    {
-      name: 'isolated',
-      testDir: './tests/isolated',
-    },
   ],
 });

e2e-tests/tests/_example/example-interlinearizer-feature.spec.ts

@@ -16,6 +16,12 @@
 import { test, expect } from '../../fixtures/cdp.fixture';
 import { waitForAppReady, waitForInterlinearizerReady } from '../../fixtures/helpers';
 
+/**
+ * Filter out expected/benign console errors from a list of captured error messages.
+ *
+ * @param errors Array of console error message strings to filter.
+ * @returns The subset of `errors` that are not considered benign.
+ */
 function filterConsoleErrors(errors: string[]): string[] {
   return errors.filter(
     (e) =>