@thinkwise/testwise 0.2.62 → 0.2.99

package/components/grid/Grid.ts

@@ -1,15 +1,35 @@
 import type { Locator, Page } from '@playwright/test';
 import { pollUntil } from '../../helpers/Poll.js';
 import { escapeRegex } from '../../helpers/RegexHelper.js';
+import { ExcelStyleFilterPopup } from '../index.js';
 import { GridObjects } from './GridObjects.js';
 
+/**
+ * Wraps a Thinkwise grid (list view) component. Provides row/cell navigation,
+ * filtering, sorting, and value-reading helpers.
+ *
+ * In generated subject classes, you interact with `Grid` indirectly through
+ * the typed `Components/` class (e.g. `EmployeeGridComponent`) which exposes
+ * named `IGridColumnControl` properties per column. Use `Grid` directly only
+ * for low-level operations not covered by the generated accessors.
+ *
+ * @example
+ * // Via generated subject (preferred):
+ * const names = await subject.grid.employeeNameColumn.getCellValues();
+ *
+ * // Via raw Grid helper:
+ * await subject.grid.clickRow(0);
+ * const count = await subject.grid.getRowCount();
+ */
 export class Grid {
   private _gridObjects: GridObjects;
   private _page: Page;
+  private _excelStyleFilterPopup: ExcelStyleFilterPopup;
 
   constructor(gridContext: Locator) {
     this._gridObjects = new GridObjects(gridContext.page(), gridContext);
     this._page = gridContext.page();
+    this._excelStyleFilterPopup = new ExcelStyleFilterPopup(this._page);
   }
 
   protected get page() {
@@ -57,8 +77,11 @@ export class Grid {
    * @param columnName - The name of the column for which to open the filter popup.
    * @returns A promise that resolves when the filter popup is opened.
    */
-  public openExcelStyleFilterPopup = async (columnName: string) => {
-    const filterIcon = this._gridObjects.menuIconByColumnHeaderName(columnName);
+  public openExcelStyleFilterPopup = async (columnNameOrHeader: string | Locator) => {
+    const filterIcon =
+      typeof columnNameOrHeader === 'string'
+        ? this._gridObjects.menuIconByColumnHeaderName(columnNameOrHeader)
+        : columnNameOrHeader.getByTestId('grid__custom__filter__icon');
     await filterIcon.click({ force: true });
   };
 
@@ -127,34 +150,47 @@ export class Grid {
    * await grid.filterByColumnValueExcelStyle('Status', 'Active');
    * await grid.filterByColumnValueExcelStyle('Status', 'Pending', false);
    */
+
   public async filterByColumnValueExcelStyle(
     columnName: string,
     valueToSelect: string,
+    deselectAll?: boolean
+  ): Promise<void>;
+  public async filterByColumnValueExcelStyle(
+    columnHeader: Locator,
+    valueToSelect: string,
+    deselectAll?: boolean
+  ): Promise<void>;
+  public async filterByColumnValueExcelStyle(
+    columnNameOrHeader: string | Locator,
+    valueToSelect: string,
     deselectAll: boolean = true
   ): Promise<void> {
-    await this.openExcelStyleFilterPopup(columnName);
+    await this.openExcelStyleFilterPopup(columnNameOrHeader);
 
     // Get column ID from header and normalize it (snake_case -> kebab-case)
-    const header = this._gridObjects.columnHeaderByName(columnName);
+    const header =
+      typeof columnNameOrHeader === 'string'
+        ? this._gridObjects.columnHeaderByName(columnNameOrHeader)
+        : columnNameOrHeader;
     const rawColumnId = await header.getAttribute('col-id');
     if (!rawColumnId) {
-      throw new Error(`Could not find col-id for column "${columnName}"`);
+      throw new Error(
+        `Could not find col-id for column${typeof columnNameOrHeader === 'string' ? ` "${columnNameOrHeader}"` : ''}`
+      );
     }
     const columnId = rawColumnId.toLowerCase().replace(/_/g, '-');
 
-    const popup = this._gridObjects.excelStyleFilterPopup(columnId);
-    await popup.waitFor({ state: 'visible' });
+    //const popup = this._gridObjects.excelStyleFilterPopup(columnId);
+    await this._excelStyleFilterPopup.waitForOpen();
 
     if (deselectAll) {
-      await this._gridObjects.excelStyleFilterSelectAllCheckbox(columnId).uncheck();
+      await this._excelStyleFilterPopup.deselectAll(columnId);
     }
 
-    const valueRegex = new RegExp(`^${escapeRegex(valueToSelect)}$`, 'i');
-    const optionButton = this._gridObjects.excelStyleFilterPopupOptionByText(columnId, valueRegex);
-    await optionButton.locator('input[type="checkbox"]').check();
-
-    await this._gridObjects.mainHeader.click(); // Click outside to close the popup
-    await popup.waitFor({ state: 'detached' });
+    await this._excelStyleFilterPopup.clickCheckboxItem(columnId, valueToSelect);
+    await this._gridObjects.mainHeader.click();
+    await this._excelStyleFilterPopup.waitForClose();
   }
 
   /**

package/components/grid/GridObjects.ts

@@ -2,11 +2,8 @@ import type { Locator, Page } from '@playwright/test';
 import { BaseComponentObjects } from '../BaseComponentObjects.js';
 
 export class GridObjects extends BaseComponentObjects {
-  private _page: Page;
-
   constructor(page: Page, context: Locator | null = null) {
     super(page, context);
-    this._page = page;
   }
 
   public columnHeaderByText = (text: string) => this.context.locator('[role="columnheader"]', { hasText: text });
@@ -33,18 +30,6 @@ export class GridObjects extends BaseComponentObjects {
 
   public columnByRowLocator = (rowLocator: Locator) => rowLocator.locator('.ag-cell');
 
-  public excelStyleFilterPopup = (columnId: string) => this._page.getByTestId(`lookup-excel-filter__${columnId}__list`);
-
-  public excelStyleFilterSelectAllCheckbox = (columnId: string) =>
-    this._page.locator(
-      `[data-testid="lookup-excel-filter__${columnId}__list-item-select-all-checkbox"] input[type="checkbox"]`
-    );
-
-  public excelStyleFilterPopupOptionByText = (columnId: string, optionText: RegExp) =>
-    this._page
-      .locator(`[data-testid^="lookup-excel-filter__${columnId}__list-item-button"]`)
-      .filter({ hasText: optionText });
-
   public gridCell = () => this.context.locator('[role="gridcell"]');
 
   public noRowsOverlay = () => this.context.locator('.ag-overlay-no-rows-center');

package/components/maps/Maps.ts

@@ -1,6 +1,12 @@
 import type { Locator } from '@playwright/test';
 import { MapsObjects } from './MapsObjects.js';
 
+/**
+ * Wraps the Thinkwise maps component that displays geographical data on an
+ * interactive map.
+ *
+ * In generated subject classes this is exposed as a typed `maps` property.
+ */
 export class Maps {
   mapsObjects: MapsObjects;
 

package/components/menu/ListBarMenuComponent.ts

@@ -1,6 +1,16 @@
 import type { Locator, Page } from '@playwright/test';
 import { ListBarMenuComponentObjects } from './ListBarMenuComponentObjects.js';
 
+/**
+ * Wraps the Thinkwise list-bar hamburger menu used to navigate between
+ * subjects and module groups.
+ *
+ * Access via `page.components.listBarMenu` — no need to construct this yourself.
+ *
+ * @example
+ * // Navigate to the Employee subject via the menu:
+ * await page.components.listBarMenu.openListBarMenuItem('HR', 'Employee');
+ */
 export class ListBarMenuComponent {
   private _objects: ListBarMenuComponentObjects;
 

package/components/pivot-grid/PivotGrid.ts

@@ -1,6 +1,12 @@
 import type { Locator } from '@playwright/test';
 import { PivotGridObjects } from './PivotGridObjects.js';
 
+/**
+ * Wraps the Thinkwise pivot-grid component that presents data in a
+ * cross-tabulated matrix view for analysis.
+ *
+ * In generated subject classes this is exposed as a typed `pivotGrid` property.
+ */
 export class PivotGrid {
   pivotGridObjects: PivotGridObjects;
 

package/components/pivot-grid/PivotGridFieldList.ts

@@ -1,6 +1,13 @@
 import type { Locator } from '@playwright/test';
 import { PivotGridFieldListObjects } from './PivotGridFieldListObjects.js';
 
+/**
+ * Wraps the Thinkwise pivot-grid field list panel that lets users drag
+ * dimensions and measures into rows, columns, and value areas of the pivot.
+ *
+ * In generated subject classes this is exposed alongside `PivotGrid` as a
+ * typed `pivotGridFieldList` property.
+ */
 export class PivotGridFieldList {
   pivotGridFieldListObjects: PivotGridFieldListObjects;
 

package/components/pop-up/AllRowsPopUp.ts

@@ -2,6 +2,18 @@ import type { Locator, Page } from '@playwright/test';
 import { pollUntil } from '../../helpers/Poll.js';
 import { AllRowsPopupObjects } from './AllRowsPopUpObjects.js';
 
+/**
+ * Handles the "Apply to all rows or selected rows?" popup that Thinkwise
+ * shows for bulk operations (mass update, mass delete).
+ *
+ * @example
+ * // Select all rows and confirm:
+ * await subject.actionBar.clickDeleteAllRows();
+ * const popup = new AllRowsPopup(page);
+ * await popup.waitForOpen();
+ * await popup.allRowsRadioButton().click();
+ * await popup.confirmButton().click();
+ */
 export class AllRowsPopup {
   private readonly deletePopup: boolean;
   private _allRowsPopupObjects: AllRowsPopupObjects;

package/components/pop-up/PopUpComponent.ts

@@ -1,6 +1,17 @@
 import type { Locator, Page } from '@playwright/test';
 import { PopUpComponentObjects } from './PopUpComponentObjects.js';
 
+/**
+ * Wraps the Thinkwise modal/popup dialog that appears for confirmations,
+ * warnings, and input prompts (e.g. "Are you sure?" dialogs, save conflicts).
+ *
+ * Access via `page.components.popUp` — no need to construct this yourself.
+ *
+ * @example
+ * // Confirm a delete prompt:
+ * await page.components.popUp.getActionButtonByText('Yes').click();
+ * const msg = await page.components.popUp.getContentText();
+ */
 export class PopUpComponent {
   private _objects: PopUpComponentObjects;
 

package/components/prefilter-list/PrefilterList.ts

@@ -1,6 +1,15 @@
 import type { Locator } from '@playwright/test';
 import { PrefilterListObjects } from './PrefilterListObjects.js';
 
+/**
+ * Wraps the Thinkwise prefilter-list panel that shows available prefilters
+ * for a subject. Enables selecting and activating prefilters in tests.
+ *
+ * In generated subject classes this is exposed as a typed `prefilterList` property.
+ *
+ * @example
+ * await subject.prefilterList.context.getByText('Active employees').click();
+ */
 export class PrefilterList {
   prefilterListObjects: PrefilterListObjects;
 

package/components/preview/Preview.ts

@@ -1,6 +1,12 @@
 import type { Locator } from '@playwright/test';
 import { PreviewObjects } from './PreviewObjects.js';
 
+/**
+ * Wraps the Thinkwise preview component that shows a read-only rendered
+ * preview of a report or document within a subject screen.
+ *
+ * In generated subject classes this is exposed as a typed `preview` property.
+ */
 export class Preview {
   previewObjects: PreviewObjects;
 

package/components/report-bar/ReportBar.ts

@@ -1,6 +1,12 @@
 import type { Locator } from '@playwright/test';
 import { ReportBarObjects } from './ReportBarObjects.js';
 
+/**
+ * Wraps the Thinkwise report-bar component that provides controls for
+ * selecting and generating reports tied to a subject.
+ *
+ * In generated subject classes this is exposed as a typed `reportBar` property.
+ */
 export class ReportBar {
   reportBarObjects: ReportBarObjects;
 

package/components/report-tiles/ReportTiles.ts

@@ -1,6 +1,12 @@
 import type { Locator } from '@playwright/test';
 import { ReportTilesObjects } from './ReportTilesObjects.js';
 
+/**
+ * Wraps the Thinkwise report-tiles component that displays available reports
+ * as clickable tiles on a dashboard-style screen.
+ *
+ * In generated subject classes this is exposed as a typed `reportTiles` property.
+ */
 export class ReportTiles {
   reportTilesObjects: ReportTilesObjects;
 

package/components/scheduler/Scheduler.ts

@@ -1,6 +1,12 @@
 import type { Locator } from '@playwright/test';
 import { SchedulerObjects } from './SchedulerObjects.js';
 
+/**
+ * Wraps the Thinkwise scheduler component that renders time-based data as a
+ * calendar / appointment view.
+ *
+ * In generated subject classes this is exposed as a typed `scheduler` property.
+ */
 export class Scheduler {
   treeViewObjects: SchedulerObjects;
 

package/components/snackbar/SnackBar.ts

@@ -1,6 +1,18 @@
 import type { Locator, Page } from '@playwright/test';
 import { SnackBarObjects } from './SnackBarObjects.js';
 
+/**
+ * Wraps the Thinkwise snackbar / toast notification bar shown at the bottom
+ * of the screen after saves, errors, and background operations.
+ *
+ * Access via `page.components.snackBar` — no need to construct this yourself.
+ *
+ * @example
+ * await employee.actionBar.save();
+ * const msg = await page.components.snackBar.getSnackbarText();
+ * // or check visibility:
+ * await expect(page.components.snackBar.getSnackbar()).toBeVisible();
+ */
 export class SnackBarComponent {
   private _objects: SnackBarObjects;
 

package/components/splitter/Splitter.ts

@@ -1,6 +1,12 @@
 import type { Locator } from '@playwright/test';
 import { SplitterObjects } from './SplitterObjects.js';
 
+/**
+ * Wraps the Thinkwise splitter component that divides the screen into
+ * resizable panels (e.g. master/detail split, filter panel divider).
+ *
+ * In generated subject classes this is exposed as a typed `splitter` property.
+ */
 export class Splitter {
   splitterObjects: SplitterObjects;
 

package/components/tab/BaseTab.ts

@@ -1,6 +1,11 @@
 import type { Locator } from '@playwright/test';
 import { BaseTabObjects } from './BaseTabObjects.js';
 
+/**
+ * Shared base class for `Tab` and `DetailTabPage` containing the common
+ * tab-strip interaction methods (open by label, open by index, get active tab).
+ * Do not use this directly — use `Tab` or `DetailTabPage` in tests.
+ */
 export class BaseTab {
   protected _objects: BaseTabObjects;
 

package/components/tab/DetailTabPage.ts

@@ -2,6 +2,17 @@ import type { Locator } from '@playwright/test';
 import { BaseTab } from './BaseTab.js';
 import { DetailTabPageObjects } from './DetailTabPageObjects.js';
 
+/**
+ * Wraps a Thinkwise detail-tab page — a full sub-screen that loads inside a
+ * tab panel, typically showing related data for the selected master record.
+ *
+ * In generated subject classes this is exposed as a typed `detailTabPage`
+ * property. Switch to a detail tab first, then interact with its content.
+ *
+ * @example
+ * await subject.tab.openDetailTabByLabel('Addresses');
+ * await subject.detailTabPage.context.waitFor({ state: 'visible' });
+ */
 export class DetailTabPage extends BaseTab {
   protected _objects: DetailTabPageObjects;
 

package/components/tab/Tab.ts

@@ -2,6 +2,16 @@ import type { Locator } from '@playwright/test';
 import { BaseTab } from './BaseTab.js';
 import { TabObjects } from './TabObjects.js';
 
+/**
+ * Wraps a Thinkwise tab-strip component used to switch between related screens
+ * (e.g. detail tabs, sub-screens within a subject).
+ *
+ * In generated subject classes this is exposed as a typed `tab` property.
+ *
+ * @example
+ * // Navigate to the "Addresses" detail tab:
+ * await subject.tab.openDetailTabByLabel('Addresses');
+ */
 export class Tab extends BaseTab {
   protected _objects: TabObjects;
 

package/components/task/TaskBar.ts

@@ -1,14 +1,24 @@
 import type { Locator } from '@playwright/test';
 import { TaskBarObjects } from './TaskBarObjects.js';
 
+/**
+ * Wraps the Thinkwise task-bar component that shows process/workflow task
+ * buttons in a horizontal bar at the bottom or top of a subject screen.
+ *
+ * In generated subject classes this is exposed as a typed `taskBar` property.
+ *
+ * @example
+ * await subject.taskBar.getTaskById('approve').click();
+ * const label = await subject.taskBar.getTaskByLabel('Approve').textContent();
+ */
 export class TaskBar {
   private _taskBarObjects: TaskBarObjects;
 
   /**
-   * @param taskBarContext the taskbar container element (same idea as Grid's context)
+   * @param context the taskbar container element (same idea as Grid's context)
    */
-  constructor(taskBarContext: Locator) {
-    this._taskBarObjects = new TaskBarObjects(taskBarContext.page(), taskBarContext);
+  constructor(context: Locator) {
+    this._taskBarObjects = new TaskBarObjects(context.page(), context);
   }
 
   /** returns all task buttons */

package/components/task/TaskTiles.ts

@@ -1,14 +1,23 @@
 import type { Locator } from '@playwright/test';
 import { TaskTilesObjects } from './TaskTilesObjects.js';
 
+/**
+ * Wraps the Thinkwise task-tiles component that displays tasks as clickable
+ * tile buttons on a dashboard or process-flow screen.
+ *
+ * In generated subject classes this is exposed as a typed `taskTiles` property.
+ *
+ * @example
+ * await subject.taskTiles.getTileByLabel('Approve').click();
+ */
 export class TaskTiles {
   private _taskTilesObjects: TaskTilesObjects;
 
   /**
-   * @param taskTilesContext the taskTiles container element
+   * @param context the taskTiles container element
    */
-  constructor(taskTilesContext: Locator) {
-    this._taskTilesObjects = new TaskTilesObjects(taskTilesContext.page(), taskTilesContext);
+  constructor(context: Locator) {
+    this._taskTilesObjects = new TaskTilesObjects(context.page(), context);
   }
 
   /** returns all task tile buttons */

package/components/topbar/TopBar.ts

@@ -1,6 +1,16 @@
 import type { Locator, Page } from '@playwright/test';
 import { TopBarObjects } from './TopBarObjects.js';
 
+/**
+ * Wraps the Thinkwise application top bar that shows the page title,
+ * breadcrumb trail, and the user/application menu.
+ *
+ * Access via `page.components.topBar` — no need to construct this yourself.
+ *
+ * @example
+ * const title = await page.components.topBar.getTopBarTitle().textContent();
+ * const breadcrumb = await page.components.topBar.getTopBarBreadcrumb().textContent();
+ */
 export class TopBarComponent {
   private _objects: TopBarObjects;
 

package/components/tree-view/TreeView.ts

@@ -1,6 +1,15 @@
 import type { Locator } from '@playwright/test';
 import { TreeViewObjects } from './TreeViewObjects.js';
 
+/**
+ * Wraps the Thinkwise tree-view navigation component used to display
+ * hierarchical data structures (e.g. organisational trees, folder structures).
+ *
+ * In generated subject classes this is exposed as a typed `treeView` property.
+ *
+ * @example
+ * await subject.treeView.context.getByText('Europe').click();
+ */
 export class TreeView {
   treeViewObjects: TreeViewObjects;
 

package/controls/DateControl.ts

@@ -1,7 +1,30 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 /* biome-ignore-all lint/suspicious/noExplicitAny: reason42 */
 import type { Locator } from '@playwright/test';
+import { DateControlObjects } from './DateControlObjects.js';
 
+/**
+ * Typed proxy for a date-picker field (`control_type: "date_picker"`) on a
+ * Thinkwise form screen.
+ *
+ * **How to use:** You never construct this directly. Generated subject
+ * component classes expose properties of type `IDateControl` for each date
+ * field on the form:
+ *
+ * ```ts
+ * // Fill accepts any common date format — numbers are extracted and entered
+ * // sequentially so the date picker can apply its own formatting:
+ * await subject.form.hireDateField.fill('15-03-2025');
+ * await subject.form.hireDateField.fill('03/15/2025');
+ * await subject.form.hireDateField.fill('20250315');  // also works
+ *
+ * const raw = await subject.form.hireDateField.inputValue();
+ * await subject.form.hireDateField.clear();
+ * ```
+ *
+ * The returned value is a **Proxy** — it works as both a Playwright `Locator`
+ * and a typed date control.
+ */
 export type IDateControl = Locator & IDateControlCore;
 
 export type IDateControlCore = {
@@ -12,12 +35,10 @@ export type IDateControlCore = {
 };
 
 export class DateControl implements IDateControlCore {
-  private _dateFieldLocator: Locator;
-  private _inputLocator: Locator;
+  private _objects: DateControlObjects;
 
   constructor(context: Locator, id: string) {
-    this._dateFieldLocator = context.getByTestId(`form-field__${id}`);
-    this._inputLocator = this._dateFieldLocator.locator('input');
+    this._objects = new DateControlObjects(context, id);
   }
 
   /**
@@ -30,23 +51,40 @@ export class DateControl implements IDateControlCore {
   public async fill(value: string): Promise<void> {
     const numbersOnlyValue = value.replace(/\D/g, '');
 
-    await this._inputLocator.focus();
-    await this._inputLocator.pressSequentially(numbersOnlyValue);
+    await this._objects.fieldInput().click();
+    await this._objects.fieldInput().pressSequentially(numbersOnlyValue);
   }
 
+  /**
+   * Clears the date input by filling it with an empty string.
+   */
   public async clear(): Promise<void> {
-    await this._inputLocator.fill('');
+    await this._objects.fieldInput().fill('');
   }
 
+  /**
+   * Returns the current raw string value from the underlying date input element.
+   */
   public async inputValue(): Promise<string> {
-    return await this._inputLocator.inputValue();
+    return await this._objects.fieldInput().inputValue();
   }
 
+  /**
+   * Returns the Playwright `Locator` for the underlying `<input>` element of the date field.
+   */
   public inputElement(): Locator {
-    return this._inputLocator;
+    return this._objects.fieldInput();
   }
 }
 
+/**
+ * Creates an `IDateControl` proxy that merges `DateControl` interaction methods with
+ * the underlying Playwright `Locator` for the `form-field__<id>` test ID.
+ * Use the returned value as both a typed date control and a regular Playwright locator.
+ * @param context - The parent locator to scope the control within.
+ * @param id - The field identifier used to locate `[data-testid="form-field__<id>"]`.
+ * @returns A proxy combining `IDateControlCore` methods and `Locator` capabilities.
+ */
 export function createDateControl(context: Locator, id: string): IDateControl {
   const inputFieldControl = new DateControl(context, id);
   const locator = context.getByTestId(`form-field__${id}`);

package/controls/DateControlObjects.ts

@@ -0,0 +1,15 @@
+import type { Locator } from '@playwright/test';
+
+export class DateControlObjects {
+  private _context: Locator;
+  private _id: string;
+
+  constructor(context: Locator, id: string) {
+    this._context = context;
+    this._id = id;
+  }
+
+  public fieldInput = (): Locator => this._context;
+
+  public dateField = (): Locator => this._context.getByTestId(`form-field__${this._id}`);
+}