playwright-cucumber-ts-steps 0.1.7 → 1.0.1

package/lib/assertions/semanticSteps.js

@@ -1,67 +1,252 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.Then_I_see_heading = Then_I_see_heading;
+exports.Then_I_do_not_see_heading = Then_I_do_not_see_heading;
+exports.Then_I_see_label = Then_I_see_label;
+exports.Then_I_do_not_see_label = Then_I_do_not_see_label;
+exports.Then_I_see_link = Then_I_see_link;
+exports.Then_I_do_not_see_link = Then_I_do_not_see_link;
+exports.Then_I_count_current_locator_elements = Then_I_count_current_locator_elements;
+exports.Then_I_see_document_title = Then_I_see_document_title;
+exports.Then_I_see_document_title_contains = Then_I_see_document_title_contains;
 const cucumber_1 = require("@cucumber/cucumber");
 const test_1 = require("@playwright/test");
-const optionsUtils_1 = require("../helpers/utils/optionsUtils");
-//
-// 🧠 HEADINGS
-//
-(0, cucumber_1.Then)("I see heading {string}", async function (text) {
-    const heading = await this.page.locator("h1, h2, h3, h4, h5, h6", { hasText: text }).first();
-    if (!(await heading.isVisible())) {
-        throw new Error(`Heading "${text}" not found or not visible`);
-    }
-});
-(0, cucumber_1.Then)("I do not see heading {string}", async function (text) {
-    const heading = this.page.locator("h1, h2, h3, h4, h5, h6", {
-        hasText: text,
-    });
-    if ((await heading.count()) > 0) {
-        const visible = await heading.first().isVisible();
-        if (visible)
-            throw new Error(`Heading "${text}" is visible but should not be`);
-    }
-});
-//
-// 🏷️ LABELS
-//
-(0, cucumber_1.Then)("I see label {string}", async function (text) {
-    const label = this.page.getByLabel(text);
-    if (!(await label.isVisible())) {
-        throw new Error(`Label "${text}" not visible`);
-    }
-});
-(0, cucumber_1.Then)("I do not see label {string}", async function (text) {
-    const label = this.page.getByLabel(text);
-    if ((await label.count()) > 0 && (await label.first().isVisible())) {
-        throw new Error(`Label "${text}" is visible but should not be`);
-    }
-});
-//
-// 🔗 LINKS
-//
-(0, cucumber_1.Then)("I see link {string}", async function (text) {
-    const link = this.page.getByRole("link", { name: text });
-    if (!(await link.isVisible())) {
-        throw new Error(`Link "${text}" not visible`);
-    }
-});
-(0, cucumber_1.Then)("I do not see link {string}", async function (text) {
-    const link = this.page.getByRole("link", { name: text });
-    if ((await link.count()) > 0 && (await link.first().isVisible())) {
-        throw new Error(`Link "${text}" is visible but should not be`);
-    }
-});
-(0, cucumber_1.Then)("I count {int} element", async function (count) {
-    const locator = this.currentLocator ?? this.page.locator("*");
-    await (0, test_1.expect)(locator).toHaveCount(count);
-});
-//document title assertions
-(0, cucumber_1.Then)("I see document title {string}", async function (expected, table) {
+const optionsUtils_1 = require("../helpers/utils/optionsUtils"); // Assuming this path is correct
+// ===================================================================================
+// ASSERTIONS: HEADINGS (H1-H6)
+// ===================================================================================
+/**
+ * Asserts that a heading element (h1-h6) containing the given text is visible on the page.
+ *
+ * ```gherkin
+ * Then I see heading {string}
+ * ```
+ *
+ * @param text - The text content expected within the heading.
+ *
+ * @example
+ * Then I see heading "Welcome to your account"
+ *
+ * @remarks
+ * This step searches for any HTML heading tag (`<h1>` through `<h6>`) that contains the specified text.
+ * It uses Playwright's `expect().toBeVisible()` to confirm both existence and visibility, which
+ * includes automatic waiting.
+ * @category Heading Assertion Steps
+ */
+async function Then_I_see_heading(text) {
+    // Use `hasText` for partial or full text match
+    const headingLocator = this.page.locator("h1, h2, h3, h4, h5, h6", { hasText: text }).first();
+    await (0, test_1.expect)(headingLocator).toBeVisible({ timeout: 5000 });
+    this.log?.(`✅ Verified heading "${text}" is visible.`);
+}
+(0, cucumber_1.Then)("I see heading {string}", Then_I_see_heading);
+/**
+ * Asserts that a heading element (h1-h6) containing the given text is NOT visible on the page.
+ *
+ * ```gherkin
+ * Then I do not see heading {string}
+ * ```
+ *
+ * @param text - The text content expected NOT to be visible within a heading.
+ *
+ * @example
+ * Then I do not see heading "Hidden Section"
+ *
+ * @remarks
+ * This step searches for any HTML heading tag (`<h1>` through `<h6>`) that contains the specified text.
+ * It uses Playwright's `expect().not.toBeVisible()` to confirm both absence and non-visibility,
+ * which includes automatic waiting.
+ * @category Heading Assertion Steps
+ */
+async function Then_I_do_not_see_heading(text) {
+    const headingLocator = this.page.locator("h1, h2, h3, h4, h5, h6", { hasText: text }).first();
+    await (0, test_1.expect)(headingLocator).not.toBeVisible({ timeout: 5000 });
+    this.log?.(`✅ Verified heading "${text}" is NOT visible.`);
+}
+(0, cucumber_1.Then)("I do not see heading {string}", Then_I_do_not_see_heading);
+// ===================================================================================
+// ASSERTIONS: LABELS
+// ===================================================================================
+/**
+ * Asserts that a `<label>` element with the given text is visible on the page.
+ *
+ * ```gherkin
+ * Then I see label {string}
+ * ```
+ *
+ * @param text - The text content of the label expected to be visible.
+ *
+ * @example
+ * Then I see label "Username"
+ * Then I see label "I agree to the terms and conditions"
+ *
+ * @remarks
+ * This step uses Playwright's `page.getByLabel()` which is designed to find labels
+ * and implicitly connected form controls. It then uses `expect().toBeVisible()`
+ * to confirm visibility.
+ * @category Label Assertion Steps
+ */
+async function Then_I_see_label(text) {
+    const labelLocator = this.page.getByLabel(text);
+    await (0, test_1.expect)(labelLocator).toBeVisible({ timeout: 5000 });
+    this.log?.(`✅ Verified label "${text}" is visible.`);
+}
+(0, cucumber_1.Then)("I see label {string}", Then_I_see_label);
+/**
+ * Asserts that a `<label>` element with the given text is NOT visible on the page.
+ *
+ * ```gherkin
+ * Then I do not see label {string}
+ * ```
+ *
+ * @param text - The text content of the label expected NOT to be visible.
+ *
+ * @example
+ * Then I do not see label "Old Feature Toggle"
+ *
+ * @remarks
+ * This step uses Playwright's `page.getByLabel()` and then `expect().not.toBeVisible()`
+ * to confirm its non-visibility.
+ * @category Label Assertion Steps
+ */
+async function Then_I_do_not_see_label(text) {
+    const labelLocator = this.page.getByLabel(text);
+    await (0, test_1.expect)(labelLocator).not.toBeVisible({ timeout: 5000 });
+    this.log?.(`✅ Verified label "${text}" is NOT visible.`);
+}
+(0, cucumber_1.Then)("I do not see label {string}", Then_I_do_not_see_label);
+// ===================================================================================
+// ASSERTIONS: LINKS
+// ===================================================================================
+/**
+ * Asserts that a link (`<a>` tag) with the given accessible name (text content) is visible on the page.
+ *
+ * ```gherkin
+ * Then I see link {string}
+ * ```
+ *
+ * @param text - The accessible name (text) of the link expected to be visible.
+ *
+ * @example
+ * Then I see link "Home"
+ * Then I see link "View Details"
+ *
+ * @remarks
+ * This step uses Playwright's `page.getByRole("link", { name: text })` for robust
+ * link finding based on accessible name, then `expect().toBeVisible()` for visibility.
+ * @category Link Assertion Steps
+ */
+async function Then_I_see_link(text) {
+    const linkLocator = this.page.getByRole("link", { name: text });
+    await (0, test_1.expect)(linkLocator).toBeVisible({ timeout: 5000 });
+    this.log?.(`✅ Verified link "${text}" is visible.`);
+}
+(0, cucumber_1.Then)("I see link {string}", Then_I_see_link);
+/**
+ * Asserts that a link (`<a>` tag) with the given accessible name (text content) is NOT visible on the page.
+ *
+ * ```gherkin
+ * Then I do not see link {string}
+ * ```
+ *
+ * @param text - The accessible name (text) of the link expected NOT to be visible.
+ *
+ * @example
+ * Then I do not see link "Admin Panel"
+ *
+ * @remarks
+ * This step uses Playwright's `page.getByRole("link", { name: text })` and then
+ * `expect().not.toBeVisible()` to confirm its non-visibility.
+ * @category Link Assertion Steps
+ */
+async function Then_I_do_not_see_link(text) {
+    const linkLocator = this.page.getByRole("link", { name: text });
+    await (0, test_1.expect)(linkLocator).not.toBeVisible({ timeout: 5000 });
+    this.log?.(`✅ Verified link "${text}" is NOT visible.`);
+}
+(0, cucumber_1.Then)("I do not see link {string}", Then_I_do_not_see_link);
+// ===================================================================================
+// ASSERTIONS: LOCATOR COUNT
+// ===================================================================================
+/**
+ * Asserts that the number of elements found by the {@link CustomWorld.currentLocator | currentLocator}
+ * matches the expected count. If no `currentLocator` is set, it defaults to counting all elements (`*`).
+ *
+ * ```gherkin
+ * Then I count {int} element
+ * ```
+ *
+ * @param expectedCount - The expected number of elements.
+ *
+ * @example
+ * When I find elements by selector ".product-item"
+ * Then I count 10 element
+ *
+ * @remarks
+ * This step is designed to follow a "find elements" step that sets `this.currentLocator`
+ * or `this.elements` (if `this.elements` is the intended source, you might prefer a
+ * step like `Then I count {int} elements` which specifically targets `this.elements`).
+ * The current implementation uses `this.currentLocator` or defaults to `this.page.locator("*")`.
+ * @category Count Assertion Steps
+ */
+async function Then_I_count_current_locator_elements(expectedCount) {
+    // If currentLocator is not set, default to finding all elements on the page.
+    // This might lead to unexpected behavior if not intended.
+    const locatorToCount = this.currentLocator ?? this.page.locator("*");
+    await (0, test_1.expect)(locatorToCount).toHaveCount(expectedCount, { timeout: 5000 });
+    this.log?.(`✅ Verified current locator has ${expectedCount} element(s).`);
+}
+(0, cucumber_1.Then)("I count {int} element", Then_I_count_current_locator_elements);
+// ===================================================================================
+// ASSERTIONS: DOCUMENT TITLE
+// ===================================================================================
+/**
+ * Asserts that the current document title exactly matches the expected string.
+ *
+ * ```gherkin
+ * Then I see document title {string}
+ * ```
+ *
+ * @param expectedTitle - The exact title string expected for the document.
+ * @param table - (Optional) A Cucumber DataTable for Playwright `ExpectOptions` (e.g., `timeout`).
+ *
+ * @example
+ * Then I see document title "My Application Dashboard"
+ *
+ * @remarks
+ * This step uses Playwright's `expect(page).toHaveTitle()` for robust assertion,
+ * including automatic waiting for the title to become correct.
+ * @category Page State Assertion Steps
+ */
+async function Then_I_see_document_title(expectedTitle, table) {
     const options = (0, optionsUtils_1.parseExpectOptions)(table);
-    await (0, test_1.expect)(this.page).toHaveTitle(expected, options);
-});
-(0, cucumber_1.Then)("I see document title contains {string}", async function (substring, table) {
+    await (0, test_1.expect)(this.page).toHaveTitle(expectedTitle, options);
+    this.log?.(`✅ Verified document title is "${expectedTitle}".`);
+}
+(0, cucumber_1.Then)("I see document title {string}", Then_I_see_document_title);
+/**
+ * Asserts that the current document title contains the expected substring (case-insensitive).
+ *
+ * ```gherkin
+ * Then I see document title contains {string}
+ * ```
+ *
+ * @param substring - The substring expected to be contained within the document title.
+ * @param table - (Optional) A Cucumber DataTable for Playwright `ExpectOptions`.
+ *
+ * @example
+ * Then I see document title contains "App Name"
+ * Then I see document title contains "Dashboard"
+ *
+ * @remarks
+ * This step uses Playwright's `expect(page).toHaveTitle()` with a case-insensitive regular
+ * expression for partial matching, ensuring automatic waiting.
+ * @category Page State Assertion Steps
+ */
+async function Then_I_see_document_title_contains(substring, table) {
     const options = (0, optionsUtils_1.parseExpectOptions)(table);
+    // Use RegExp for case-insensitive partial match
     await (0, test_1.expect)(this.page).toHaveTitle(new RegExp(substring, "i"), options);
-});
+    this.log?.(`✅ Verified document title contains "${substring}".`);
+}
+(0, cucumber_1.Then)("I see document title contains {string}", Then_I_see_document_title_contains);

package/lib/assertions/storageSteps.d.ts

@@ -1 +1,149 @@
-export {};
+import type { CustomWorld } from "../helpers/world";
+/**
+ * Asserts that a Local Storage item with the given key exists for the current page's origin.
+ *
+ * ```gherkin
+ * Then I see local storage item {string}
+ * ```
+ *
+ * @param key - The key of the Local Storage item expected to exist.
+ *
+ * @example
+ * Then I see local storage item "token"
+ *
+ * @remarks
+ * This step executes `localStorage.getItem(key)` in the browser's context.
+ * It asserts that the returned value is not `null`, indicating the item exists.
+ * @category Storage Assertion Steps
+ */
+export declare function Then_I_see_local_storage_item(this: CustomWorld, key: string): Promise<void>;
+/**
+ * Asserts that a Local Storage item with the given key does NOT exist for the current page's origin.
+ *
+ * ```gherkin
+ * Then I do not see local storage item {string}
+ * ```
+ *
+ * @param key - The key of the Local Storage item expected NOT to exist.
+ *
+ * @example
+ * Then I do not see local storage item "oldFeatureFlag"
+ *
+ * @remarks
+ * This step executes `localStorage.getItem(key)` in the browser's context.
+ * It asserts that the returned value is strictly `null`, indicating the item does not exist.
+ * @category Storage Assertion Steps
+ */
+export declare function Then_I_do_not_see_local_storage_item(this: CustomWorld, key: string): Promise<void>;
+/**
+ * Asserts that a Local Storage item with the given key exactly equals the expected value.
+ *
+ * ```gherkin
+ * Then I see local storage item {string} equals {string}
+ * ```
+ *
+ * @param key - The key of the Local Storage item.
+ * @param expectedValue - The exact value the item is expected to have.
+ *
+ * @example
+ * Then I see local storage item "token" equals "abc123"
+ *
+ * @remarks
+ * This step executes `localStorage.getItem(key)` in the browser's context.
+ * It asserts strict equality between the retrieved value and `expectedValue`.
+ * @category Storage Assertion Steps
+ */
+export declare function Then_I_see_local_storage_item_equals(this: CustomWorld, key: string, expectedValue: string): Promise<void>;
+/**
+ * Asserts that a Local Storage item with the given key contains the expected substring.
+ *
+ * ```gherkin
+ * Then I see local storage item {string} contains {string}
+ * ```
+ *
+ * @param key - The key of the Local Storage item.
+ * @param part - The substring expected to be contained within the item's value.
+ *
+ * @example
+ * Then I see local storage item "userSession" contains "loggedIn"
+ *
+ * @remarks
+ * This step executes `localStorage.getItem(key)` in the browser's context.
+ * It asserts that the retrieved value (if not null) includes the `part` substring.
+ * @category Storage Assertion Steps
+ */
+export declare function Then_I_see_local_storage_item_contains(this: CustomWorld, key: string, part: string): Promise<void>;
+/**
+ * Asserts that a Session Storage item with the given key exists for the current page's origin.
+ *
+ * ```gherkin
+ * Then I see session storage item {string}
+ * ```
+ *
+ * @param key - The key of the Session Storage item expected to exist.
+ *
+ * @example
+ * Then I see session storage item "sessionId"
+ *
+ * @remarks
+ * This step executes `sessionStorage.getItem(key)` in the browser's context.
+ * It asserts that the returned value is not `null`, indicating the item exists.
+ * @category Storage Assertion Steps
+ */
+export declare function Then_I_see_session_storage_item(this: CustomWorld, key: string): Promise<void>;
+/**
+ * Asserts that a Session Storage item with the given key does NOT exist for the current page's origin.
+ *
+ * ```gherkin
+ * Then I do not see session storage item {string}
+ * ```
+ *
+ * @param key - The key of the Session Storage item expected NOT to exist.
+ *
+ * @example
+ * Then I do not see session storage item "tempData"
+ *
+ * @remarks
+ * This step executes `sessionStorage.getItem(key)` in the browser's context.
+ * It asserts that the returned value is strictly `null`, indicating the item does not exist.
+ * @category Storage Assertion Steps
+ */
+export declare function Then_I_do_not_see_session_storage_item(this: CustomWorld, key: string): Promise<void>;
+/**
+ * Asserts that a Session Storage item with the given key exactly equals the expected value.
+ *
+ * ```gherkin
+ * Then I see session storage item {string} equals {string}
+ * ```
+ *
+ * @param key - The key of the Session Storage item.
+ * @param expectedValue - The exact value the item is expected to have.
+ *
+ * @example
+ * Then I see session storage item "sessionId" equals "xyz789"
+ *
+ * @remarks
+ * This step executes `sessionStorage.getItem(key)` in the browser's context.
+ * It asserts strict equality between the retrieved value and `expectedValue`.
+ * @category Storage Assertion Steps
+ */
+export declare function Then_I_see_session_storage_item_equals(this: CustomWorld, key: string, expectedValue: string): Promise<void>;
+/**
+ * Asserts that a Session Storage item with the given key contains the expected substring.
+ *
+ * ```gherkin
+ * Then I see session storage item {string} contains {string}
+ * ```
+ *
+ * @param key - The key of the Session Storage item.
+ * @param part - The substring expected to be contained within the item's value.
+ *
+ * @example
+ * Then I see session storage item "userState" contains "authenticated"
+ *
+ * @remarks
+ * This step executes `sessionStorage.getItem(key)` in the browser's context.
+ * It asserts that the retrieved value (if not null) includes the `part` substring.
+ * @category Storage Assertion Steps
+ */
+export declare function Then_I_see_session_storage_item_contains(this: CustomWorld, key: string, part: string): Promise<void>;