@thinkwise/testwise 0.2.67 → 0.2.103

package/mcp/ArtifactResolver.ts

@@ -0,0 +1,296 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { PipelinePaths } from '../artifact-builder/helpers/PipelinePaths.js';
+import type { ScreenContext } from '../interfaces/ISubjectDetail.js';
+
+/** All known screen context suffixes, ordered longest-first to avoid prefix clashes. */
+const screenContexts: ScreenContext[] = ['Detail', 'Popup', 'Main', 'Zoom'];
+
+/** Describes a single generated subject class discovered in the test-artifacts directory. */
+export interface SubjectArtifactInfo {
+  /** PascalCase subject folder name (e.g. `"CustomerOrder"`). */
+  subject: string;
+  /** Exact generated class name (e.g. `"CustomerOrderMain"`). */
+  className: string;
+  /** Screen context encoded in the class name. */
+  screenContext: ScreenContext;
+  /**
+   * Module specifier that importing code should use, relative to the consumer
+   * project root (e.g. `"@thinkwise/testwise/test-artifacts/subjects/CustomerOrder/CustomerOrderMain.js"`).
+   */
+  importPath: string;
+}
+
+/** Describes a single field or column on a screen interface. */
+export interface ScreenFieldInfo {
+  /** camelCase property name as it appears on the screen interface (e.g. `"customerName"`, `"orderDate"`). */
+  propertyName: string;
+  /**
+   * Testwise control type suffix indicating which control helper to use
+   * (e.g. `"Field"`, `"Lookup"`, `"Dropdown"`, `"DatePicker"`, `"Checkbox"`, `"Textarea"`, `"ComboBox"`).
+   * Derived from the property name suffix in the generated interface.
+   */
+  controlType: string;
+  /** The component this field belongs to — `"Form"` or `"Grid"`. */
+  componentType: 'Form' | 'Grid';
+}
+
+/** Describes a single typed component property on a generated subject class. */
+export interface ComponentInfo {
+  /** camelCase property name as declared on the subject class (e.g. `"grid"`, `"actionBar"`). */
+  propertyName: string;
+  /** Testwise component class name (e.g. `"Grid"`, `"ActionBar"`, `"Form"`). */
+  componentType: string;
+}
+
+/**
+ * Runtime service that reads the generated test-artifact files to answer
+ * questions about available subjects, their screen-context variants, and the
+ * components exposed on each subject class.
+ *
+ * Intended to be used by the `@thinkwise/testwise-mcp` server so that AI
+ * tooling can discover the correct class names and component properties before
+ * generating test code — without having to guess or hallucinate names.
+ */
+/**
+ * Runtime service that reads the generated test-artifact files to answer
+ * questions about available subjects, their screen-context variants, and the
+ * components exposed on each subject class.
+ *
+ * **What it does:** The `@thinkwise/testwise-mcp` MCP server calls these
+ * methods to surface information to AI tooling (e.g. GitHub Copilot agents)
+ * so the AI can write correct Testwise tests without guessing class names,
+ * property names, or field names.
+ *
+ * **How to use it (as a consumer of the MCP server):** You don't call this
+ * class directly — use the MCP tools:
+ * - `list_subjects()` — all available subject folder names
+ * - `list_artifacts(subject?, screenContext?)` — exact class names + import paths
+ * - `get_components(subject, screenContext)` — component properties on a class
+ * - `get_screen_interface(subject, screenContext)` — field/column names + control types
+ *
+ * **For contributors:** This class is intentionally side-effect-free — it
+ * only reads files and never writes anything. Do not add browser-interaction
+ * logic here.
+ *
+ * @example
+ * // Used internally by the MCP server:
+ * const resolver = new ArtifactResolver();
+ * const subjects = resolver.listSubjects();
+ * const artifacts = resolver.listArtifacts('Employee', 'Main');
+ */
+export class ArtifactResolver {
+  private readonly _paths: PipelinePaths;
+
+  constructor(paths?: PipelinePaths) {
+    this._paths = paths ?? new PipelinePaths();
+  }
+
+  /**
+   * Returns all subject folder names (PascalCase) that have been generated
+   * into the test-artifacts directory.
+   *
+   * @example
+   * resolver.listSubjects();
+   * // → ["CustomerOrder", "Product", "Employee"]
+   */
+  public listSubjects(): string[] {
+    const subjectsDir = this._paths.subjects;
+
+    if (!fs.existsSync(subjectsDir)) return [];
+
+    return fs.readdirSync(subjectsDir).filter((entry) => fs.statSync(path.join(subjectsDir, entry)).isDirectory());
+  }
+
+  /**
+   * Returns all artifacts for the given subject, optionally filtered to a
+   * specific screen context.
+   *
+   * When `subject` is omitted every generated artifact is returned.
+   *
+   * @example
+   * // All screen contexts for one subject
+   * resolver.listArtifacts('CustomerOrder');
+   * // → [{ className: "CustomerOrderMain", screenContext: "Main", ... }, ...]
+   *
+   * @example
+   * // One specific artifact
+   * resolver.listArtifacts('CustomerOrder', 'Main');
+   * // → [{ className: "CustomerOrderMain", screenContext: "Main", ... }]
+   */
+  public listArtifacts(subject?: string, screenContext?: ScreenContext): SubjectArtifactInfo[] {
+    const subjects = subject ? [subject] : this.listSubjects();
+    const results: SubjectArtifactInfo[] = [];
+
+    for (const subjectName of subjects) {
+      const subjectDir = path.join(this._paths.subjects, subjectName);
+
+      if (!fs.existsSync(subjectDir)) continue;
+
+      const files = fs.readdirSync(subjectDir).filter((f) => f.endsWith('.ts') && f !== 'index.ts');
+
+      for (const file of files) {
+        const className = file.replace('.ts', '');
+        const context = this.inferScreenContext(className);
+
+        if (!context) continue;
+        if (screenContext && context !== screenContext) continue;
+
+        results.push({
+          subject: subjectName,
+          className,
+          screenContext: context,
+          importPath: `@thinkwise/testwise/test-artifacts/subjects/${subjectName}/${className}.js`
+        });
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Returns the typed component properties declared on the generated subject
+   * class for the given subject + screen context combination.
+   *
+   * @example
+   * resolver.getComponents('CustomerOrder', 'Main');
+   * // → [
+   * //   { propertyName: "grid",      componentType: "Grid"      },
+   * //   { propertyName: "actionBar", componentType: "ActionBar" },
+   * //   { propertyName: "filterForm",componentType: "FilterForm"},
+   * // ]
+   */
+  public getComponents(subject: string, screenContext: ScreenContext): ComponentInfo[] {
+    const artifacts = this.listArtifacts(subject, screenContext);
+
+    if (artifacts.length === 0) return [];
+
+    const filePath = path.join(this._paths.subjects, subject, `${artifacts[0].className}.ts`);
+
+    if (!fs.existsSync(filePath)) return [];
+
+    return this.parseComponentProperties(fs.readFileSync(filePath, 'utf-8'));
+  }
+
+  /**
+   * Returns all fields and columns declared on the generated screen interface
+   * for the given subject + screen context combination.
+   *
+   * The interface lives in `test-artifacts/screens/` and contains every field
+   * name, column name, and control type for the screen — enough for an AI to
+   * write a complete, accurate test without inspecting a live browser.
+   *
+   * @example
+   * resolver.getScreenInterface('CustomerOrder', 'Main');
+   * // → [
+   * //   { propertyName: "customerName", controlType: "Field",      componentType: "Form" },
+   * //   { propertyName: "orderDate",    controlType: "DatePicker",  componentType: "Form" },
+   * //   { propertyName: "status",       controlType: "Lookup",      componentType: "Form" },
+   * //   { propertyName: "orderId",      controlType: "Column",      componentType: "Grid" },
+   * // ]
+   */
+  public getScreenInterface(subject: string, screenContext: ScreenContext): ScreenFieldInfo[] {
+    const artifacts = this.listArtifacts(subject, screenContext);
+    if (artifacts.length === 0) return [];
+
+    // Component files live in Components/ subfolder under the subject folder
+    const componentsDir = path.join(this._paths.subjects, subject, 'Components');
+    if (!fs.existsSync(componentsDir)) return [];
+
+    const results: ScreenFieldInfo[] = [];
+    const componentFiles = fs.readdirSync(componentsDir).filter((f) => f.endsWith('.ts'));
+
+    for (const file of componentFiles) {
+      const content = fs.readFileSync(path.join(componentsDir, file), 'utf-8');
+      const interfaceName = file.replace('.ts', '');
+      const fields = this.parseScreenInterface(content, interfaceName);
+      results.push(...fields);
+    }
+
+    return results;
+  }
+
+  // ── Private helpers ────────────────────────────────────────────────────────
+
+  private inferScreenContext(className: string): ScreenContext | undefined {
+    for (const ctx of screenContexts) {
+      if (className.endsWith(ctx)) return ctx;
+    }
+    return undefined;
+  }
+
+  /**
+   * Parses component properties from a generated subject class.
+   *
+   * Generated classes declare properties without `public`:
+   *   actionBarVXE6V0YT: ActionBar;
+   *   gridQT3UL7F8: EmployeeGrid;
+   */
+  private parseComponentProperties(content: string): ComponentInfo[] {
+    const results: ComponentInfo[] = [];
+
+    // Match class-body property declarations: "  name: Type;" (no public keyword)
+    // Excludes private fields (_name), constructor, and method declarations
+    const propertyRegex = /^\s{4}(\w+)\s*:\s*(\w+)\s*;/gm;
+
+    for (let match = propertyRegex.exec(content); match !== null; match = propertyRegex.exec(content)) {
+      const propertyName = match[1];
+      const componentType = match[2];
+
+      if (propertyName.startsWith('_')) continue;
+      if (['string', 'number', 'boolean', 'Page', 'Locator'].includes(componentType)) continue;
+
+      results.push({ propertyName, componentType });
+    }
+
+    return results;
+  }
+
+  /**
+   * Parses fields/columns from the Components/ subfolder files for a subject.
+   *
+   * Generated component files (e.g. EmployeeGrid.ts, EmployeeForm.ts) declare
+   * getters like:
+   *   public get firstNameColumn(): IGridColumnControl { ... }
+   *   public get firstNameField(): IInputFieldControl { ... }
+   */
+  private parseScreenInterface(content: string, interfaceName: string): ScreenFieldInfo[] {
+    const results: ScreenFieldInfo[] = [];
+
+    // Match readonly interface members: "  readonly bioColumn: IGridColumnControl;"
+    const interfaceRegex = /^\s+readonly\s+(\w+)\s*:\s*(I?\w+Control)\s*;/gm;
+    for (let match = interfaceRegex.exec(content); match !== null; match = interfaceRegex.exec(content)) {
+      const propertyName = match[1];
+      const rawType = match[2];
+      const controlType = this.inferControlType(rawType, propertyName);
+      const componentType = interfaceName.toLowerCase().includes('grid') ? 'Grid' : 'Form';
+      results.push({ propertyName, controlType, componentType: componentType as 'Form' | 'Grid' });
+    }
+
+    return results;
+  }
+
+  private inferControlType(rawType: string, propertyName: string): string {
+    const typeMap: Record<string, string> = {
+      IGridColumnControl: 'Column',
+      GridColumnControl: 'Column',
+      IInputFieldControl: 'Field',
+      InputFieldControl: 'Field',
+      ILookupDropdown: 'Lookup',
+      LookupDropdown: 'Lookup',
+      IFormComboBox: 'ComboBox',
+      FormComboBox: 'ComboBox',
+      IDateControl: 'DatePicker',
+      DateControl: 'DatePicker',
+      ICheckboxControl: 'Checkbox',
+      CheckboxControl: 'Checkbox',
+      ITextareaControl: 'Textarea',
+      TextareaControl: 'Textarea'
+    };
+
+    if (typeMap[rawType]) return typeMap[rawType];
+
+    const suffixMatch = propertyName.match(/(Field|Lookup|Dropdown|DatePicker|Checkbox|Textarea|ComboBox|Column)$/i);
+    return suffixMatch ? suffixMatch[1] : rawType;
+  }
+}

package/mcp/index.ts

@@ -0,0 +1,2 @@
+export type { ComponentInfo, ScreenFieldInfo, SubjectArtifactInfo } from './ArtifactResolver.js';
+export { ArtifactResolver } from './ArtifactResolver.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkwise/testwise",
-  "version": "0.2.67",
+  "version": "0.2.103",
   "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;
   }