@agnos-ui/base-po 0.0.1-alpha.0

package/README.md

@@ -0,0 +1,39 @@
+# @agnos-ui/base-po
+
+[![npm](https://img.shields.io/npm/v/@agnos-ui/base-po)](https://www.npmjs.com/package/@agnos-ui/base-po)
+
+Base class to build page objects for end-to-end tests with Playwright.
+
+## Installation
+
+```sh
+npm install @agnos-ui/base-po
+```
+
+## Usage
+
+```ts
+import {BasePO} from '@agnos-ui/base-po';
+import {Locator} from '@playwright/test';
+
+export const customComponentSelectors = {
+	rootComponent: '.custom',
+	otherContent: '.content-class',
+};
+
+export class CustomComponentPO extends BasePO {
+	selectors = {...customComponentSelectors};
+
+	override getComponentSelector(): string {
+		return this.selectors.rootComponent;
+	}
+
+	get locatorOtherContent(): Locator {
+		return this.locatorRoot.locator(this.selectors.otherContent);
+	}
+}
+```
+
+## Main features
+
+Please refer to the documentation included in [the source code](lib/base.po.ts).

package/dist/lib/index.d.ts

@@ -0,0 +1,121 @@
+import type { Locator } from '@playwright/test';
+import type { Page } from '@playwright/test';
+
+/**
+ * Base class to be extended for page objects.
+ * The purpose of this architecture is to standardize the way locators are created in the page object, to be able to target precisely the dom elements you want to interact with.
+ *
+ * The constructor takes two parameters:
+ *
+ * - `container: Page | Locator` is the container locator from which other locators are built
+ * - `index: number | null = null` is the nth index component found in the container locator
+ *
+ * Page objects must usually override the `getComponentSelector()` method to return the html selector of the component
+ *
+ * @example
+ *
+ * ```html
+ * <!-- page.html -->
+ * <div class="component1">
+ *    <div class="component2">
+ *      <button>Click me</button>
+ *    </div>
+ *    <div class="component2">
+ *      <button>Click me</button>
+ *    </div>
+ * </div>
+ * ```
+ *
+ * ```typescript
+ * // component1.po.ts
+ * export Component1Page extends BasePo {
+ *    getComponentSelector(): string {
+ *      return 'div.component1';
+ *    }
+ * }
+ *
+ * // component2.po.ts
+ * export Component2Page extends BasePo {
+ *    getComponentSelector(): string {
+ *      return 'div.component2';
+ *    }
+ *
+ *    // Button locator in component2
+ *    get locatorButton() {
+ *        return this.locatorRoot.locator('button');
+ *    }
+ * }
+ *
+ * // test.spec.ts
+ * test('should click', ({page}) => {
+ *
+ *    // will manage the component1 section
+ *    const component1Po = new Component1Page(page);
+ *
+ *    // click on the button of the first component2 of component1
+ *    const firstComponent2Po = new Component2Page(component1Po.locatorRoot);
+ *    await firstComponent2Po.locatorButton.click();
+ *
+ *    // click on the button of the second component2 of component1
+ *    const secondComponent2Po = new Component2Page(component1Po.locatorRoot, 1);
+ *    await secondComponent2Po.locatorButton.click();
+ *
+ * });
+ *
+ * ```
+ *
+ */
+export declare class BasePO {
+    #private;
+    /**
+     * Playwright page object from which the page object has been created.
+     * It can be convenient for situation where you can't work (internally) with the locatorRoot
+     */
+    protected _page: Page;
+    /**
+     *
+     * @param container - Container locator (page if there is no container) where the component is located
+     * @param index - If you have multiple components **inside the container**, you must provide the index to select the component to work with. You can omit this parameter if you have a single component.
+     */
+    constructor(container: Page | Locator, index?: number | null);
+    /**
+     * The root locator of your page object.
+     * It can be used to be chain with internal locators.
+     *
+     * It is built with the provided `container` from the constructor, the `getComponentSelector` (one of them must be provided, at least) and the optional `index` parameter from the contructor.
+     *
+     * @example
+     *
+     * ```typescript
+     *
+     * // Button locator in this component
+     * get locatorButton() {
+     *    return this.locatorRoot().locator('button').nth(0);
+     * }
+     * ```
+     */
+    get locatorRoot(): Locator;
+    /**
+     * Returns the root selector for the component
+     * This method must be usually overriden to return the css selector of your component
+     *
+     * @example
+     *
+     * ```typescript
+     * getComponentSelector(): string {
+     *  return 'app-component';
+     * }
+     * ```
+     * Will target the html component:
+     * ```html
+     * <app-component>...</app-component>
+     * ```
+     */
+    getComponentSelector(): string;
+    /**
+     * Wait for the locatorRoot to be displayed in the page
+     */
+    waitLoaded(): Promise<void>;
+}
+
+export { }

package/dist/lib/index.js

@@ -0,0 +1 @@
+"use strict";var d=Object.defineProperty;var f=(o,t,e)=>t in o?d(o,t,{enumerable:!0,configurable:!0,writable:!0,value:e}):o[t]=e;var g=(o,t,e)=>(f(o,typeof t!="symbol"?t+"":t,e),e),p=(o,t,e)=>{if(!t.has(o))throw TypeError("Cannot "+e)};var s=(o,t,e)=>(p(o,t,"read from private field"),e?e.call(o):t.get(o)),c=(o,t,e)=>{if(t.has(o))throw TypeError("Cannot add the same private member more than once");t instanceof WeakSet?t.add(o):t.set(o,e)},n=(o,t,e,i)=>(p(o,t,"write to private field"),i?i.call(o,e):t.set(o,e),e);Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function h(o){return"waitFor"in o}var r,a,l;class m{constructor(t,e=null){c(this,r,void 0);c(this,a,void 0);c(this,l,void 0);g(this,"_page");n(this,r,t),n(this,a,e),this._page=h(t)?t.page():t}get locatorRoot(){let t=s(this,l);if(!t){const e=this.getComponentSelector();let i=s(this,r);if(e){i=i.locator(e);const u=s(this,a);u!==null&&(i=i.nth(u))}t=h(i)?i:i.locator("html"),n(this,l,t)}return t}getComponentSelector(){return""}async waitLoaded(){h(this.locatorRoot)&&await this.locatorRoot.waitFor()}}r=new WeakMap,a=new WeakMap,l=new WeakMap;exports.BasePO=m;

package/dist/lib/index.mjs

@@ -0,0 +1,92 @@
+var R = Object.defineProperty;
+var f = (o, t, e) => t in o ? R(o, t, { enumerable: !0, configurable: !0, writable: !0, value: e }) : o[t] = e;
+var u = (o, t, e) => (f(o, typeof t != "symbol" ? t + "" : t, e), e), g = (o, t, e) => {
+  if (!t.has(o))
+    throw TypeError("Cannot " + e);
+};
+var l = (o, t, e) => (g(o, t, "read from private field"), e ? e.call(o) : t.get(o)), s = (o, t, e) => {
+  if (t.has(o))
+    throw TypeError("Cannot add the same private member more than once");
+  t instanceof WeakSet ? t.add(o) : t.set(o, e);
+}, n = (o, t, e, i) => (g(o, t, "write to private field"), i ? i.call(o, e) : t.set(o, e), e);
+function h(o) {
+  return "waitFor" in o;
+}
+var r, a, c;
+class d {
+  /**
+   *
+   * @param container - Container locator (page if there is no container) where the component is located
+   * @param index - If you have multiple components **inside the container**, you must provide the index to select the component to work with. You can omit this parameter if you have a single component.
+   */
+  constructor(t, e = null) {
+    s(this, r, void 0);
+    s(this, a, void 0);
+    s(this, c, void 0);
+    /**
+     * Playwright page object from which the page object has been created.
+     * It can be convenient for situation where you can't work (internally) with the locatorRoot
+     */
+    u(this, "_page");
+    n(this, r, t), n(this, a, e), this._page = h(t) ? t.page() : t;
+  }
+  /**
+   * The root locator of your page object.
+   * It can be used to be chain with internal locators.
+   *
+   * It is built with the provided `container` from the constructor, the `getComponentSelector` (one of them must be provided, at least) and the optional `index` parameter from the contructor.
+   *
+   * @example
+   *
+   * ```typescript
+   *
+   * // Button locator in this component
+   * get locatorButton() {
+   *    return this.locatorRoot().locator('button').nth(0);
+   * }
+   * ```
+   */
+  get locatorRoot() {
+    let t = l(this, c);
+    if (!t) {
+      const e = this.getComponentSelector();
+      let i = l(this, r);
+      if (e) {
+        i = i.locator(e);
+        const p = l(this, a);
+        p !== null && (i = i.nth(p));
+      }
+      t = h(i) ? i : i.locator("html"), n(this, c, t);
+    }
+    return t;
+  }
+  /**
+   * Returns the root selector for the component
+   * This method must be usually overriden to return the css selector of your component
+   *
+   * @example
+   *
+   * ```typescript
+   * getComponentSelector(): string {
+   *  return 'app-component';
+   * }
+   * ```
+   * Will target the html component:
+   * ```html
+   * <app-component>...</app-component>
+   * ```
+   */
+  getComponentSelector() {
+    return "";
+  }
+  /**
+   * Wait for the locatorRoot to be displayed in the page
+   */
+  async waitLoaded() {
+    h(this.locatorRoot) && await this.locatorRoot.waitFor();
+  }
+}
+r = new WeakMap(), a = new WeakMap(), c = new WeakMap();
+export {
+  d as BasePO
+};

package/dist/lib/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.36.4"
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+	"name": "@agnos-ui/base-po",
+	"description": "Base class to build page objects for end-to-end tests with Playwright.",
+	"keywords": [
+		"playwright",
+		"page-object",
+		"e2e",
+		"testing"
+	],
+	"main": "dist/lib/index.js",
+	"module": "dist/lib/index.mjs",
+	"types": "dist/lib/index.d.ts",
+	"scripts": {
+		"build": "npm run build:rollup && npm run build:dts && npm run build:api-extractor",
+		"build:rollup": "tsc && vite build -c vite.config.ts",
+		"build:dts": "tsc -p tsconfig.d.json",
+		"build:api-extractor": "api-extractor run"
+	},
+	"peerDependencies": {
+		"@playwright/test": "*"
+	},
+	"files": [
+		"dist/lib"
+	],
+	"license": "MIT",
+	"bugs": "https://github.com/AmadeusITGroup/AgnosUI/issues",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/AmadeusITGroup/AgnosUI.git",
+		"directory": "base-po"
+	},
+	"version": "0.0.1-alpha.0"
+}