added locator.as method to define top level components (like pages) (#142)

* added `locator.as` method to define top level components (like pages)

Author: AlexGalichenko

CHANGELOG.md

@@ -14,9 +14,22 @@ Check [Keep a Changelog](http://keepachangelog.com/) for recommendations on how
 
 :microscope: - experimental
 
+## [2.2.0]
+- :rocket: added `locator.as` method to define top level components (like pages)
+```typescript
+export class App {
+  LoginPage = locator.as(LoginPage);
+}
+
+class LoginPage {
+  username = locator('#username');
+  password = locator('#password');
+}
+```
+
 ## [2.1.0]
 - :rocket: added grouping by steps in traces
-- :beetle: added `FrameLocator` as possible return type for `locator.native`
+- :rocket: added `FrameLocator` as possible return type for `locator.native`
 
 ## [2.0.0]
 - :pencil: added memory processor to playwrightLocator parameter type

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@qavajs/steps-playwright",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "steps to interact with playwright",
   "main": "./index.js",
   "scripts": {
@@ -41,7 +41,7 @@
     "ts-node": "^10.9.2",
     "typescript": "^5.7.2",
     "vitest": "^2.1.8",
-    "@qavajs/validation": "^0.10.0"
+    "@qavajs/validation": "^1.0.0"
   },
   "dependencies": {
     "@playwright/test": "^1.49.1"

package.json

@@ -1,11 +1,13 @@
 import {type Browser, type BrowserContext, type Page, Locator, FrameLocator} from '@playwright/test';
 
+type SelectorDefinition = string | ((argument: string) => string) | ((argument: any) => any) | null;
+
 export class Selector {
-    selector: string | ((argument: string) => string) | ((argument: any) => any);
+    selector: SelectorDefinition;
     component!: Function;
     type: string = 'simple';
 
-    constructor(selector: string | ((argument: string) => string) | ((argument: any) => any), type?: string) {
+    constructor(selector: SelectorDefinition, type?: string) {
         this.selector = selector;
         if (type) {
             this.type = type;
@@ -48,6 +50,12 @@ export interface LocatorDefinition {
      * @param {(argument: string) => string} selector - selector function
      */
     native: (selector: (params: NativeSelectorParams) => Locator | FrameLocator) => Selector;
+
+    /**
+     * Define component
+     * @param { new () => void } component
+     */
+    as: (component: new () => void) => Selector;
 }
 
 export const locator: LocatorDefinition = function locator(selector: any): Selector {
@@ -62,6 +70,12 @@ locator.native = function(selector: (params: NativeSelectorParams) => Locator |
     return new Selector(selector, 'native');
 }
 
+locator.as = function (component: new () => void) {
+    const selector = new Selector(null);
+    selector.component = component;
+    return selector;
+}
+
 export class ChainItem {
     alias: string;
     argument?: string;
@@ -80,7 +94,7 @@ export function query(root: any, path: string) {
     const elements = path.split(/\s*>\s*/);
     const tokens = [];
     let currentComponent = new root();
-    let currentAlias = 'root';
+    let currentAlias = 'page object root';
     for (const element of elements) {
         const groups = element.match(/^(?<alias>.+?)(?:\((?<argument>.+)\))?$/)?.groups as { alias: string, argument: string };
         const alias = groups.alias.replace(/\s/g, '');
@@ -106,7 +120,7 @@ export function element(this: any, path: string): Locator {
     let current = page as unknown as Locator;
     for (const item of chain) {
         switch (item.type) {
-            case 'simple': current = current.locator(item.selector); break;
+            case 'simple': current = item.selector ? current.locator(item.selector) : current; break;
             case 'template': current = current.locator(item.selector(item.argument)); break;
             case 'native': current = item.selector({
                 driver: this.playwright.driver,

src/pageObject.ts

@@ -21,3 +21,6 @@ Feature: page object
   Scenario: template with memory
     When I save '#textValue' to memory as 'selector'
     Then I expect text of 'Simple Text Element Template ({$selector})' to be equal 'text value'
+
+  Scenario: top level component
+    Then I expect text of 'Top Level Component > Text Element' to be equal 'text value'

test-e2e/features/pageObject.feature

@@ -77,6 +77,8 @@ export default class App {
     //JS Selector
     SimpleTextElementByJS = locator('js=document.querySelectorAll("#textValue")');
     SimpleTextListItemsByJS = locator('js=document.querySelectorAll("#textValueList li")');
+
+    TopLevelComponent = locator.as(BodyComponent);
 }
 
 class BodyComponent {