@thinkwise/testwise 0.2.62 → 0.2.99

package/dist/services/Logger.d.ts

@@ -1,3 +1,16 @@
+/**
+ * The singleton logger instance. Import this in any file that needs to write
+ * structured log entries during test execution or pipeline runs.
+ *
+ * All methods accept an optional message string followed by any number of
+ * extra values (arrays, objects, errors) that will be appended to the entry.
+ *
+ * ```ts
+ * logger.info('Starting sync pipeline');
+ * logger.warn('Subject not found', { subject: name });
+ * logger.error('Unexpected failure', err);
+ * ```
+ */
 export declare const logger: {
     error: (msg?: string, ...optionalParams: unknown[]) => void;
     warn: (msg?: string, ...optionalParams: unknown[]) => void;

package/dist/services/Logger.js

@@ -3,6 +3,32 @@ import path from 'node:path';
 import { LogLevel } from '../enums/LogLevel.js';
 import { originalDebug, originalError, originalInfo, originalLog, originalWarn } from '../index.js';
 import { testwiseConfig } from './ConfigBuilder.js';
+/**
+ * Buffered, level-filtered logger that writes timestamped entries to a log
+ * file AND (optionally) to the console during test runs.
+ *
+ * **Configuration** — all settings live under `featureSettings.logger` in
+ * `Testwise.json`:
+ *
+ * | Key | Type | Default | Description |
+ * |---|---|---|---|
+ * | `logDir` | string | `"logs"` | Directory to write log files into, relative to the consumer project root. |
+ * | `logLevel` | `"ERROR"\|"WARN"\|"INFO"\|"DEBUG"\|"ALL"` | `"ALL"` | Minimum severity level to record. |
+ * | `logByDay` | boolean | `false` | When `true`, creates a new `test-log-YYYY-MM-DD.log` file each day instead of always writing to `test-log.log`. |
+ * | `bufferSizeLimit` | number | `1000` | Number of log lines to buffer in memory before flushing to disk. |
+ * | `applyLogLevelToConsoleOutput` | boolean | `false` | When `true`, the log-level filter also suppresses console output (not just file output). |
+ *
+ * **How to use it:**
+ * ```ts
+ * import { logger } from '../services/Logger.js';
+ *
+ * logger.info('Navigating to Employee subject');
+ * logger.error('Connection failed', error);
+ * ```
+ *
+ * Entries are written in the format:
+ * `[ISO-timestamp] [LEVEL] [file:line:col] message`
+ */
 const logDir = path.resolve(process.cwd(), testwiseConfig().get('featureSettings.logger.logDir') ?? 'logs');
 const logLevel = testwiseConfig().get('featureSettings.logger.logLevel')?.toUpperCase() ?? LogLevel.ALL;
 const applyLogLevelToConsoleOutput = testwiseConfig().get('featureSettings.logger.applyLogLevelToConsoleOutput') ?? false;
@@ -149,6 +175,19 @@ function getCallerInfo() {
     }
     return 'unknown origin';
 }
+/**
+ * The singleton logger instance. Import this in any file that needs to write
+ * structured log entries during test execution or pipeline runs.
+ *
+ * All methods accept an optional message string followed by any number of
+ * extra values (arrays, objects, errors) that will be appended to the entry.
+ *
+ * ```ts
+ * logger.info('Starting sync pipeline');
+ * logger.warn('Subject not found', { subject: name });
+ * logger.error('Unexpected failure', err);
+ * ```
+ */
 export const logger = {
     // Order by severity level
     error: (msg, ...optionalParams) => log(msg, LogLevel.ERROR, ...optionalParams),

package/dist/services/Logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"Logger.js","sourceRoot":"","sources":["../../services/Logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACpG,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,CAAC,GAAG,CAAS,+BAA+B,CAAC,IAAI,MAAM,CAAC,CAAC;AACpH,MAAM,QAAQ,GACX,cAAc,EAAE,CAAC,GAAG,CAAS,iCAAiC,CAAC,EAAE,WAAW,EAAe,IAAI,QAAQ,CAAC,GAAG,CAAC;AAC/G,MAAM,4BAA4B,GAChC,cAAc,EAAE,CAAC,GAAG,CAAU,qDAAqD,CAAC,IAAI,KAAK,CAAC;AAEhG,IAAI,SAAS,GAAG,KAAK,CAAC;AACtB,IAAI,WAAW,GAAG,KAAK,CAAC;AACxB,IAAI,OAAO,GAAG,KAAK,CAAC;AACpB,IAAI,QAAQ,GAAG,KAAK,CAAC;AACrB,IAAI,MAAM,GAAG,KAAK,CAAC;AAEnB,QAAQ,QAAQ,EAAE,CAAC;IACjB,KAAK,QAAQ,CAAC,KAAK;QACjB,SAAS,GAAG,IAAI,CAAC;QACjB,MAAM;IACR,KAAK,QAAQ,CAAC,IAAI;QAChB,SAAS,GAAG,IAAI,CAAC;QACjB,WAAW,GAAG,IAAI,CAAC;QACnB,MAAM;IACR,KAAK,QAAQ,CAAC,IAAI;QAChB,SAAS,GAAG,IAAI,CAAC;QACjB,WAAW,GAAG,IAAI,CAAC;QACnB,OAAO,GAAG,IAAI,CAAC;QACf,MAAM;IACR,KAAK,QAAQ,CAAC,KAAK;QACjB,SAAS,GAAG,IAAI,CAAC;QACjB,WAAW,GAAG,IAAI,CAAC;QACnB,OAAO,GAAG,IAAI,CAAC;QACf,QAAQ,GAAG,IAAI,CAAC;QAChB,MAAM;IACR,KAAK,QAAQ,CAAC,GAAG;QACf,SAAS,GAAG,IAAI,CAAC;QACjB,WAAW,GAAG,IAAI,CAAC;QACnB,OAAO,GAAG,IAAI,CAAC;QACf,QAAQ,GAAG,IAAI,CAAC;QAChB,MAAM,GAAG,IAAI,CAAC;QACd,MAAM;IACR;QACE,MAAM,IAAI,KAAK,CAAC,sBAAsB,QAAQ,EAAE,CAAC,CAAC;AACtD,CAAC;AAED,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;AAE1C,MAAM,kBAAkB,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAClE,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAC3B,MAAM,EACN,cAAc,EAAE,CAAC,GAAG,CAAU,iCAAiC,CAAC,KAAK,IAAI;IACvE,CAAC,CAAC,YAAY,kBAAkB,MAAM;IACtC,CAAC,CAAC,cAAc,CACnB,CAAC;AAEF,IAAI,SAAS,GAAa,EAAE,CAAC;AAC7B,MAAM,eAAe,GAAG,cAAc,EAAE,CAAC,GAAG,CAAS,wCAAwC,CAAC,IAAI,IAAI,CAAC;AAEvG,IAAI,oBAAoB,GAAG,CAAC,CAAC;AAE7B,IAAI,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;IAC/B,MAAM,YAAY,GAAG,EAAE,CAAC,YAAY,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACvF,6DAA6D;IAC7D,oBAAoB,GAAG,YAAY,CAAC,MAAM,CAAC;AAC7C,CAAC;AAED;;;;GAIG;AACH,SAAS,SAAS;IAChB,IAAI,CAAC;QACH,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzB,MAAM,YAAY,GAAG,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC;gBAC7C,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;gBACnE,CAAC,CAAC,EAAE,CAAC;YAEP,MAAM,YAAY,GAAG,CAAC,GAAG,YAAY,EAAE,GAAG,SAAS,CAAC,CAAC;YACrD,MAAM,WAAW,GAAG,eAAe,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC;YAE/F,EAAE,CAAC,aAAa,CAAC,WAAW,EAAE,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAE7D,SAAS,GAAG,EAAE,CAAC;QACjB,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC;IACzC,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAS,GAAG,CAAC,OAAgB,EAAE,QAAkB,QAAQ,CAAC,GAAG,EAAE,GAAG,cAAyB;IACzF,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC3C,MAAM,MAAM,GAAG,aAAa,EAAE,CAAC;IAC/B,MAAM,SAAS,GAAG,IAAI,SAAS,MAAM,KAAK,MAAM,MAAM,KAAK,OAAO,EAAE,CAAC;IAErE,QAAQ,KAAK,EAAE,CAAC;QACd,KAAK,QAAQ,CAAC,KAAK;YACjB,IAAI,SAAS,EAAE,CAAC;gBACd,SAAS,CAAC,IAAI,CAAC,GAAG,SAAS,IAAI,cAAc,EAAE,CAAC,CAAC;YACnD,CAAC;YAED,IAAI,SAAS,IAAI,CAAC,4BAA4B;gBAAE,aAAa,CAAC,SAAS,EAAE,GAAG,cAAc,CAAC,CAAC;YAC5F,MAAM;QACR,KAAK,QAAQ,CAAC,IAAI;YAChB,IAAI,WAAW,EAAE,CAAC;gBAChB,SAAS,CAAC,IAAI,CAAC,GAAG,SAAS,IAAI,cAAc,EAAE,CAAC,CAAC;YACnD,CAAC;YAED,IAAI,WAAW,IAAI,CAAC,4BAA4B;gBAAE,YAAY,CAAC,SAAS,EAAE,GAAG,cAAc,CAAC,CAAC;YAC7F,MAAM;QACR,KAAK,QAAQ,CAAC,KAAK;YACjB,IAAI,QAAQ,EAAE,CAAC;gBACb,SAAS,CAAC,IAAI,CAAC,GAAG,SAAS,IAAI,cAAc,EAAE,CAAC,CAAC;YACnD,CAAC;YAED,IAAI,QAAQ,IAAI,CAAC,4BAA4B;gBAAE,aAAa,CAAC,SAAS,EAAE,GAAG,cAAc,CAAC,CAAC;YAC3F,MAAM;QACR,KAAK,QAAQ,CAAC,IAAI;YAChB,IAAI,OAAO,EAAE,CAAC;gBACZ,SAAS,CAAC,IAAI,CAAC,GAAG,SAAS,IAAI,cAAc,EAAE,CAAC,CAAC;YACnD,CAAC;YAED,IAAI,OAAO,IAAI,CAAC,4BAA4B;gBAAE,YAAY,CAAC,SAAS,EAAE,GAAG,cAAc,CAAC,CAAC;YACzF,MAAM;QACR;YACE,IAAI,MAAM,EAAE,CAAC;gBACX,SAAS,CAAC,IAAI,CAAC,GAAG,SAAS,IAAI,cAAc,EAAE,CAAC,CAAC;YACnD,CAAC;YAED,IAAI,MAAM,IAAI,CAAC,4BAA4B;gBAAE,WAAW,CAAC,SAAS,EAAE,GAAG,cAAc,CAAC,CAAC;IAC3F,CAAC;IAED,IAAI,SAAS,CAAC,MAAM,IAAI,eAAe,EAAE,CAAC;QACxC,SAAS,EAAE,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,aAAa;IACpB,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE,CAAC,KAAK,CAAC;IAChC,IAAI,CAAC,KAAK;QAAE,OAAO,gBAAgB,CAAC;IAEpC,MAAM,UAAU,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAErC,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;YAC9D,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC;YACjD,IAAI,KAAK,EAAE,CAAC;gBACV,IAAI,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;gBACpB,MAAM,UAAU,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;gBAC5B,MAAM,YAAY,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;gBAE9B,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;oBAChC,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,CAAC;gBACjD,CAAC;gBACD,OAAO,GAAG,IAAI,IAAI,UAAU,IAAI,YAAY,EAAE,CAAC;YACjD,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,0BAA0B;IAC1B,KAAK,EAAE,CAAC,GAAY,EAAE,GAAG,cAAyB,EAAQ,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,KAAK,EAAE,GAAG,cAAc,CAAC;IACxG,IAAI,EAAE,CAAC,GAAY,EAAE,GAAG,cAAyB,EAAQ,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,IAAI,EAAE,GAAG,cAAc,CAAC;IACtG,IAAI,EAAE,CAAC,GAAY,EAAE,GAAG,cAAyB,EAAQ,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,IAAI,EAAE,GAAG,cAAc,CAAC;IACtG,KAAK,EAAE,CAAC,GAAY,EAAE,GAAG,cAAyB,EAAQ,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,KAAK,EAAE,GAAG,cAAc,CAAC;IACxG,GAAG,EAAE,CAAC,GAAY,EAAE,GAAG,cAAyB,EAAQ,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,GAAG,EAAE,GAAG,cAAc,CAAC;CACrG,CAAC"}
+{"version":3,"file":"Logger.js","sourceRoot":"","sources":["../../services/Logger.ts"],"names":[],"mappings":"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"}

package/dist/types/Components.d.ts

@@ -1,4 +1,21 @@
-export type SubjectAgnosticComponents = 'Chart' | 'PivotGridFieldList' | 'Splitter' | 'ActionBar' | 'CombinedFilter' | 'CustomActionBar' | 'DetailTabPage' | 'Tab' | 'Tab' | 'TaskTiles' | 'FilterForm' | 'PrefilterList' | 'TaskBar' | 'Cardlist' | 'TreeView' | 'CubeViewBar' | 'PivotGrid' | 'Maps' | 'ReportBar' | 'ReportTiles' | 'Scheduler' | 'Preview';
+/**
+ * Enumerates every Thinkwise UI component that the artifact pipeline can
+ * generate references to inside subject classes.
+ *
+ * Components are split into two groups:
+ *
+ * - **`SubjectAgnosticComponents`** (`coreComponents` array) — components that
+ *   are identical across all subjects and don't need subject-specific typing.
+ *   Examples: `ActionBar`, `Tab`, `FilterForm`, `TreeView`.
+ *
+ * - **`SubjectComponents`** (`subjectComponents` array) — `Form` and `Grid`,
+ *   which get a fully-typed generated `Components/` subfolder with field/column
+ *   accessors specific to that subject.
+ *
+ * The `SelectorBuilder` in the artifact-builder uses these lists to decide
+ * which locator strategy to apply when generating subject class properties.
+ */
+export type SubjectAgnosticComponents = 'Chart' | 'PivotGridFieldList' | 'Splitter' | 'ActionBar' | 'CombinedFilter' | 'CustomActionBar' | 'DetailTabPage' | 'Tab' | 'TaskTiles' | 'FilterForm' | 'PrefilterList' | 'TaskBar' | 'Cardlist' | 'TreeView' | 'CubeViewBar' | 'PivotGrid' | 'Maps' | 'ReportBar' | 'ReportTiles' | 'Scheduler' | 'Preview';
 export declare const coreComponents: SubjectAgnosticComponents[];
 export type SubjectComponents = 'Form' | 'Grid';
 export declare const subjectComponents: SubjectComponents[];

package/dist/types/Components.js

@@ -6,7 +6,6 @@ export const coreComponents = [
     'Tab',
     'DetailTabPage',
     'TaskBar',
-    'Tab',
     'Cardlist',
     'FilterForm',
     'TaskTiles',

package/dist/types/Components.js.map

@@ -1 +1 @@
-{"version":3,"file":"Components.js","sourceRoot":"","sources":["../../types/Components.ts"],"names":[],"mappings":"AAwBA,MAAM,CAAC,MAAM,cAAc,GAAgC;IACzD,WAAW;IACX,gBAAgB;IAChB,iBAAiB;IACjB,UAAU;IACV,KAAK;IACL,eAAe;IACf,SAAS;IACT,KAAK;IACL,UAAU;IACV,YAAY;IACZ,WAAW;IACX,eAAe;IACf,OAAO;IACP,UAAU;IACV,aAAa;IACb,WAAW;IACX,oBAAoB;IACpB,MAAM;IACN,WAAW;IACX,aAAa;IACb,WAAW;IACX,SAAS;CACV,CAAC;AAGF,MAAM,CAAC,MAAM,iBAAiB,GAAwB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAGvE,MAAM,CAAC,MAAM,gBAAgB,GAAuB,CAAC,GAAG,cAAc,EAAE,GAAG,iBAAiB,CAAC,CAAC;AAC9F,MAAM,CAAC,MAAM,wBAAwB,GAAuB,CAAC,UAAU,CAAC,CAAC"}
+{"version":3,"file":"Components.js","sourceRoot":"","sources":["../../types/Components.ts"],"names":[],"mappings":"AAwCA,MAAM,CAAC,MAAM,cAAc,GAAgC;IACzD,WAAW;IACX,gBAAgB;IAChB,iBAAiB;IACjB,UAAU;IACV,KAAK;IACL,eAAe;IACf,SAAS;IACT,UAAU;IACV,YAAY;IACZ,WAAW;IACX,eAAe;IACf,OAAO;IACP,UAAU;IACV,aAAa;IACb,WAAW;IACX,oBAAoB;IACpB,MAAM;IACN,WAAW;IACX,aAAa;IACb,WAAW;IACX,SAAS;CACV,CAAC;AAGF,MAAM,CAAC,MAAM,iBAAiB,GAAwB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAGvE,MAAM,CAAC,MAAM,gBAAgB,GAAuB,CAAC,GAAG,cAAc,EAAE,GAAG,iBAAiB,CAAC,CAAC;AAC9F,MAAM,CAAC,MAAM,wBAAwB,GAAuB,CAAC,UAAU,CAAC,CAAC"}

package/dist/types/LocatorType.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The subset of Playwright locator method names used when generating locator
+ * strings inside the artifact-builder pipeline.
+ */
+export type LocatorType = 'locator' | 'getByTestId' | 'getByRole' | 'getByLabel' | 'getByPlaceholder' | 'getByText';

package/dist/types/LocatorType.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=LocatorType.js.map

package/dist/types/LocatorType.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocatorType.js","sourceRoot":"","sources":["../../types/LocatorType.ts"],"names":[],"mappings":""}

package/dist/types/PollTypes.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Options for `pollUntil()` — controls how the polling loop behaves.
+ *
+ * All fields are optional; sensible defaults are used if omitted:
+ * - `timeout`: 10 000 ms
+ * - `interval`: 200 ms
+ * - `predicate`: truthy check on the returned value
+ */
 export type PollOptions<T = unknown> = {
     timeout?: number;
     interval?: number;

package/dist/types/Test.d.ts

@@ -1,2 +1,20 @@
 import type { PlaywrightTestArgs, PlaywrightTestOptions, PlaywrightWorkerArgs, PlaywrightWorkerOptions, TestType } from '@playwright/test';
+/**
+ * Convenience alias for the fully-typed Playwright `TestType` that includes
+ * all built-in test arguments and options (both per-test and per-worker).
+ *
+ * Used throughout the library instead of the verbose `TestType<...>` generic
+ * to keep constructor signatures readable. Every page-extension and
+ * page-override receives and returns a `Test` so they can chain
+ * `test.extend()` calls cleanly.
+ *
+ * @example
+ * import type { Test } from '../types/Test.js';
+ *
+ * export class MyExtension {
+ *   constructor(test: Test) {
+ *     this._test = test.extend({ ... });
+ *   }
+ * }
+ */
 export type Test = TestType<PlaywrightTestArgs & PlaywrightTestOptions, PlaywrightWorkerArgs & PlaywrightWorkerOptions>;

package/dist/types/Universal.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Configuration and login option shapes used by `LoginHelper` and the
+ * `LoginFeatures` page extension.
+ *
+ * - `UniversalConfigOptions` — feature flags and settings applied when
+ *   configuring the Thinkwise application during login.
+ * - `UniversalLoginOptions` — full set of overrides for a single login call
+ *   (credentials, application ID, config options, etc.).
+ *
+ * These types are used internally; you typically only interact with them
+ * via `page.logInWithOptions(options)`.
+ */
 export type UniversalConfigOptions = {
     barcodeScannerSymbologies?: string;
     cortexEnabledSymbologies?: string[];

package/dist/types/index.d.ts

@@ -1,2 +1,4 @@
+export * from './LocatorType.js';
+export * from './PollTypes.js';
 export * from './Test.js';
 export * from './Universal.js';

package/dist/types/index.js

@@ -1,3 +1,5 @@
+export * from './LocatorType.js';
+export * from './PollTypes.js';
 export * from './Test.js';
 export * from './Universal.js';
 //# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../types/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../types/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC"}

package/enums/ElementTypes.ts

@@ -1,3 +1,21 @@
+/**
+ * Maps Thinkwise model control type identifiers to their string values.
+ *
+ * The artifact pipeline reads `control_type` values from the Indicium API
+ * (via `IProperty.control_type`) and uses these enum members to decide which
+ * Testwise control class to generate for each field or column.
+ *
+ * | Enum member | Generated control |
+ * |---|---|
+ * | `Field` | `InputFieldControl` |
+ * | `Dropdown` | `LookupDropdown` (drop-down variant) |
+ * | `Textarea` | `InputFieldControl` (multi-line) |
+ * | `Checkbox` | `InputFieldControl` (checkbox) |
+ * | `Lookup` | `LookupDropdown` |
+ * | `Column` | `GridColumnControl` |
+ * | `ComboBox` | `FormComboBox` |
+ * | `DatePicker` | `DateControl` |
+ */
 export enum KnownElementTypes {
   Field = 'field',
   Dropdown = 'dropdown',

package/enums/ExportFormat.ts

@@ -1,3 +1,11 @@
+/**
+ * Supported file formats for the `ExportComponent` export action.
+ * Pass one of these values to `ExportComponent.export(format)` to trigger
+ * a grid or list export in the desired format (CSV, XLSX, or XLS).
+ *
+ * @example
+ * await page.components.export.export(ExportFormat.XLSX);
+ */
 export enum ExportFormat {
   CSV = 'csv',
   XLSX = 'xlsx',

package/enums/LogLevel.ts

@@ -1,8 +1,24 @@
+/**
+ * Controls how much output the Testwise `Logger` writes, both to the log file
+ * and (optionally) to the console.
+ *
+ * Levels are cumulative — choosing `WARN` includes `ERROR`; choosing `DEBUG`
+ * includes `ERROR`, `WARN`, and `INFO`.
+ *
+ * Configure via `Testwise.json`:
+ * ```json
+ * { "featureSettings": { "logger": { "logLevel": "INFO" } } }
+ * ```
+ */
 export enum LogLevel {
-  // Order by severity
+  /** Only critical failures. Use in CI environments where log noise must be minimal. */
   ERROR = 'ERROR',
+  /** Errors and recoverable warnings. Good default for most pipelines. */
   WARN = 'WARN',
+  /** Errors, warnings, and informational messages about what the test is doing. Recommended for local development. */
   INFO = 'INFO',
+  /** Full verbose output including internal state changes. Use when diagnosing hard-to-reproduce failures. */
   DEBUG = 'DEBUG',
+  /** Everything. Includes low-level log entries that are normally filtered out. */
   ALL = 'ALL'
 }

package/enums/index.ts

@@ -1 +1,2 @@
 export * from './ExportFormat.js';
+export * from './LogLevel.js';

package/helpers/ConfigChecker.ts

@@ -1,5 +1,18 @@
 import { indiciumApi } from '../services/IndiciumApi.service.js';
 
+/**
+ * Verifies that the consuming project's Testwise configuration is valid and
+ * reachable before the artifact pipeline is allowed to run.
+ *
+ * **Why this exists:** The artifact-builder fetches live model data from the
+ * Thinkwise Indicium API. If the API URL or credentials in `Testwise.json`
+ * are wrong, the pipeline fails mid-way with a cryptic network error.
+ * `ConfigChecker` performs a lightweight connectivity probe upfront so the
+ * pipeline can give a clear "cannot connect" error message instead.
+ *
+ * **When it is called:** Automatically by `ArtifactManager` at the start of
+ * every `testwise sync` run. You do not need to call it manually.
+ */
 export class ConfigChecker {
   public async hasValidModelBuilderConfig(): Promise<boolean> {
     return await indiciumApi.canConnectToProject();

package/helpers/Ensure.ts

@@ -1,7 +1,20 @@
+/**
+ * Asserts that `condition` is truthy, acting as a TypeScript assertion function.
+ * Throws an `Error` with the given message if the condition is falsy.
+ * @param condition - The value to assert.
+ * @param message - Optional error message (default `'Check failed'`).
+ */
 export function ensure(condition: unknown, message = 'Check failed'): asserts condition {
   if (!condition) throw new Error(message);
 }
 
+/**
+ * Asserts strict equality between `actual` and `expected`.
+ * Throws a descriptive `Error` (optionally prefixed by `label`) if they differ.
+ * @param actual - The value produced.
+ * @param expected - The value expected.
+ * @param label - Optional prefix for the error message.
+ */
 export function ensureEqual<T>(actual: T, expected: T, label?: string) {
   if (actual !== expected) {
     throw new Error(label ? `${label}: expected ${expected}, got ${actual}` : `expected ${expected}, got ${actual}`);

package/helpers/FlightTracker.ts

@@ -1,22 +1,54 @@
 import { EventEmitter } from 'node:events';
 import { testwiseConfig } from '../services/ConfigBuilder.js';
 
-const timeout = testwiseConfig().get<number>('featureSettings.InflightRequests.waitTimeout') ?? 5000;
+/**
+ * Tracks in-flight XHR requests made by the Thinkwise application and blocks
+ * test execution until the network has been idle for a short stability window.
+ *
+ * **Why this exists:** The Thinkwise Platform performs fire-and-forget XHR calls
+ * for things like navigation, saves, and data loads. Raw Playwright `waitFor*`
+ * helpers don't know about these — tests that proceed too early will act on
+ * stale data or a half-rendered screen. `FlightTracker` listens to every
+ * request/response cycle and exposes `waitToContinue()` which returns only
+ * once all tracked requests have finished AND the page has been quiet for at
+ * least `stabilityTime` milliseconds.
+ *
+ * **How to use it in tests:** You don't — it is wired up automatically inside
+ * `SubjectNavigator.navigateTo()`, `ClickOverride`, and `FillOverride`. You
+ * only need to know it exists if you are writing a new page-extension or
+ * override that performs navigation.
+ *
+ * @example
+ * // Inside a page-override or page-extension:
+ * const tracker = new FlightTracker();
+ * page.on('request',  req  => tracker.handleRequestStarted(req.url(), req.resourceType()));
+ * page.on('response', res  => tracker.handleRequestFinished(res.request().url()));
+ * await myAction();
+ * await tracker.waitToContinue();
+ */
+const minTimeout = 30000;
+const timeout = Math.max(testwiseConfig().get<number>('featureSettings.InflightRequests.waitTimeout') ?? 0, minTimeout);
+
 const stabilityTime = 150;
 
 export class FlightTracker {
   public requestsInFlight: number = 0;
-  private activeRequests = new Set<string>();
+  private activeRequests = new Map<string, number>();
   public eventEmitter: EventEmitter = new EventEmitter();
 
   /**
-   * Filters out non-functional "noise" requests that shouldn't block test execution.
+   * Returns true for XHR requests that should block test execution.
+   * Filters out non-XHR traffic and known noise endpoints.
    */
-  public isEssentialRequest(url: string): boolean {
+  public isEssentialRequest(url: string, resourceType: string): boolean {
+    if (resourceType !== 'xhr') return false;
+
     const noisePatterns = [
-      '.download_icon',
-      '.download_list_bar_grp_icon',
-      '.download_form_next_grp_icon',
+      '/detect_change(',
+      '/set_gui_start_use_log_session',
+      'download_icon',
+      'download_list_bar_grp_icon',
+      'download_form_next_grp_icon',
       '/badge()',
       'universal_background_picture',
       'i_ui_theme'
@@ -25,17 +57,44 @@ export class FlightTracker {
     return !noisePatterns.some((pattern) => url.includes(pattern));
   }
 
-  public handleRequestStarted = (url: string) => {
-    if (this.isEssentialRequest(url)) {
-      this.activeRequests.add(url);
-      this.requestsInFlight = this.activeRequests.size;
+  public handleRequestStarted = (url: string, resourceType: string) => {
+    if (this.isEssentialRequest(url, resourceType)) {
+      const wasIdle = this.activeRequests.size === 0;
+      this.activeRequests.set(url, (this.activeRequests.get(url) ?? 0) + 1);
+      this.requestsInFlight++;
+      if (wasIdle) this.eventEmitter.emit('active');
+    }
+  };
+
+  public reset = (): void => {
+    this.activeRequests.clear();
+    this.requestsInFlight = 0;
+  };
+
+  public handleRequestFailed = (url: string) => {
+    const count = this.activeRequests.get(url);
+    if (count !== undefined) {
+      if (count <= 1) {
+        this.activeRequests.delete(url);
+      } else {
+        this.activeRequests.set(url, count - 1);
+      }
+      this.requestsInFlight = Math.max(0, this.requestsInFlight - 1);
+      if (this.requestsInFlight === 0) {
+        this.eventEmitter.emit('idle');
+      }
     }
   };
 
   public handleRequestFinished = (url: string) => {
-    if (this.isEssentialRequest(url)) {
-      this.activeRequests.delete(url);
-      this.requestsInFlight = this.activeRequests.size;
+    const count = this.activeRequests.get(url);
+    if (count !== undefined) {
+      if (count <= 1) {
+        this.activeRequests.delete(url);
+      } else {
+        this.activeRequests.set(url, count - 1);
+      }
+      this.requestsInFlight = Math.max(0, this.requestsInFlight - 1);
       if (this.requestsInFlight === 0) {
         this.eventEmitter.emit('idle');
       }
@@ -64,14 +123,14 @@ export class FlightTracker {
       this.eventEmitter.on('idle', checkIdle);
     });
 
-    const timeoutPromise = new Promise<void>((_, reject) => {
+    const timeoutPromise = new Promise<void>((resolve) => {
       timeoutId = setTimeout(() => {
-        const pending = Array.from(this.activeRequests).join('\n -> ');
-        reject(
-          new Error(
-            `Timeout waiting for ${this.requestsInFlight} requests to complete (${timeout}ms).\nPending Essential Requests:\n -> ${pending}`
-          )
+        const pending = Array.from(this.activeRequests.keys()).join('\n -> ');
+        console.warn(
+          `FlightTracker: timed out after ${timeout}ms waiting for ${this.requestsInFlight} request(s) to complete.\nPending Essential Requests:\n -> ${pending}\nContinuing test execution.`
         );
+        this.reset();
+        resolve();
       }, timeout);
     });
 
@@ -83,4 +142,34 @@ export class FlightTracker {
       this.eventEmitter.removeAllListeners('idle');
     }
   };
+
+  /**
+   * For use after hash-based SPA navigation. Waits for the SPA to begin firing
+   * XHR requests (within `spaStartupTimeout`), then waits for all of them to
+   * settle. If no requests appear within the startup window the page is
+   * considered already loaded.
+   */
+  public waitForNavigationToSettle = async (spaStartupTimeout = 3000): Promise<void> => {
+    if (this.requestsInFlight > 0) {
+      return this.waitToContinue();
+    }
+
+    await new Promise<void>((resolve) => {
+      const timer = setTimeout(() => {
+        this.eventEmitter.off('active', onActive);
+        resolve();
+      }, spaStartupTimeout);
+
+      const onActive = () => {
+        clearTimeout(timer);
+        resolve();
+      };
+
+      this.eventEmitter.once('active', onActive);
+    });
+
+    if (this.requestsInFlight > 0) {
+      await this.waitToContinue();
+    }
+  };
 }

package/helpers/GlobalWaitEventHandler.ts

@@ -2,6 +2,19 @@ import { EventEmitter } from 'node:events';
 import type { Page, Response } from '@playwright/test';
 import { testwiseConfig } from '../services/ConfigBuilder.js';
 
+/**
+ * Waits for a specific response URL pattern before allowing test execution
+ * to continue. Used when you need to block until a known async API response
+ * has arrived, as opposed to waiting for XHR idle (which `FlightTracker` does).
+ *
+ * Attached to the page as `page.waitEventHandler` by the `WaitEventHandler`
+ * page extension. Call `page.waitEventHandler.waitForUrl(pattern)` to block
+ * until a response matching that URL has been received.
+ *
+ * @example
+ * // Wait for a specific background endpoint before asserting:
+ * await page.waitEventHandler.waitForUrl('/api/employees/load');
+ */
 export class GlobalWaitEventHandler {
   private _canContinue: boolean = true;
   private _eventEmitter: EventEmitter = new EventEmitter();

package/helpers/LoginHelper.ts

@@ -9,10 +9,22 @@ import { pollUntil } from './Poll.js';
 const dirname = path.dirname(fileURLToPath(import.meta.url));
 const configFixture = JSON.parse(fs.readFileSync(path.resolve(dirname, '../../config.json'), 'utf-8'));
 
+/**
+ * Handles authentication against the Thinkwise Indicium API and the
+ * web application login screen.
+ *
+ * Exposed on the page fixture via `LoginFeatures` as `page.logIn()`,
+ * `page.logInWithCredentials()`, `page.logInWithOptions()`, and `page.logOut()`.
+ * You do not instantiate `LoginHelper` directly in tests.
+ *
+ * Credentials are read from `Testwise.json` (`environmentSettings.username`
+ * and `environmentSettings.password`) by default, and can be overridden
+ * per-call via `logInWithCredentials()` or `logInWithOptions()`.
+ */
 export class LoginHelper {
   private _page: Page;
-  protected serviceUrl = String(testwiseConfig().get('environmentSettings.serviceUrl'));
-  protected metaEndpoint = String(testwiseConfig().get('environmentSettings.metaEndpoint'));
+  protected serviceUrl = String(testwiseConfig().get('environmentSettings.serviceUrl')).replace(/\/+$/, '');
+  protected metaEndpoint = String(testwiseConfig().get('environmentSettings.metaEndpoint')).replace(/\/+$/, '');
 
   constructor(page: Page) {
     if (!this.serviceUrl || this.serviceUrl === 'undefined') throw new Error('Service URL not found');
@@ -56,20 +68,23 @@ export class LoginHelper {
   }
 
   /**
-   * Navigate to the home page and wait for the menu to load
+   * Navigate to the home page and wait for the menu to load.
    */
   private async navigateHomeAndWaitForMenuToLoad() {
-    const baseUrl = testwiseConfig().get<string>('environmentSettings.baseUrl');
+    const baseUrl = testwiseConfig().get<string>('environmentSettings.baseUrl')?.replace(/\/+$/, '');
+    const minimumTimeout = 60000;
+
     if (!baseUrl) {
       throw new Error('Base URL is not defined in the configuration.');
     }
-    await this._page.goto(baseUrl);
 
-    await this._page.route('**/i_ui_menu?**', (route) => {
-      route.continue();
-    });
+    let timeout = Number(testwiseConfig().get<string | number>('featureSettings.other.loginTimeout') ?? minimumTimeout);
 
-    const timeout = Number(testwiseConfig().get<string | number>('featureSettings.other.loginTimeout') ?? 30_000);
+    if (Number.isNaN(timeout) || timeout < minimumTimeout) {
+      timeout = minimumTimeout;
+    }
+
+    await this._page.goto(baseUrl);
 
     await pollUntil(async () => this._page.url().includes('#application='), {
       timeout,
@@ -93,8 +108,8 @@ export class LoginHelper {
     }
 
     if (serviceUrl && metaEndpoint) {
-      this.serviceUrl = serviceUrl;
-      this.metaEndpoint = metaEndpoint;
+      this.serviceUrl = serviceUrl.replace(/\/+$/, '');
+      this.metaEndpoint = metaEndpoint.replace(/\/+$/, '');
     }
 
     const response = await this._page.request.post(`${this.serviceUrl}/account/api/login`, {
@@ -171,6 +186,10 @@ export class LoginHelper {
     });
   }
 
+  /**
+   * Logs out the current session by POSTing to the logout endpoint (accepts 204 or 401
+   * as valid responses), then clears all browser cookies.
+   */
   public async logOut() {
     const response = await this._page.request.post(`${this.serviceUrl}/account/api/logout`);
 
@@ -188,6 +207,14 @@ export class UserPreferences {
   public readonly guiApplAlias = String(testwiseConfig().get<string>('environmentSettings.guiApplAlias'));
   public readonly url: string;
 
+  /**
+   * Initialises the `UserPreferences` service, resolving the service URL, meta endpoint,
+   * and GUI application alias from config (overridable via optional parameters) and
+   * constructing the full Indicium endpoint URL.
+   * @param requestContext - The Playwright `Page` used to make API requests.
+   * @param serviceUrl - Optional override for the service URL from config.
+   * @param metaEndpoint - Optional override for the meta endpoint from config.
+   */
   constructor(requestContext: Page, serviceUrl?: string, metaEndpoint?: string) {
     this._page = requestContext;
 
@@ -198,9 +225,14 @@ export class UserPreferences {
     if (!metaEndpoint) throw new Error('Meta endpoint not found or is empty');
     if (!this.guiApplAlias) throw new Error('GUI application alias not found or is empty');
 
-    this.url = `${serviceUrl}/${metaEndpoint}/${this.guiApplAlias}`;
+    this.url = `${serviceUrl.replace(/\/+$/, '')}/${metaEndpoint.replace(/\/+$/, '')}/${this.guiApplAlias}`;
   }
 
+  /**
+   * Activates a specific user preference configuration for the current session by POSTing
+   * to the `set_up_configuration` endpoint with the given configuration ID.
+   * @param upConfigurationId - The ID of the user preference configuration to activate.
+   */
   public async run(upConfigurationId: number) {
     const fullUrl = `${this.url}/set_up_configuration`;
 
@@ -211,6 +243,11 @@ export class UserPreferences {
     await this._page.request.post(fullUrl, { headers: { 'Content-Type': 'application/json; charset=utf-8' }, data });
   }
 
+  /**
+   * Disables all active user preferences for the current session by POSTing to the
+   * `disable_up` endpoint.
+   * @returns The raw Playwright `APIResponse`.
+   */
   public async disable(): Promise<APIResponse> {
     const fullUrl = `${this.url}/disable_up`;