pomwright 0.0.6 → 0.0.8

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # pomwright
 
+## 0.0.8
+
+### Patch Changes
+
+- 0d4924e: adds additional inforamtion to package.json and shields in readme
+
+## 0.0.7
+
+### Patch Changes
+
+- 5b7ed8a: Update README
+
 ## 0.0.6
 
 ### Patch Changes

package/README.md

@@ -1,2 +1,249 @@
 # POMWright
-POMWright is a complementary test framework for Playwright written in TypeScript.
+
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/DyHex/POMWright/main.yaml?label=CI%20on%20main) ![NPM Version](https://img.shields.io/npm/v/pomwright?link=https%3A%2F%2Fwww.npmjs.com%2Fpackage%2Fpomwright) ![NPM Downloads](https://img.shields.io/npm/dt/pomwright) ![GitHub License](https://img.shields.io/github/license/DyHex/POMWright) ![NPM dev or peer Dependency Version](https://img.shields.io/npm/dependency-version/pomwright/peer/%40playwright%2Ftest) 
+
+
+POMWright is a TypeScript-based framework that implements the Page Object Model Design Pattern, designed specifically to augment Playwright's testing capabilities.
+
+POMWright provides a way of abstracting the implementation details of a web page and encapsulating them into a reusable page object. This approach makes the tests easier to read, write and maintain, and helps reduce duplicated code by breaking down the code into smaller, reusable components, making the code more maintainable and organized.
+
+## Features
+
+**Easy Creation of Page Object Classes:**
+Extend a class with POMwright to create a Page Object Class (POC).
+
+**Support for Multiple Domains/BaseURLs:**
+Extend an abstract class with POMWright with a given BaseUrl, then create POCs for that BaseUrl by extending the abstract class.
+
+**Custom Playwright Fixture Integration:** Create custom Playwright Fixtures from your POMWright POCs by extending test as POMWrightTestFixture.
+
+**LocatorSchema Interface:** Offers a way to define and structure comprehensive locators per POC and share common locators between them.
+
+**Advanced Locator Management:** Enables retrieval and automatic chaining of locators using LocatorSchemaPath.
+
+**LocatorSchema Update/Updatess:** Allows updating single locators aswell as each locator a chained locator consist of, dynamically throughout a test.
+
+**Deep Copy of LocatorSchemas:** Ensures original LocatorSchemas are reusable in tests.
+
+**Custom HTML Logger:** Provides detailed logs for nested locators, aiding in debugging and integration with Playwright's HTML report.
+
+**SessionStorage Handling:** Includes methods for managing sessionStorage, complementing Playwright's capabilities.
+
+## Installation
+
+```bash
+npm install pomwright --save-dev
+```
+
+## Usage
+
+**Simple example of creating a Page Object Class:**
+
+```TS
+import { Page, TestInfo } from "@playwright/test";
+import { POMWright, POMWrightLogger } from "pomwright";
+
+type LocatorSchemaPath = 
+  | "content"
+  | "content.heading"
+  | "content.region.details"
+  | "content.region.details.button.edit";
+
+export default class Profile extends POMWright<LocatorSchemaPath> {
+  constructor(page: Page, testInfo: TestInfo, pwrl: POMWrightLogger) {
+    super(page, testInfo, "https://someDomain.com", "/profile", Profile.name, pwrl);
+  }
+
+  protected initLocatorSchemas() {
+    this.locators.addSchema("content", {
+      locator: ".main-content",
+      locatorMethod: GetByMethod.locator
+    });
+
+    this.locators.addSchema("content.heading", {
+      role: "heading",
+      roleOptions: {
+        name: "Your Profile"
+      }
+      locatorMethod: GetByMethod.role
+    });
+
+    this.locators.addSchema("content.region.details", {
+      role: "region",
+      roleOptions: {
+        name: "Profile Details"
+      }
+      locatorMethod: GetByMethod.role
+    });
+
+    this.locators.addSchema("content.region.details.button.edit", {
+      role: "button",
+      roleOptions: {
+        name: "Edit"
+      }
+      locatorMethod: GetByMethod.role
+    });
+  }
+
+  // add your helper methods here...
+}
+```
+
+**Creating a Custom Playwright Fixture for the Profile POC:**
+
+```TS
+import { POMWrightTestFixture as base } from "pomwright";
+import Profile from "...";
+
+type fixtures = {
+  profile: Profile;
+}
+
+export const test = base.extend<fixtures>({
+  profile: async ({ page, log }, use, testInfo) => {
+    const profile = new Profile(page, testInfo, log);
+    await use(profile);
+  }
+});
+```
+
+**Using the fixture in a Playwright tests:**
+
+```TS
+import { test } from ".../fixtures";
+
+test("click edit button with a single locator", async ({ profile }) => {
+  // perform setup/navigation...
+
+  await profile.page.waitForURL(profile.fullUrl);
+
+  /** 
+   * returns the locator resolving to the full locatorSchemaPath
+   */
+  const editBtn = await profile.getLocator("content.region.details.button.edit");
+
+  await editBtn.click();
+
+});
+```
+
+```TS
+import { test } from ".../fixtures";
+
+test("click edit button with a nested locator", async ({ profile }) => {
+  // perform setup/navigation...
+
+  await profile.page.waitForURL(profile.fullUrl);
+
+  /** 
+   * returns a nested/chained locator consisting of the 3 locators: 
+   * content, 
+   * content.region.details
+   * content.region.details.button.edit
+   */
+  const editBtn = await profile.getNestedLocator("content.region.details.button.edit");
+
+  await editBtn.click();
+
+});
+```
+
+```TS
+import { test } from ".../fixtures";
+
+test("specify index for nested locator(s)", async ({ profile }) => {
+  // perform setup/navigation...
+
+  await profile.page.waitForURL(profile.fullUrl);
+
+  /** 
+   * returns a nested/chained locator consisting of the 3 locators: 
+   * content 
+   * content.region.details with .first()
+   * content.region.details.button.edit with .nth(1)
+   */
+  const editBtn = await profile.getNestedLocator("content.region.details.button.edit", {
+    3: 0, 4: 1
+  });
+
+  await editBtn.click();
+
+});
+```
+
+```TS
+import { test } from ".../fixtures";
+
+test("update a locator before use", async ({ profile }) => {
+  // perform setup/navigation...
+
+  await profile.page.waitForURL(profile.fullUrl);
+
+  /** 
+   * returns a nested/chained locator consisting of the 3 locators: 
+   * content, 
+   * content.region.details
+   * content.region.details.button.edit (updated)
+   */
+  const editBtn = await profile.getLocatorSchema("content.region.details.button.edit")
+    .update({ roleOptions: { name: "Edit details" }})
+    .getNestedLocator();
+
+  await editBtn.click();
+
+});
+```
+
+```TS
+import { test } from ".../fixtures";
+
+test("update a nested locator before use", async ({ profile }) => {
+  // perform setup/navigation...
+
+  await profile.page.waitForURL(profile.fullUrl);
+
+  /** 
+   * returns a nested/chained locator consisting of the 3 locators: 
+   * content, 
+   * content.region.details (updated)
+   * content.region.details.button.edit
+   */
+  const editBtn = await profile.getLocatorSchema("content.region.details.button.edit")
+    .updates({ 
+      2: { // content.region.details
+        locator: ".profile-details",
+        locatorMethod: GetByMethod.locator
+        } 
+      })
+    .getNestedLocator();
+
+  await editBtn.click();
+
+});
+```
+
+```TS
+import { test } from ".../fixtures";
+
+test("make multiple versions of a locator", async ({ profile }) => {
+  // perform setup/navigation...
+
+  await profile.page.waitForURL(profile.fullUrl);
+
+  const editBtnSchema = profile.getLocatorSchema("content.region.details.button.edit");
+
+  const editBtn = await editBtnSchema.getLocator();
+  await editBtn.click();
+
+  editBtnSchema.update({ roleOptions: { name: "Edit details" }});
+
+  const editBtnUpdated = await editBtnSchema.getNestedLocator();
+  await editBtnUpdated.click();
+
+  /**
+   * Calling profile.getLocatorSchema("content.region.details.button.edit") again 
+   * will return a new deepCopy of the original LocatorSchema
+   */
+
+});
+```

package/dist/index.js

@@ -1085,7 +1085,7 @@ var BasePage2 = class {
 // src/fixture/base.fixtures.ts
 var import_test5 = require("@playwright/test");
 var test3 = import_test5.test.extend({
-  // biome-ignore lint/correctness/noEmptyPattern: <explanation>
+  // biome-ignore lint/correctness/noEmptyPattern: <Playwright does not support the use of _, thus we must provide an empty object {}>
   log: async ({}, use, testInfo) => {
     const contextName = "TestCase";
     const sharedLogEntry = [];

package/dist/index.mjs

@@ -1056,7 +1056,7 @@ var BasePage2 = class {
 // src/fixture/base.fixtures.ts
 import { test as base } from "@playwright/test";
 var test3 = base.extend({
-  // biome-ignore lint/correctness/noEmptyPattern: <explanation>
+  // biome-ignore lint/correctness/noEmptyPattern: <Playwright does not support the use of _, thus we must provide an empty object {}>
   log: async ({}, use, testInfo) => {
     const contextName = "TestCase";
     const sharedLogEntry = [];

package/package.json

@@ -1,7 +1,19 @@
 {
   "name": "pomwright",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "POMWright is a complementary test framework for Playwright written in TypeScript.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DyHex/POMWright"
+  },
+  "homepage": "https://github.com/DyHex/POMWright#readme",
+  "bugs": {
+    "url": "https://github.com/DyHex/POMWright/issues"
+  },
+  "author": {
+    "name": "Magnus Blütecher Dysthe"
+  },
+  "license": "Apache 2.0",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -11,8 +23,6 @@
     "Page Object Model",
     "Test Framework"
   ],
-  "author": "Magnus Blütecher Dysthe",
-  "license": "Apache 2.0",
   "devDependencies": {
     "@biomejs/biome": "^1.5.1",
     "@changesets/cli": "^2.27.1",