@thinkwise/testwise 0.2.62 → 0.2.99

package/services/ConfigBuilder.ts

@@ -2,6 +2,30 @@ import fs from 'node:fs';
 import path from 'node:path';
 import dotenv from 'dotenv';
 
+/**
+ * Reads and exposes the consumer project's `Testwise.json` configuration file
+ * and any `.env` files found in the project root.
+ *
+ * **What it does:**
+ * - Locates `Testwise.json` relative to `process.env.INIT_CWD` (the directory
+ *   from which `npm run` was invoked — i.e. the consumer project root).
+ * - Parses and applies every `.env` file found in that directory into
+ *   `process.env` so environment variables are available to all pipeline steps
+ *   and helpers before they construct.
+ * - Exposes a dot-notation `get<T>(key)` accessor to retrieve deeply nested
+ *   config values without needing to cast or navigate the raw JSON.
+ *
+ * **How to use it in tests or helpers:**
+ * ```ts
+ * import { testwiseConfig } from '../services/ConfigBuilder.js';
+ *
+ * const baseUrl = testwiseConfig().get<string>('application.baseUrl');
+ * const timeout  = testwiseConfig().get<number>('featureSettings.InflightRequests.waitTimeout');
+ * ```
+ *
+ * The exported `testwiseConfig()` function returns a singleton—the file is
+ * only read once per process.
+ */
 class ConfigBuilder {
   private config: Record<string, unknown> | null = null;
 

package/services/IndiciumApi.service.ts

@@ -1,7 +1,7 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 /** biome-ignore-all lint/style/noNonNullAssertion: because null is bad */
 /** biome-ignore-all lint/suspicious/noExplicitAny: because it is necessary */
-import axios, { type AxiosInstance } from 'axios';
+import axios, { type AxiosError, type AxiosInstance } from 'axios';
 import { testwiseConfig } from './ConfigBuilder.js';
 
 export class IndiciumApiService {
@@ -23,6 +23,17 @@ export class IndiciumApiService {
     await this.initPromise;
   }
 
+  private static extractMessage(error: unknown): string {
+    if (axios.isAxiosError(error)) {
+      const axiosErr = error as AxiosError;
+      const status = axiosErr.response?.status;
+      const statusText = axiosErr.response?.statusText;
+      const url = axiosErr.config?.url ?? '';
+      return status ? `HTTP ${status} ${statusText} — ${url}` : axiosErr.message;
+    }
+    return error instanceof Error ? error.message : String(error);
+  }
+
   private async initialize(): Promise<void> {
     const config = testwiseConfig();
     const serviceUrl = config.get<string>('environmentSettings.serviceUrl')?.replace(/\/$/, '');
@@ -66,20 +77,33 @@ export class IndiciumApiService {
         console.warn(`IndiciumApiService: No GUI Application found for alias: ${targetAlias}`);
       }
     } catch (error) {
-      console.error('IndiciumApiService: Verification failed:', error);
+      console.error(`IndiciumApiService: Verification failed: ${IndiciumApiService.extractMessage(error)}`);
     }
   }
 
+  /**
+   * Returns whether the service successfully connected to and verified the configured
+   * GUI application alias. Use this to guard against misconfiguration before making API calls.
+   * @returns `true` if the connection was verified; `false` otherwise.
+   */
   public async canConnectToProject(): Promise<boolean> {
     await this.ensureReady();
     return this.isVerified;
   }
 
+  /**
+   * Returns the resolved GUI application ID for the configured alias, or `null` if
+   * verification failed (e.g. the alias was not found or the service URL is unreachable).
+   */
   public async getVerifiedGuiApplId(): Promise<number | null> {
     await this.ensureReady();
     return this.guiApplId;
   }
 
+  /**
+   * Fetches all UI table records (`i_ui_tab`) for the verified GUI application.
+   * @returns An array of table objects, or an empty array if not verified or on error.
+   */
   public async getAllTables(): Promise<any[]> {
     await this.ensureReady();
     if (!this.isVerified || !this.guiApplId) return [];
@@ -90,11 +114,15 @@ export class IndiciumApiService {
       );
       return response.data?.value || [];
     } catch (error) {
-      console.error('Failed to fetch tables:', error);
+      console.error(`IndiciumApiService: Failed to fetch tables: ${IndiciumApiService.extractMessage(error)}`);
       return [];
     }
   }
 
+  /**
+   * Fetches all UI column records (`i_ui_col`) for the verified GUI application.
+   * @returns An array of column objects, or an empty array if not verified or on error.
+   */
   public async getAllColumns(): Promise<any[]> {
     await this.ensureReady();
     if (!this.isVerified || !this.guiApplId) return [];
@@ -105,11 +133,15 @@ export class IndiciumApiService {
       );
       return response.data?.value || [];
     } catch (error) {
-      console.error('Failed to fetch columns:', error);
+      console.error(`IndiciumApiService: Failed to fetch columns: ${IndiciumApiService.extractMessage(error)}`);
       return [];
     }
   }
 
+  /**
+   * Fetches all lookup table relationships (`i_ui_tab_look_up`) for the verified GUI application.
+   * @returns An array of lookup objects, or an empty array if not verified or on error.
+   */
   public async getLookups(): Promise<any[]> {
     await this.ensureReady();
     if (!this.isVerified || !this.guiApplId) return [];
@@ -120,11 +152,15 @@ export class IndiciumApiService {
       );
       return response.data?.value || [];
     } catch (error) {
-      console.error('Failed to fetch lookups:', error);
+      console.error(`IndiciumApiService: Failed to fetch lookups: ${IndiciumApiService.extractMessage(error)}`);
       return [];
     }
   }
 
+  /**
+   * Fetches all screen component records (`i_ui_screen_component`) for the verified GUI application.
+   * @returns An array of screen component objects, or an empty array if not verified or on error.
+   */
   public async getScreenComponents(): Promise<any[]> {
     await this.ensureReady();
     if (!this.isVerified || !this.guiApplId) return [];
@@ -135,7 +171,9 @@ export class IndiciumApiService {
       );
       return response.data?.value || [];
     } catch (error) {
-      console.error('Failed to fetch screen components:', error);
+      console.error(
+        `IndiciumApiService: Failed to fetch screen components: ${IndiciumApiService.extractMessage(error)}`
+      );
       return [];
     }
   }

package/services/Logger.ts

@@ -4,6 +4,33 @@ 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<string>('featureSettings.logger.logDir') ?? 'logs');
 const logLevel =
   (testwiseConfig().get<string>('featureSettings.logger.logLevel')?.toUpperCase() as LogLevel) ?? LogLevel.ALL;
@@ -173,6 +200,19 @@ function getCallerInfo(): string {
   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?: string, ...optionalParams: unknown[]): void => log(msg, LogLevel.ERROR, ...optionalParams),

package/templates/copilot-instructions.md

@@ -0,0 +1,130 @@
+---
+applyTo: "**"
+---
+# Testwise – GitHub Copilot Instructions
+
+## What Testwise is
+
+**Testwise** (`@thinkwise/testwise`) is the end-to-end test automation library for this Thinkwise application. It wraps Playwright with typed components, generated subject artifacts, and helpers that match the exact UI patterns of Thinkwise applications.
+
+**Always prefer Testwise over raw Playwright.** Using raw Playwright on a Thinkwise application leads to brittle selectors, automation loops, and high token usage. Testwise components are maintained by Thinkwise and absorb UI changes automatically.
+
+---
+
+## Imports
+
+Always import `test` and `expect` from `@thinkwise/testwise`, never from `@playwright/test` directly.
+
+```typescript
+import { test, expect } from '@thinkwise/testwise';
+```
+
+For BDD-style tests:
+
+```typescript
+import { bddTest as test, expect } from '@thinkwise/testwise';
+```
+
+---
+
+## Subject artifacts
+
+Testwise generates typed **subject classes** from the Thinkwise application model. Each class represents one screen and exposes the components on that screen as typed properties. They live in `node_modules/@thinkwise/testwise/test-artifacts/subjects/`.
+
+### Accessing a subject
+
+Use the `page.subject` proxy. The property name is the **exact generated class name** (PascalCase), which encodes the subject name and the screen context:
+
+```typescript
+test('example', async ({ page }) => {
+  const subject = await page.subject.CustomerOrderMain;
+});
+```
+
+> **Never guess a class name.** Always use the MCP `list_artifacts` tool to get the exact name before writing code.
+
+### Screen contexts
+
+| Context  | Description                                    |
+|----------|------------------------------------------------|
+| `Main`   | Primary screen (list/overview)                 |
+| `Detail` | Detail tab or sub-form                         |
+| `Popup`  | Modal/dialog pop-up                            |
+| `Zoom`   | Zoom form that opens over the current screen   |
+
+---
+
+## MCP workflow — do this before writing any test
+
+When `@thinkwise/testwise-mcp` is connected, **call the MCP tools first** to get accurate names and component types. This prevents hallucination and avoids token-expensive correction loops.
+
+1. **`list_subjects`** — see which subjects exist in this application.
+2. **`list_artifacts(subject, screenContext?)`** — get the exact class name and import path.
+3. **`get_components(subject, screenContext)`** — get the property names and component types on the subject class.
+4. Write the test using only the values returned by those tools.
+
+---
+
+## Components
+
+Each subject class exposes typed component properties. Use the component methods — never reach for raw Playwright locators when a component method already exists.
+
+| Component        | Key methods                                                                                         |
+|------------------|-----------------------------------------------------------------------------------------------------|
+| `Grid`           | `getRowByIndex(n)`, `getRowByRowId(id)`, `getCellByExactValue(v)`, `getRowsByColValue(col, v)`, `openExcelStyleFilterPopup(col)` |
+| `Form`           | Field accessors typed to the screen interface                                                       |
+| `ActionBar`      | `getAddButton()`, `getSaveButton()`, `getCancelButton()`, `getDeleteButton()`, `getFilterButton()`, `getSearchInput()` |
+| `FilterForm`     | Filter field accessors                                                                              |
+| `Tab`            | Tab switching                                                                                       |
+| `TreeView`       | Tree node navigation                                                                                |
+| `CombinedFilter` | Combined filter interactions                                                                        |
+
+### Example
+
+```typescript
+test('add and save a record', async ({ page }) => {
+  const subject = await page.subject.CustomerOrderMain;
+
+  await subject.actionBar.getAddButton().click();
+  await subject.form.customerName.fill('ACME Corp');
+  await subject.actionBar.getSaveButton().click();
+});
+```
+
+---
+
+## Controls
+
+For typed input interactions within `Form` components:
+
+| Control class       | Use case                          |
+|---------------------|-----------------------------------|
+| `InputFieldControl` | Standard text/number inputs       |
+| `LookupDropdown`    | Lookup (foreign key) dropdowns    |
+| `FormComboBox`      | Combo box fields                  |
+| `DateControl`       | Date picker fields                |
+| `GridColumnControl` | Column-level controls in a grid   |
+
+---
+
+## Helpers and page extensions
+
+| API                      | Purpose                                               |
+|--------------------------|-------------------------------------------------------|
+| `LoginHelper`            | Authenticate before tests                             |
+| `UserSimulationHelper`   | Simulate a specific user role/identity                |
+| `SubjectNavigator`       | Navigate to a subject by menu path                    |
+| `page.goToDeepLink(...)` | Navigate directly to a Thinkwise deep link            |
+| `page.login(...)`        | Authenticate via page extension                       |
+| `FlightTracker`          | Wait for all pending network requests to complete     |
+| `Ensure`                 | Assertion helpers with built-in retry                 |
+| `Poll`                   | Poll until a condition is met or timeout              |
+
+---
+
+## What NOT to do
+
+- ❌ Do not `import { test } from '@playwright/test'` — always use `@thinkwise/testwise`.
+- ❌ Do not hardcode locators (`page.locator(...)`) for UI interactions a Testwise component already covers.
+- ❌ Do not guess subject class names — use the MCP `list_artifacts` tool.
+- ❌ Do not use `page.fill()` / `page.click()` directly when a typed component method exists.

package/templates/mcp.json

@@ -0,0 +1,9 @@
+{
+  "servers": {
+    "testwise": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["./node_modules/@thinkwise/testwise-mcp/dist/index.js"]
+    }
+  }
+}