@thinkwise/testwise 0.2.62 → 0.2.99

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkwise/testwise",
-  "version": "0.2.62",
+  "version": "0.2.99",
   "main": "dist/index.js",
   "type": "module",
   "bin": {
@@ -11,25 +11,29 @@
     "lint": "eslint ./ --cache --ignore-pattern .gitignore",
     "format:fix": "run-s \"lint --fix\" && biome check --fix --unsafe",
     "format:check": "run-s \"lint \" && biome check",
-    "postinstall": "node scripts/main.js postinstall"
+    "postinstall": "node scripts/main.js postinstall",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "diagram": "node scripts/main.js diagram"
   },
   "keywords": [],
   "author": "",
   "license": "ISC",
   "description": "",
   "dependencies": {
-    "@thinkwise/backups": "^1.0.16",
-    "@types/node": "^22.15.29",
+    "@thinkwise/backups": "^1.0.20",
     "axios": "^1.9.0",
     "chalk": "^5.4.1",
     "change-case": "^5.4.4",
     "csv-parse": "^5.6.0",
     "dotenv": "^17.2.2",
-    "playwright-bdd": "^8.4.2",
+    "playwright-bdd": "^6.6.0",
     "prettier": "^3.8.1",
     "prompts": "^2.4.2",
     "quicktype-core": "^23.2.6",
     "rimraf": "^6.0.1",
+    "ts-morph": "^28.0.0",
     "ts-node": "^10.9.2",
     "typescript": "^5.8.3"
   },
@@ -37,12 +41,15 @@
     "@playwright/test": "^1.56.1"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.8",
+    "@biomejs/biome": "^2.4.12",
     "@eslint/js": "^9.28.0",
+    "@types/node": "^25.6.0",
+    "@vitest/coverage-v8": "^4.1.5",
     "eslint": "^9.39.2",
     "eslint-plugin-playwright": "^2.2.0",
     "npm-run-all": "^4.1.5",
-    "typescript-eslint": "^8.34.0"
+    "typescript-eslint": "^8.34.0",
+    "vitest": "^4.1.5"
   },
   "exports": {
     ".": {
@@ -52,6 +59,10 @@
     "./subjects/*": {
       "types": "./dist/test-artifacts/subjects/*/index.d.ts",
       "import": "./dist/test-artifacts/subjects/*/index.js"
+    },
+    "./helpers/SubjectNavigator": {
+      "types": "./dist/helpers/SubjectNavigator.d.ts",
+      "import": "./dist/helpers/SubjectNavigator.js"
     }
   },
   "files": [
@@ -74,6 +85,7 @@
     "test-artifacts/",
     "artifact-builder/",
     "**/config.json",
-    "templates/"
+    "templates/",
+    "mcp/"
   ]
 }

package/page-extensions/GlobalComponents.ts

@@ -9,6 +9,27 @@ import {
 } from '../components/index.js';
 import type { Test } from '../types/Test.js';
 
+/**
+ * Holds pre-constructed instances of the Thinkwise UI components that are
+ * present globally across all screens (not tied to any specific subject).
+ *
+ * Accessed via `page.components` in tests. Available properties:
+ * - `popUp` — the main overlay/modal dialog
+ * - `export` — the export panel triggered from a grid or list
+ * - `snackBar` — the toast notification bar
+ * - `topBar` — the application top bar (breadcrumbs, user menu)
+ * - `listBarMenu` — the hamburger / list-bar dropdown menu
+ * - `managePrefilterPopup` — the "Manage prefilter" popup dialog
+ *
+ * @example
+ * ```ts
+ * // Confirm a save popup:
+ * await page.components.popUp.confirm();
+ *
+ * // Check a snackbar message:
+ * await expect(page.components.snackBar.message).toHaveText('Saved successfully');
+ * ```
+ */
 class GlobalComponents {
   public popUp: PopUpComponent;
   public export: ExportComponent;
@@ -36,6 +57,12 @@ declare module '@playwright/test' {
 export class Components {
   private _test: Test;
 
+  /**
+   * Extends the Playwright `Test` fixture to attach a `GlobalComponents` instance to
+   * `page.components` before each test, providing access to shared UI components
+   * such as `popUp`, `export`, `snackBar`, `topBar`, `listBarMenu`, and `managePrefilterPopup`.
+   * @param test - The Playwright `Test` fixture to extend.
+   */
   constructor(test: Test) {
     this._test = test.extend({
       page: async ({ page }, use) => {
@@ -46,6 +73,9 @@ export class Components {
     });
   }
 
+  /**
+   * Returns the extended `Test` fixture with `page.components` wired up.
+   */
   get test() {
     return this._test;
   }

package/page-extensions/GoToDeepLink.ts

@@ -9,6 +9,12 @@ declare module '@playwright/test' {
 export class GoToDeepLink {
   private _test: Test;
 
+  /**
+   * Extends the Playwright `Test` fixture to add a `page.goToDeepLink(deepLink)` method.
+   * The method preserves the current `#application=` hash segment and appends the given
+   * deep link path before navigating to the resulting URL.
+   * @param test - The Playwright `Test` fixture to extend.
+   */
   constructor(test: Test) {
     this._test = test.extend({
       page: async ({ page }, use) => {
@@ -39,6 +45,9 @@ export class GoToDeepLink {
     });
   }
 
+  /**
+   * Returns the extended `Test` fixture with `page.goToDeepLink` wired up.
+   */
   get test() {
     return this._test;
   }

package/page-extensions/LoginFeatures.ts

@@ -15,6 +15,11 @@ export class LoginFeatures {
   private _loginHelper: LoginHelper | undefined;
   private _test: Test;
 
+  /**
+   * Extends the Playwright `Test` fixture to attach `logIn`, `logInWithCredentials`,
+   * `logInWithOptions`, and `logOut` methods to the page, backed by `LoginHelper`.
+   * @param test - The Playwright `Test` fixture to extend.
+   */
   constructor(test: Test) {
     this._test = test.extend({
       page: async ({ page }, use) => {
@@ -49,6 +54,9 @@ export class LoginFeatures {
     return this._loginHelper;
   }
 
+  /**
+   * Returns the extended `Test` fixture with login methods wired up on `page`.
+   */
   get test() {
     return this._test;
   }

package/page-extensions/SubjectRegistry.ts

@@ -1,12 +1,44 @@
 import type { Test } from '../types/Test.js';
+
+/**
+ * Playwright page-extension that makes every generated subject class available
+ * on the `page.subject` proxy during tests.
+ *
+ * **What it does:** At test startup it reads the registered subject list and
+ * wires up a `page.subject` property. Accessing `page.subject.EmployeeMain`
+ * returns an instance of the generated `EmployeeMain` class, which exposes
+ * typed component properties (`form`, `grid`, `actionBar`, etc.) and a
+ * `goTo()` method that navigates to that screen.
+ *
+ * **Important — do not edit this file directly.** The real implementation is
+ * generated from `templates/SubjectRegistry.template.ts` by the
+ * `SubjectRegistration` pipeline step. Any changes made here will be
+ * overwritten on the next `testwise sync`. Edit the template instead.
+ *
+ * @example
+ * ```ts
+ * // In a test:
+ * const employee = await page.subject.EmployeeEditable1Main.goTo();
+ * await employee.form.firstNameField.fill('Jane');
+ * await employee.actionBar.save();
+ * ```
+ */
 export class SubjectRegistry {
   private _test: Test;
 
+  /**
+   * Stores the provided `Test` instance. The full implementation of this class is
+   * generated from the template in the templates folder — do not edit here directly.
+   * @param test - The Playwright `Test` fixture.
+   */
   constructor(test: Test) {
     // Implementation of this class is in the templates folder, don't edit here
     this._test = test;
   }
 
+  /**
+   * Returns the stored `Test` fixture.
+   */
   get test() {
     return this._test;
   }

package/page-extensions/UserSimulation.ts

@@ -9,10 +9,28 @@ declare module '@playwright/test' {
   }
 }
 
+/**
+ * Playwright fixture layer that adds user-simulation methods to the page:
+ * `page.simulateUser(username)`, `page.getSimulatedUser()`, and
+ * `page.stopSimulation()`.
+ *
+ * These methods switch the active identity inside the running Thinkwise
+ * application without a full logout/login cycle, enabling RBAC tests.
+ *
+ * @example
+ * await page.simulateUser('manager@example.com');
+ * // assert manager-only visibility ...
+ * await page.stopSimulation();
+ */
 export class UserSimulation {
   private _userSimulationHelper: UserSimulationHelper | undefined;
   private _test: Test;
 
+  /**
+   * Extends the Playwright `Test` fixture to attach `simulateUser`, `getSimulatedUser`,
+   * and `stopSimulation` methods to the page, backed by `UserSimulationHelper`.
+   * @param test - The Playwright `Test` fixture to extend.
+   */
   constructor(test: Test) {
     this._test = test.extend({
       page: async ({ page }, use) => {
@@ -43,6 +61,9 @@ export class UserSimulation {
     return this._userSimulationHelper;
   }
 
+  /**
+   * Returns the extended `Test` fixture with user simulation methods wired up on `page`.
+   */
   get test() {
     return this._test;
   }

package/page-extensions/WaitEventHandler.ts

@@ -7,9 +7,26 @@ declare module '@playwright/test' {
   }
 }
 
+/**
+ * Playwright fixture layer that attaches a `GlobalWaitEventHandler` instance
+ * to `page.waitEventHandler` before each test.
+ *
+ * Use `page.waitEventHandler` when you need to block test execution until a
+ * specific URL pattern has been responded to — for example, waiting for a
+ * background data-load endpoint before asserting on results.
+ *
+ * @example
+ * await page.waitEventHandler.waitForUrl('/api/employees/load');
+ * await expect(subject.grid.rows()).toHaveCount(10);
+ */
 export class WaitEventHandler {
   private _test: Test;
 
+  /**
+   * Extends the Playwright `Test` fixture to attach a `GlobalWaitEventHandler` instance
+   * to `page.waitEventHandler` before each test.
+   * @param test - The Playwright `Test` fixture to extend.
+   */
   constructor(test: Test) {
     this._test = test.extend({
       page: async ({ page }, use) => {
@@ -20,6 +37,9 @@ export class WaitEventHandler {
     });
   }
 
+  /**
+   * Returns the extended `Test` fixture with `page.waitEventHandler` wired up.
+   */
   get test() {
     return this._test;
   }

package/page-overrides/ClickOverride.ts

@@ -1,80 +1,58 @@
-import type { Locator, Page } from '@playwright/test';
+import type { Locator } from '@playwright/test';
 import { FlightTracker } from '../helpers/FlightTracker.js';
 import { testwiseConfig } from '../services/ConfigBuilder.js';
 import type { Test } from '../types/Test.js';
 
 const waitForRequestsToComplete =
   testwiseConfig().get<boolean>('featureSettings.InflightRequests.waitForRequestsToComplete') ?? true;
-const continueOnError = testwiseConfig().get<boolean>('featureSettings.InflightRequests.continueOnError') ?? true;
 
+/**
+ * Playwright fixture layer that wraps every Locator `click()` call to wait
+ * for in-flight XHR requests to settle before returning control to the test.
+ *
+ * **Why this exists:** The Thinkwise application fires XHR calls immediately
+ * after a click (save, navigation, data load). Without this override a test
+ * that clicks a button and then immediately reads a value races against the
+ * server response. `ClickOverride` uses `FlightTracker` under the hood to
+ * block until all relevant requests finish.
+ *
+ * **How to disable** (if a specific test must opt out):
+ * Set `featureSettings.InflightRequests.waitForRequestsToComplete: false` in
+ * `Testwise.json` — but this is rarely needed.
+ */
 export class ClickOverride {
   private _test: Test;
-  private _page: Page | null = null;
-  private flightTracker: FlightTracker = new FlightTracker();
 
+  /**
+   * Extends the Playwright `Test` fixture to wrap every locator's `click` method with
+   * in-flight XHR tracking via `FlightTracker`, waiting for all relevant requests to
+   * settle after each click. Behaviour is configurable via `featureSettings.InflightRequests`.
+   * @param test - The Playwright `Test` fixture to extend.
+   */
   constructor(test: Test) {
     this._test = test.extend({
       page: async ({ page }, use) => {
-        this._page = page;
+        const flightTracker = new FlightTracker();
 
-        const isTrackable = (url: string, resourceType: string) => {
-          const lowerUrl = url.toLowerCase();
+        page.on('request', (request) => {
+          flightTracker.handleRequestStarted(request.url(), request.resourceType());
+        });
 
-          return (
-            resourceType === 'xhr' &&
-            !lowerUrl.includes('/detect_change(') &&
-            !lowerUrl.includes('/set_gui_start_use_log_session') &&
-            !lowerUrl.includes('download_icon') &&
-            !lowerUrl.includes('download_list_bar_grp_icon') &&
-            !lowerUrl.includes('/badge()')
-          );
-        };
+        page.on('response', (response) => {
+          flightTracker.handleRequestFinished(response.request().url());
+        });
+
+        page.on('requestfailed', (request) => {
+          flightTracker.handleRequestFailed(request.url());
+        });
 
         const overrideClickMethod = (locator: Locator): Locator => {
           const originalClickMethod = locator.click.bind(locator);
 
-          page.on('request', (request) => {
-            if (isTrackable(request.url(), request.resourceType())) {
-              this.flightTracker.requestsInFlight++;
-            }
-          });
-
-          page.on('response', (response) => {
-            if (isTrackable(response.request().url(), response.request().resourceType())) {
-              if (this.flightTracker.requestsInFlight > 0) {
-                this.flightTracker.requestsInFlight--;
-              }
-              if (this.flightTracker.requestsInFlight === 0) {
-                this.flightTracker.eventEmitter.emit('idle');
-              }
-            }
-          });
-
           locator.click = async (options) => {
             await originalClickMethod(options);
             if (waitForRequestsToComplete) {
-              try {
-                await this.flightTracker.waitToContinue();
-              } catch (error) {
-                console.warn('Exception while waiting for inflight requests to finish:', error);
-                if (this._page) {
-                  const inflightRequests = await this._page.evaluate(() => {
-                    return performance
-                      .getEntriesByType('resource')
-                      .filter((entry) => {
-                        const res = entry as PerformanceResourceTiming;
-                        return (
-                          res.initiatorType === 'xmlhttprequest' &&
-                          !res.name.includes('/detect_change(') &&
-                          !res.name.includes('/set_gui_start_use_log_session')
-                        );
-                      })
-                      .map((entry) => (entry as PerformanceResourceTiming).name);
-                  });
-                  console.debug('Current inflight XHR requests:', inflightRequests);
-                }
-                if (!continueOnError) throw error;
-              }
+              await flightTracker.waitToContinue();
             }
             return;
           };
@@ -122,6 +100,9 @@ export class ClickOverride {
     });
   }
 
+  /**
+   * Returns the extended `Test` fixture with the click override active.
+   */
   get test() {
     return this._test;
   }

package/page-overrides/FillOverride.ts

@@ -7,10 +7,41 @@ const requestWatchlist: string[] = testwiseConfig().get<string[]>('featureSettin
 const waitForRequestsToComplete =
   testwiseConfig().get<boolean>('featureSettings.InflightRequests.waitForRequestsToComplete') ?? true;
 
+const locatorMethods = [
+  'locator',
+  'getByText',
+  'getByTestId',
+  'getByAltText',
+  'getByLabel',
+  'getByRole',
+  'getByPlaceholder',
+  'getByTitle'
+] as const;
+
+/**
+ * Playwright fixture layer that wraps every Locator `fill()` call to wait
+ * for in-flight XHR requests to settle before returning control to the test.
+ *
+ * **Why this exists:** After filling a lookup or auto-complete field the
+ * Thinkwise application fires XHR calls to search/resolve the typed value.
+ * Without this override, subsequent assertions or interactions race against
+ * those server responses. `FillOverride` uses `FlightTracker` to block until
+ * all relevant requests on the watchlist finish.
+ *
+ * The `featureSettings.InflightRequests.paths` list in `Testwise.json`
+ * controls which API endpoints are watched during fill operations.
+ */
 export class FillOverride {
   private _test: Test;
   private flightTracker: FlightTracker = new FlightTracker();
 
+  /**
+   * Extends the Playwright `Test` fixture to wrap every locator's `fill` method:
+   * waits for watched in-flight requests to settle, fills the element, and — for
+   * qualifying form fields — triggers a `/staged` response wait and blurs the element
+   * if the value changed. Watchlist and behaviour are configurable via `featureSettings`.
+   * @param test - The Playwright `Test` fixture to extend.
+   */
   constructor(test: Test) {
     this._test = test.extend({
       page: async ({ page }, use) => {
@@ -35,101 +66,56 @@ export class FillOverride {
         }
 
         const overrideFillMethod = (locator: Locator) => {
-          const originalFillMethod = locator.fill.bind(locator);
+          const originalFill = locator.fill.bind(locator);
 
           locator.fill = async (value, options) => {
-            try {
-              if (waitForRequestsToComplete) await this.flightTracker.waitToContinue();
-            } catch (e) {
-              console.warn('Exception:', e);
-              this.flightTracker.requestsInFlight = 0;
-            }
-
-            const currentValue = await locator.inputValue();
-            const valueIsDifferent = currentValue !== value;
-
-            const formFieldTestIdPrefix: string = 'form-field__';
-
-            const isQualifyingFormField = await locator.evaluate((el, formFieldTestIdPrefix) => {
-              const elementTestId = el.getAttribute('data-testid');
+            if (waitForRequestsToComplete) await this.flightTracker.waitToContinue();
 
-              const parentWithFormSectionTestId = el.closest('[data-testid^="form-section__"]');
+            const [valueIsDifferent, isQualifyingFormField] = await Promise.all([
+              locator.inputValue().then((v) => v !== value),
+              locator.evaluate((el) => {
+                const testId = el.getAttribute('data-testid');
+                return (
+                  !!testId && testId.includes('form-field__') && el.closest('[data-testid^="form-section__"]') !== null
+                );
+              })
+            ]);
 
-              if (elementTestId) {
-                return elementTestId.includes(formFieldTestIdPrefix) && parentWithFormSectionTestId !== null;
-              }
-              return false;
-            }, formFieldTestIdPrefix);
-
-            if (valueIsDifferent && isQualifyingFormField) {
-              await page.waitEventHandler.waitForCanContinue();
-              page.waitEventHandler.waitForResponse('/staged');
-            }
+            await page.waitEventHandler.waitForCanContinue();
 
-            await originalFillMethod(value, options);
+            await originalFill(value, options);
 
             if (isQualifyingFormField) {
+              if (valueIsDifferent) page.waitEventHandler.waitForResponse('/staged');
               await locator.evaluate((el) => {
-                const ariaExpanded = el.getAttribute('aria-expanded');
-
-                if (!ariaExpanded) el.blur();
+                if (!el.getAttribute('aria-expanded')) el.blur();
               });
             }
           };
 
-          const originalLocatorMethod = locator.locator.bind(locator);
-          locator.locator = (...args) => overrideFillMethod(originalLocatorMethod(...args));
-
-          const originalGetByTextMethod = locator.getByText.bind(locator);
-          locator.getByText = (...args) => overrideFillMethod(originalGetByTextMethod(...args));
-
-          const originalGetByTestIdMethod = locator.getByTestId.bind(locator);
-          locator.getByTestId = (...args) => overrideFillMethod(originalGetByTestIdMethod(...args));
-
-          const originalGetByAltTextMethod = locator.getByAltText.bind(locator);
-          locator.getByAltText = (...args) => overrideFillMethod(originalGetByAltTextMethod(...args));
-
-          const originalGetByLabelMethod = locator.getByLabel.bind(locator);
-          locator.getByLabel = (...args) => overrideFillMethod(originalGetByLabelMethod(...args));
-
-          const originalGetByRoleMethod = locator.getByRole.bind(locator);
-          locator.getByRole = (...args) => overrideFillMethod(originalGetByRoleMethod(...args));
-
-          const originalGetByPlaceholderMethod = locator.getByPlaceholder.bind(locator);
-          locator.getByPlaceholder = (...args) => overrideFillMethod(originalGetByPlaceholderMethod(...args));
-
-          const originalGetByTitleMethod = locator.getByTitle.bind(locator);
-          locator.getByTitle = (...args) => overrideFillMethod(originalGetByTitleMethod(...args));
+          for (const method of locatorMethods) {
+            const original = (locator[method] as (...args: unknown[]) => Locator).bind(locator);
+            (locator as unknown as Record<string, (...args: unknown[]) => Locator>)[method] = (...args: unknown[]) =>
+              overrideFillMethod(original(...args));
+          }
 
           return locator;
         };
 
-        // Override the locator method on the page object
-        const originalLocator = page.locator.bind(page);
-        page.locator = (...args) => overrideFillMethod(originalLocator(...args));
-
-        const originalGetByTestId = page.getByTestId.bind(page);
-        const originalGetByAltText = page.getByAltText.bind(page);
-        const originalGetByLabel = page.getByLabel.bind(page);
-        const originalGetByRole = page.getByRole.bind(page);
-        const originalGetByPlaceholder = page.getByPlaceholder.bind(page);
-        const originalGetByText = page.getByText.bind(page);
-        const originalGetByTitle = page.getByTitle.bind(page);
-
-        // Override other top-level methods as before
-        page.getByTestId = (...args) => overrideFillMethod(originalGetByTestId(...args));
-        page.getByAltText = (...args) => overrideFillMethod(originalGetByAltText(...args));
-        page.getByLabel = (...args) => overrideFillMethod(originalGetByLabel(...args));
-        page.getByRole = (...args) => overrideFillMethod(originalGetByRole(...args));
-        page.getByPlaceholder = (...args) => overrideFillMethod(originalGetByPlaceholder(...args));
-        page.getByText = (...args) => overrideFillMethod(originalGetByText(...args));
-        page.getByTitle = (...args) => overrideFillMethod(originalGetByTitle(...args));
+        for (const method of locatorMethods) {
+          const original = (page[method] as (...args: unknown[]) => Locator).bind(page);
+          (page as unknown as Record<string, (...args: unknown[]) => Locator>)[method] = (...args: unknown[]) =>
+            overrideFillMethod(original(...args));
+        }
 
         await use(page);
       }
     });
   }
 
+  /**
+   * Returns the extended `Test` fixture with the fill override active.
+   */
   get test() {
     return this._test;
   }

package/promptCredentials.js

@@ -84,7 +84,7 @@ const questions = [
 (async () => {
   const credentialsResponse = await prompts(questions);
 
-  if (!credentialsResponse || !credentialsResponse.username || !credentialsResponse.password) {
+  if (!credentialsResponse?.username || !credentialsResponse.password) {
     exitWithError('Username or password was not given');
   }
 

package/scripts/Testwise.template.json

@@ -22,7 +22,7 @@
       "paths" : ["/stage", "/layout()", "/context()"]
     },
     "other" : {
-      "loginTimeout" : 30000
+      "loginTimeout" : 60000
     }
   }
 }