transit-core-taf 1.0.3 → 1.0.4

package/README.md

@@ -0,0 +1,286 @@
+# Shutterfly Automation
+
+This project contains automated tests for the Shutterfly website, specifically focusing on the product personalization workflow. It is built using Playwright.
+
+## Project Overview
+
+The primary purpose of this project is to automate the testing of user flows on the Shutterfly platform. The main test case covers:
+
+1.  **User Login**: Logging into the Shutterfly stage environment.
+2.  **Product Selection**: Navigating to a product category (e.g., Desk Calendars) and selecting a product.
+3.  **Personalization**: Opening the product personalization interface (the "builder").
+4.  **Builder Functionality**: Interacting with various features within the builder, such as:
+    *   Adding photos
+    *   Changing layouts
+    *   Applying backgrounds
+    *   Adding stickers
+    *   Modifying date options
+
+## Technologies Used
+
+*   **Test Framework**: [Playwright](https://playwright.dev/)
+*   **Language**: TypeScript
+*   **Dependencies**:
+    *   `aurora-core`: Core library for Shutterfly automation.
+    *   `builder-taf`: Test automation framework for the builder interface.
+    *   `dotenv`: For managing environment variables.
+
+## Getting Started
+
+### Prerequisites
+
+*   Node.js and npm installed.
+*   A `.env` file with the necessary credentials (`USERNAME`, `PASSWORD`) for the stage environment.
+
+### Installation
+
+1.  Clone the repository:
+    ```bash
+    git clone https://github.com/sflyinc-shutterfly/shutterflyautomation.git
+    ```
+2.  Navigate to the project directory:
+    ```bash
+    cd shutterflyautomation
+    ```
+3.  Install the dependencies:
+    ```bash
+    npm install
+    ```
+### Certificate errors during `npm install`
+If you see a certificate error while running `npm install` or `npm i`, follow this process:
+
+```bash
+npm config set strict-ssl false
+NODE_TLS_REJECT_UNAUTHORIZED=0 npm i
+NODE_TLS_REJECT_UNAUTHORIZED=0 npx playwright install
+
+### Running Tests
+
+To run the tests, execute the following command:
+
+```bash
+npm run tests
+```
+
+This will run the `basictest.spec.ts` test in headed mode with debugging enabled, as configured in `package.json`.
+
+### Local Run and Debug
+
+To run a specific test file, right-click on the spec file in your IDE, copy the relative path, and replace the path in the `package.json` scripts (`test:api` or `test:ui`).
+
+The scripts are:
+```json
+"test:api": "ENV=stage npx playwright test --project=api-tests tests/api-tests/projectsandrendering/projects/books.spec.ts --workers=1",
+"test:ui": "ENV=stage npx playwright test --headed tests/builder-tests/photobooks/layoutApplyToPhotoBook.spec.ts"
+```
+
+> **Note:** The `test:api` and `test:ui` scripts are intended for local runs. Any modifications made to them for debugging or specific test runs should not be committed to the repository.
+
+> **Important:** Changes to `package.json` and `package-lock.json` should not be committed unless they involve dependency updates or new scripts necessary for CI/CD.
+
+Then, execute the desired script from your terminal:
+
+### Running Tests
+
+-   **Run all tests:**
+    ```bash
+    npx playwright test
+    ```
+-   **Run tests with a specific tag (e.g., `@smoke`):**
+    ```bash
+    npx playwright test --grep @smoke
+    ```
+-   **Run tests on a specific environment (e.g., stage):**
+    ```bash
+    npm run test:stage
+    ```
+-   **Run a single test in headed/debug mode:**
+    ```bash
+    npm run test:single
+    ```
+-   **View the HTML report:**
+    ```bash
+    npx playwright show-report
+    ```
+
+> **Note on Local Testing:** When running a single test locally using `npm run test:single`, you may add debugging statements (e.g., `console.log`). These changes should not be committed to the repository unless they are intended to be part of the final implementation for CI/CD.
+
+---
+
+## Architecture
+
+This section provides an overview of the test automation architecture for both API and UI tests. The framework is designed to be modular, allowing the core functionalities to be published as an npm module and reused across different Playwright projects.
+
+### API Test Architecture
+
+The following diagram illustrates the architecture of the API tests. The core logic, including API helpers and fixtures, is encapsulated within the `src` directory, which can be published as a package.
+
+```mermaid
+graph TD
+    subgraph "aurora-core-taf Repository"
+        A[tests/api-tests/**/*.spec.ts] --> B{Playwright Test Runner};
+        B --> C[src/apihelpers];
+        C --> D[src/resources];
+        B --> E[src/fixtures.ts];
+        C --> F[External APIs];
+    end
+
+    subgraph "Published NPM Module"
+        G["@sfly/aurora-core-taf"]
+        subgraph "Contents"
+            direction LR
+            C --- G;
+            D --- G;
+            E --- G;
+        end
+    end
+
+    subgraph "Another-Playwright-Repo"
+        H[tests/**/*.spec.ts] --> I{Playwright Test Runner};
+        I --> G;
+    end
+
+    style G fill:#f9f,stroke:#333,stroke-width:2px
+```
+
+### UI (Builder) Test Architecture
+
+The UI tests follow the Page Object Model (POM) pattern. The pages, locators, and base classes are part of the reusable `src` directory.
+
+```mermaid
+graph TD
+    subgraph "aurora-core-taf Repository"
+        A[tests/builder-tests/**/*.spec.ts] --> B{Playwright Test Runner};
+        B --> C[src/fixtures.ts];
+        C --> D[src/builder/pages];
+        D --> E[src/builder/locators];
+        D --> F[src/base];
+        B --> G[Shutterfly Application];
+    end
+
+    subgraph "Published NPM Module"
+        H["@sfly/aurora-core-taf"]
+        subgraph "Contents"
+            direction LR
+            C --- H;
+            D --- H;
+            E --- H;
+            F --- H;
+        end
+    end
+
+    subgraph "Another-Playwright-Repo"
+        I[tests/**/*.spec.ts] --> J{Playwright Test Runner};
+        J --> H;
+        J --> K[Another Application];
+    end
+
+    style H fill:#f9f,stroke:#333,stroke-width:2px
+```
+
+**To run API Tests:**
+```bash
+npm run test:api
+```
+
+**To run UI Tests:**
+```bash
+npm run test:ui
+```
+
+To debug a test, add the `--debug` flag to the script in `package.json` before running it. For example:
+```json
+"test:api": "ENV=stage npx playwright test --debug --project=api-tests tests/api-tests/projectsandrendering/projects/books.spec.ts --workers=1"
+```
+
+---
+
+## Coding Standards for Automation Framework
+
+This section outlines the coding standards and conventions to be followed when working with the Playwright automation framework in this repository.
+
+### **1. Project Structure (Page Object Model)**
+
+The framework follows the **Page Object Model (POM)** design pattern.
+
+-   **`builder-taf/src/pages`**: Contains page object classes that encapsulate the logic for interacting with a specific page (e.g., `HomePage`, `BuilderPage`).
+-   **`builder-taf/src/locators`**: Contains locator classes that define the selectors for the elements on a page (e.g., `HomePageLocators`). This separates the locators from the page logic.
+-   **`builder-taf/src/base`**: Contains base classes for common actions and waits (e.g., `BasePageWaits`).
+-   **`tests/`**: Contains the actual test files (`.spec.ts`). Tests are organized into subdirectories based on the feature or application area (e.g., `tests/cards`, `tests/calendar`).
+
+### **2. Naming Conventions**
+
+-   **Files**: All filenames should be **lowercase**.
+    -   Page classes: `[pagename]page.ts` (e.g., `homepage.ts`)
+    -   Locator classes: `[pagename]pagelocators.ts` (e.g., `homepagelocators.ts`)
+    -   Test files: `[testname].spec.ts` (e.g., `cardsreturnrecipientaddress.spec.ts`)
+-   **Classes**: Use **PascalCase** for class names (e.g., `HomePage`, `HomePageLocators`).
+-   **Methods & Functions**: Use **camelCase** for methods and functions (e.g., `closeHomepagePopup`, `clickOnCalendar`).
+-   **Variables & Properties**: Use **camelCase** for variables and properties (e.g., `homePageLocators`, `discountPopupCloseButton`).
+
+### **3. Coding Style & Best Practices**
+
+-   **TypeScript**: The framework is written in TypeScript. Use appropriate types for variables, parameters, and return values.
+-   **Asynchronous Operations**: Use `async/await` for all asynchronous operations (e.g., Playwright actions).
+-   **Comments**: Use JSDoc-style comments (`/** ... */`) to document all page action functions. This helps with code clarity and auto-generation of documentation. For example:
+    ```typescript
+    /**
+     * Navigates to a specific URL and waits for the page to load.
+     * @param url The URL to navigate to.
+     */
+    ```
+    
+    ```typescript
+    /** Comments Section should be followed as this for single line comments */
+    ```
+-   **Fixtures**: Use Playwright fixtures (`builder-taf/src/fixtures.ts`) to provide instances of page objects to the tests. This promotes code reuse and simplifies test setup.
+-   **Base Classes**: Utilize `BasePageActions`, `BasePageValidations`, and `BasePageWaits` for common actions, validations, and waits. These base classes help avoid repetitive code and ensure consistency across the framework.
+-   **Environment Variables**: Store sensitive information like usernames and passwords in environment variables (`process.env`) and not directly in the code.
+-   **Waits**:
+    -   Prefer using explicit waits provided by `BasePageWaits` (e.g., `waits.waitForPageLoad()`).
+    -   Static waits (`waits.waitForSeconds()`) should be used sparingly and only when necessary, with a comment explaining the reason.
+
+### **4. Test Structure**
+
+-   **Grouping**: Use `test.describe()` to group related tests.
+-   **Test Names**: Write clear and descriptive test names that explain the purpose of the test. Include the relevant test case ID if applicable (e.g., `C5564361`).
+-   **Assertions**: Use `expect` from Playwright for assertions to validate the application's state.
+-   **Tags**: Use tags to categorize tests (e.g., `@smoke`, `@regression`). This allows for running specific subsets of tests.
+
+### **5. TestRail Integration**
+
+-   **Case ID**: All test cases should have the corresponding TestRail case ID mentioned in a comment block above the test case. This helps in tracking the automation status of the test cases.
+    For Example:
+    ```typescript
+    /** C5586855 - Verify Remove using Drag and Drop in Photo Contextual Menu */
+    ```
+-   **Status Update**: Once a pull request (PR) with the automated test case is merged, the status of the corresponding test case in TestRail needs to be updated to "Automated".
+
+---
+
+## Pull Request Review Checklist
+
+This checklist should be used when reviewing pull requests to ensure that the code adheres to the coding standards and best practices of this framework.
+
+### **1. Code Quality & Style**
+- [ ] **TypeScript**: Is the code written in TypeScript with appropriate types for variables, parameters, and return values?
+- [ ] **Async/Await**: Are all asynchronous operations handled with `async/await`?
+- [ ] **Comments**: Are all page action functions documented with JSDoc-style comments?
+- [ ] **Readability**: Is the code easy to read and understand?
+
+### **2. Framework & Best Practices**
+- [ ] **Fixtures**: Are Playwright fixtures used for test setup?
+- [ ] **Base Classes**: Are `BasePageActions`, `BasePageValidations`, and `BasePageWaits` utilized for common actions?
+- [ ] **Environment Variables**: Is sensitive information stored in environment variables and not hardcoded?
+- [ ] **Waits**: Are explicit waits used instead of static waits wherever possible? If static waits are used, is there a valid reason provided in the comments?
+
+### **3. Test Structure & Naming**
+- [ ] **Grouping**: Are related tests grouped using `test.describe()`?
+- [ ] **Test Names**: Are the test names clear, descriptive, and include the TestRail case ID?
+- [ ] **Assertions**: Are assertions made using `expect` from Playwright?
+- [ ] **Tags**: Are appropriate tags (e.g., `@smoke`, `@regression`) used for the tests?
+- [ ] **Naming Conventions**: Do all files, classes, methods, and variables follow the established naming conventions?
+
+### **4. TestRail Integration**
+- [ ] **Case ID**: Is the TestRail case ID present in a comment block above the test case?
+- [ ] **TestRail Status**: Once a pull request (PR) with the automated test case is merged, the status of the corresponding test case in TestRail needs to be updated to "Automated".

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "transit-core-taf",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Transit Core Automation Framework",
   "main": "dist/transit-core-taf/index.js",
   "types": "dist/transit-core-taf/index.d.ts",
@@ -8,7 +8,6 @@
     "dist/transit-core-taf"
   ],
   "devDependencies": {
-    "@cucumber/cucumber": "^11.3.0",
     "@faker-js/faker": "^9.9.0",
     "@playwright/test": "^1.54.1",
     "@types/node": "^24.3.1",
@@ -16,7 +15,6 @@
     "@types/pngjs": "^6.0.5",
     "dotenv": "^16.6.1",
     "npm-run-all": "^4.1.5",
-    "ts-node": "^10.9.2",
     "typescript": "^5.0.0",
     "xlsx": "^0.18.5"
   },
@@ -24,9 +22,8 @@
     "playwright": "^1.54.1"
   },
   "scripts": {
-    "build": "tsc",
-    "test:cucumber": "cucumber-js"
+    "build": "tsc"
   },
-  "author": "Transit Core",
+  "author": "Aurora Core",
   "license": "ISC"
-}
+}

package/dist/transit-core-taf/base/basepageactions.d.ts

@@ -1,178 +0,0 @@
-import { Locator, Page } from '@playwright/test';
-import { Logger } from './logger';
-export declare class BasePageActions {
-    private page;
-    private waits;
-    private logger;
-    constructor(page: Page, logger: Logger);
-    /**
-     * Waits for an element to be visible and clicks on it.
-     * Logs the action and provides an error message if the element isn't visible in time.
-     * @param element The locator of the element to click.
-     * @param timeout Optional timeout in ms to wait for visibility (default: 30s).
-     */
-    clickElement(element: Locator, timeout?: number): Promise<void>;
-    /**
-     * Clicks an element using its locator.
-     * @param {Locator} element - The Playwright locator of the element to click.
-     * @param {Object} [options={}] - Click options.
-     * @param {number} [options.timeout=120000] - Maximum time to wait for the element.
-     * @param {boolean} [options.force=false] - Whether to force the click (useful if the element is not interactable).
-     */
-    clickByLocator(element: Locator, options?: {
-        timeout?: number;
-        force?: boolean;
-    }): Promise<void>;
-    /**
-     * Locates a button with the specified text on the page.
-     *
-     * Note: This function currently only creates the locator but does not perform a click.
-     *
-     * @param buttonText - The visible text of the button to locate.
-    */
-    clickButtonByText(buttonText: string, timeout?: number): Promise<void>;
-    /**
-     * Locates a button with the specified text on the page.
-     *
-     * Note: This function currently only creates the locator but does not perform a click.
-     *
-     * @param buttonText - The visible text of the button to locate.
-    */
-    clickById(id: string, clickIfVisible?: boolean, timeout?: number): Promise<void>;
-    /**
-     * Fills an input element with a given value.
-     * @param element The locator of the input element.
-     * @param value The value to fill the input with.
-     */
-    fillInput(element: Locator, value: string): Promise<void>;
-    /**
-     * Clears the value of an input element.
-     * @param element The locator of the input element.
-     */
-    clearInput(element: Locator): Promise<void>;
-    /**
-     * Types a text into an element slowly, with a specified delay between keystrokes.
-     * @param element The locator of the element to type into.
-     * @param text The text to type.
-     * @param delay The delay between keystrokes in milliseconds (default is 100).
-     */
-    typeSlowly(element: Locator, text: string, delay?: number): Promise<void>;
-    /**
-     * Hovers over a given element.
-     * @param element The locator of the element to hover over.
-     */
-    hoverOverElement(element: Locator, timeout?: number): Promise<void>;
-    /**
-     * Presses a key on a given element.
-     * @param element The locator of the element.
-     * @param key The key to press (e.g., 'Enter', 'ArrowDown').
-     */
-    pressKey(element: Locator, key: string): Promise<void>;
-    /**
-     * Checks a checkbox if it is not already checked.
-     * @param element The locator of the checkbox element.
-     */
-    checkCheckbox(element: Locator): Promise<void>;
-    /**
-     * Unchecks a checkbox if it is already checked.
-     * @param element The locator of the checkbox element.
-     */
-    uncheckCheckbox(element: Locator): Promise<void>;
-    /**
-     * Selects an option from a dropdown element by its value.
-     * @param element The locator of the select element.
-     * @param value The value of the option to select.
-     */
-    selectOption(element: Locator, value: string): Promise<void>;
-    /**
-   * Retrieves the text content of an element by its ID.
-   *
-   * @param id - The ID of the HTML element to retrieve text from.
-   * @returns The text content of the specified element.
-   */
-    getElementTextById(id: string): Promise<string | undefined>;
-    /**
-     * Retrieves the text content of an element by its Locator.
-     * @param locator - The Locator of the HTML element to retrieve text from.
-     * @returns The text content of the specified element.
-     */
-    getElementTextByLocator(locator: Locator): Promise<string>;
-    /**Gets the specified attribute value of an element using its ID.
-     * @param id The ID of the element.
-     * @param attribute The attribute name (e.g., 'value', 'min', 'max')
-     */
-    getElementAttributeValueById(id: string, attribute: string): Promise<string | undefined>;
-    /**
-     * Gets the specified attribute value of an element using a Locator.
-     * @param locator The Playwright Locator for the element.
-     * @param attribute The attribute name (e.g., 'value', 'min', 'max').
-     * @returns The attribute value as a string (or undefined if not present).
-     */
-    getAttributeValueByLocator(locator: Locator, attribute: string): Promise<string | undefined>;
-    /** Fills an input element identified by its ID with a given value.
-    * - Waits for the input to be visible before filling.
-    *
-    * @param elementId - The ID of the input element.
-    * @param value - The value to fill the input with.
-    */
-    fillInputById(elementId: string, value: string): Promise<void>;
-    /**
-     * Clicks a tab by its text and validates that it's selected using accessibility and style attributes.
-     * @param tabText - Visible text of the tab (e.g., "Crop").
-     * @param timeout - Optional timeout for the click action.
-     */
-    validateCropTabSelected(tabLocator: Locator, timeout?: number): Promise<void>;
-    /**
-     * Counts the number of objects in the array where the given key is null or undefined.
-     * @param items - The array of items to check.
-     * @param key - The key to inspect on each item.
-     * @returns The number of items where the key is null or undefined.
-     */
-    getNullCountByType(items: any[], key: string): Promise<number>;
-    /**
-     * Sets the viewport size and waits for DOM content to be loaded.
-     * @param viewport - An object with width and height properties.
-     */
-    setViewport(viewport: {
-        width: number;
-        height: number;
-    }): Promise<void>;
-    /**
-     * Reloads the current page and waits until the DOM is fully loaded.
-     * @param options - Optional reload options (timeout, waitUntil).
-     */
-    reloadPage(options?: {
-        timeout?: number;
-        waitUntil?: 'load' | 'domcontentloaded' | 'networkidle';
-    }): Promise<void>;
-    /**
-     * Universal drag-and-drop method for builder elements (photos, layouts, backgrounds, stickers).
-     * Accepts either a string selector or a Playwright Locator for both source and target.
-     * @param source - Locator or string selector for the element to drag.
-     * @param target - Locator or string selector for the drop target.
-     * @param attribute - (Optional) Attribute to return from the dragged element (default: "data-id").
-     * @returns The attribute value if available, otherwise null.
-     */
-    dragElementToTarget(source: Locator | string, target: Locator | string, attribute?: string): Promise<string | null>;
-    /**
-     * Gives the textcontent of all elements .
-     * @param locator The ID of the element.
-     * Returns array of values of all the elements textcontent
-     */
-    getAllTextContents(locator: Locator): Promise<string[]>;
-    /**
-     * @param locator The ID of the element.
-     * Click on element if its not expanded
-     */
-    clickIfNotExpanded(locator: Locator): Promise<void>;
-    /**
-     * Performs a mouse click at the given screen coordinates.
-     * @param x - The x-coordinate for the click.
-     * @param y - The y-coordinate for the click.
-     * @param options - Optional click options like button or clickCount.
-     */
-    mouseClickAt(x: number, y: number, options?: {
-        button?: 'left' | 'right' | 'middle';
-        clickCount?: number;
-    }): Promise<void>;
-}