playwright-cucumber-ts-steps 0.1.7 → 1.0.1

package/src/assertions/cookieSteps.ts

@@ -1,52 +1,131 @@
 import { Then } from "@cucumber/cucumber";
-import type { CustomWorld } from "../helpers/world";
+import { expect } from "@playwright/test"; // Import expect for more robust assertions where applicable
+import type { CustomWorld } from "../helpers/world"; // Assuming this path is correct
+
+// ===================================================================================
+// ASSERTIONS: COOKIES
+// ===================================================================================
 
 /**
- * THEN: I see cookie "myCookie"
+ * Asserts that a cookie with the given name exists in the browser context.
+ *
+ * ```gherkin
+ * Then I see cookie {string}
+ * ```
+ *
+ * @param cookieName - The name of the cookie expected to exist.
+ *
+ * @example
+ * Then I see cookie "session_id"
+ *
+ * @remarks
+ * This step retrieves all cookies from the current Playwright browser context
+ * and checks if a cookie with `cookieName` is present.
+ * @category Cookie Assertion Steps
  */
-Then("I see cookie {string}", async function (this: CustomWorld, cookieName: string) {
+export async function Then_I_see_cookie(this: CustomWorld, cookieName: string) {
   const cookies = await this.context.cookies();
   const cookie = cookies.find((c) => c.name === cookieName);
-  if (!cookie) throw new Error(`Cookie "${cookieName}" not found`);
-});
+
+  // Using Playwright's expect for better assertion messages and retries (if configured)
+  expect(cookie, `Cookie "${cookieName}" should exist but was not found.`).toBeDefined();
+  this.log?.(`✅ Verified cookie "${cookieName}" exists.`);
+}
+Then("I see cookie {string}", Then_I_see_cookie);
 
 /**
- * THEN: I do not see cookie "myCookie"
+ * Asserts that a cookie with the given name does NOT exist in the browser context.
+ *
+ * ```gherkin
+ * Then I do not see cookie {string}
+ * ```
+ *
+ * @param cookieName - The name of the cookie expected NOT to exist.
+ *
+ * @example
+ * Then I do not see cookie "expired_token"
+ *
+ * @remarks
+ * This step retrieves all cookies from the current Playwright browser context
+ * and asserts that no cookie with `cookieName` is present.
+ * @category Cookie Assertion Steps
  */
-Then("I do not see cookie {string}", async function (this: CustomWorld, name: string) {
+export async function Then_I_do_not_see_cookie(this: CustomWorld, cookieName: string) {
   const cookies = await this.context.cookies();
-  const cookie = cookies.find((c) => c.name === name);
-  if (cookie) throw new Error(`Cookie "${name}" was found but should not exist`);
-});
+  const cookie = cookies.find((c) => c.name === cookieName);
+
+  // Using Playwright's expect for better assertion messages and retries
+  expect(cookie, `Cookie "${cookieName}" should NOT exist but was found.`).toBeUndefined();
+  this.log?.(`✅ Verified cookie "${cookieName}" does not exist.`);
+}
+Then("I do not see cookie {string}", Then_I_do_not_see_cookie);
 
 /**
- * THEN: I see cookie "sessionId" has value "abc123"
+ * Asserts that a cookie with the given name exists and has an exact expected value.
+ *
+ * ```gherkin
+ * Then I see cookie {string} has value {string}
+ * ```
+ *
+ * @param cookieName - The name of the cookie to check.
+ * @param expectedValue - The exact value the cookie is expected to have.
+ *
+ * @example
+ * Then I see cookie "sessionId" has value "abc123"
+ *
+ * @remarks
+ * This step finds the cookie by name and then asserts that its `value` property
+ * strictly matches `expectedValue`.
+ * @category Cookie Assertion Steps
  */
-Then(
-  "I see cookie {string} has value {string}",
-  async function (this: CustomWorld, name: string, expectedValue: string) {
-    const cookies = await this.context.cookies();
-    const cookie = cookies.find((c) => c.name === name);
-    if (!cookie) throw new Error(`Cookie "${name}" not found`);
-    if (cookie.value !== expectedValue) {
-      throw new Error(
-        `Expected cookie "${name}" to have value "${expectedValue}", but got "${cookie.value}"`
-      );
-    }
-  }
-);
+export async function Then_I_see_cookie_has_value(
+  this: CustomWorld,
+  cookieName: string,
+  expectedValue: string
+) {
+  const cookies = await this.context.cookies();
+  const cookie = cookies.find((c) => c.name === cookieName);
+
+  expect(cookie, `Cookie "${cookieName}" not found.`).toBeDefined();
+  expect(
+    cookie?.value,
+    `Expected cookie "${cookieName}" to have value "${expectedValue}", but got "${cookie?.value}".`
+  ).toBe(expectedValue);
+  this.log?.(`✅ Verified cookie "${cookieName}" has value "${expectedValue}".`);
+}
+Then("I see cookie {string} has value {string}", Then_I_see_cookie_has_value);
 
 /**
- * THEN: I see cookie "token" contains value "auth"
+ * Asserts that a cookie with the given name exists and its value contains a specific substring.
+ *
+ * ```gherkin
+ * Then I see cookie {string} contains value {string}
+ * ```
+ *
+ * @param cookieName - The name of the cookie to check.
+ * @param valuePart - The substring expected to be present within the cookie's value.
+ *
+ * @example
+ * Then I see cookie "token" contains value "auth_type"
+ *
+ * @remarks
+ * This step finds the cookie by name and then asserts that its `value` property
+ * includes the `valuePart` string. Useful for tokens or complex cookie values.
+ * @category Cookie Assertion Steps
  */
-Then(
-  "I see cookie {string} contains value {string}",
-  async function (this: CustomWorld, name: string, valuePart: string) {
-    const cookies = await this.context.cookies();
-    const cookie = cookies.find((c) => c.name === name);
-    if (!cookie) throw new Error(`Cookie "${name}" not found`);
-    if (!cookie.value.includes(valuePart)) {
-      throw new Error(`Cookie "${name}" does not contain value "${valuePart}"`);
-    }
-  }
-);
+export async function Then_I_see_cookie_contains_value(
+  this: CustomWorld,
+  cookieName: string,
+  valuePart: string
+) {
+  const cookies = await this.context.cookies();
+  const cookie = cookies.find((c) => c.name === cookieName);
+
+  expect(cookie, `Cookie "${cookieName}" not found.`).toBeDefined();
+  expect(
+    cookie?.value,
+    `Expected cookie "${cookieName}" to contain "${valuePart}", but got "${cookie?.value}".`
+  ).toContain(valuePart);
+  this.log?.(`✅ Verified cookie "${cookieName}" contains value "${valuePart}".`);
+}
+Then("I see cookie {string} contains value {string}", Then_I_see_cookie_contains_value);

package/src/assertions/elementSteps.ts

@@ -1,103 +1,432 @@
 import { Then } from "@cucumber/cucumber";
 import { expect } from "@playwright/test";
-import type { CustomWorld } from "../helpers/world";
-//
-// ✅ ELEMENT EXISTS
-//
-
-Then(/^I see element "([^"]+)" exists$/, async function (this: any, selector: string) {
-  const el = await this.page.locator(selector);
-  await expect(el).toHaveCount(1);
-});
-Then("I see element exists", async function (this: CustomWorld) {
-  if (!this.element) throw new Error("No element stored in context");
-  const count = (await this.element.count?.()) ?? 1;
-  if (count === 0) throw new Error("Element does not exist");
-});
-Then("I see element does not exist", async function (this: CustomWorld) {
-  if (!this.element) throw new Error("No element stored in context");
-  const count = (await this.element.count?.()) ?? 1;
-  if (count > 0) throw new Error("Element exists but should not");
-});
-Then("I see element is visible", async function (this: CustomWorld) {
-  if (!this.element) throw new Error("No element in context");
-  const isVisible = await this.element.isVisible();
-  if (!isVisible) throw new Error("Element is not visible");
-});
-Then("I see element is not visible", async function (this: CustomWorld) {
-  if (!this.element) throw new Error("No element in context");
-  const isVisible = await this.element.isVisible();
-  if (isVisible) throw new Error("Element is visible but should not be");
-});
-
-Then(/^I see element "([^"]+)" does not exist$/, async function (this: any, selector: string) {
-  const el = await this.page.locator(selector);
-  await expect(el).toHaveCount(0);
-});
-
-//
-// 👁️ ELEMENT VISIBILITY
-//
-
-Then(/^I see element "([^"]+)" is visible$/, async function (this: any, selector: string) {
-  const el = this.page.locator(selector);
-  await expect(el).toBeVisible();
-});
-
-Then(/^I see element "([^"]+)" is not visible$/, async function (this: any, selector: string) {
-  const el = this.page.locator(selector);
-  await expect(el).not.toBeVisible();
-});
-
-//
-// 🔎 ATTRIBUTE ASSERTIONS
-//
+import type { CustomWorld } from "../helpers/world"; // Assuming this path is correct
 
+// ===================================================================================
+// ASSERTIONS: ELEMENT EXISTENCE (IN DOM)
+// ===================================================================================
+
+/**
+ * Asserts that at least one element matching the given selector exists in the DOM.
+ * It does not necessarily check for visibility.
+ *
+ * ```gherkin
+ * Then I see element {string} exists
+ * ```
+ *
+ * @param selector - The CSS selector of the element expected to exist.
+ *
+ * @example
+ * Then I see element ".user-profile-card" exists
+ *
+ * @remarks
+ * This step uses Playwright's `expect(locator).toHaveCount(1)` as a robust way to
+ * assert that exactly one matching element is present in the DOM. If multiple elements
+ * match, it will still pass as long as at least one exists (though `toHaveCount(1)`
+ * would strictly mean *only one*). For asserting multiple elements, use "Then I count X elements".
+ * @category Assertion Steps
+ */
+export async function Then_I_see_element_exists(this: CustomWorld, selector: string) {
+  const locator = this.page.locator(selector);
+  // Using toHaveCount(1) for "exists" implies expecting at least one, or exactly one.
+  // If the intent is *at least one*, expect(locator).first().waitFor({state: 'attached'}) is also an option.
+  // For strict "exists", toHaveCount(1) is good if you expect uniqueness.
+  await expect(locator).toHaveCount(1, { timeout: 5000 });
+  this.log?.(`✅ Verified element "${selector}" exists in the DOM.`);
+}
+Then(/^I see element "([^"]+)" exists$/, Then_I_see_element_exists);
+
+/**
+ * Asserts that the previously stored element exists in the DOM.
+ * This checks for its presence, not necessarily its visibility.
+ *
+ * ```gherkin
+ * Then I see element exists
+ * ```
+ *
+ * @example
+ * When I find element by selector ".my-dialog"
+ * Then I see element exists
+ *
+ * @remarks
+ * This step requires a preceding step that sets the {@link CustomWorld.element | current element}.
+ * It asserts that the stored element is attached to the DOM.
+ * @category Assertion Steps
+ */
+export async function Then_I_see_stored_element_exists(this: CustomWorld) {
+  if (!this.element)
+    throw new Error("No element stored in context. Use a 'find' step before asserting.");
+
+  // Playwright's toBeAttached is the most robust way to check for DOM existence
+  await expect(this.element).toBeAttached({ timeout: 5000 });
+  this.log?.(`✅ Verified stored element exists in the DOM.`);
+}
+Then("I see element exists", Then_I_see_stored_element_exists);
+
+/**
+ * Asserts that the previously stored element does NOT exist in the DOM.
+ *
+ * ```gherkin
+ * Then I see element does not exist
+ * ```
+ *
+ * @example
+ * When I find element by selector "#deleted-item"
+ * Then I see element does not exist
+ *
+ * @remarks
+ * This step requires a preceding step that sets the {@link CustomWorld.element | current element}.
+ * It asserts that the stored element is detached from the DOM.
+ * @category Assertion Steps
+ */
+export async function Then_I_see_stored_element_does_not_exist(this: CustomWorld) {
+  if (!this.element)
+    throw new Error("No element stored in context. Use a 'find' step before asserting.");
+
+  // Playwright's not.toBeAttached is the most robust way to check for DOM non-existence
+  await expect(this.element).not.toBeAttached({ timeout: 5000 });
+  this.log?.(`✅ Verified stored element does NOT exist in the DOM.`);
+}
+Then("I see element does not exist", Then_I_see_stored_element_does_not_exist);
+
+// ===================================================================================
+// ASSERTIONS: ELEMENT VISIBILITY (Stored Element)
+// ===================================================================================
+
+/**
+ * Asserts that the previously stored element is visible in the viewport.
+ *
+ * ```gherkin
+ * Then I see element is visible
+ * ```
+ *
+ * @example
+ * When I find element by selector ".success-message"
+ * Then I see element is visible
+ *
+ * @remarks
+ * This step requires a preceding step that sets the {@link CustomWorld.element | current element}.
+ * It uses Playwright's `expect(locator).toBeVisible()` which automatically waits
+ * for the element to become visible.
+ * @category Assertion Steps
+ */
+export async function Then_I_see_stored_element_is_visible(this: CustomWorld) {
+  if (!this.element) throw new Error("No element stored in context to check visibility.");
+
+  await expect(this.element).toBeVisible({ timeout: 5000 });
+  this.log?.(`✅ Verified stored element is visible.`);
+}
+Then("I see element is visible", Then_I_see_stored_element_is_visible);
+
+/**
+ * Asserts that the previously stored element is NOT visible in the viewport.
+ *
+ * ```gherkin
+ * Then I see element is not visible
+ * ```
+ *
+ * @example
+ * When I find element by selector ".loading-spinner"
+ * Then I see element is not visible
+ *
+ * @remarks
+ * This step requires a preceding step that sets the {@link CustomWorld.element | current element}.
+ * It uses Playwright's `expect(locator).not.toBeVisible()` which automatically waits
+ * for the element to become hidden.
+ * @category Assertion Steps
+ */
+export async function Then_I_see_stored_element_is_not_visible(this: CustomWorld) {
+  if (!this.element) throw new Error("No element stored in context to check non-visibility.");
+
+  await expect(this.element).not.toBeVisible({ timeout: 5000 });
+  this.log?.(`✅ Verified stored element is NOT visible.`);
+}
+Then("I see element is not visible", Then_I_see_stored_element_is_not_visible);
+
+// ===================================================================================
+// ASSERTIONS: ELEMENT EXISTENCE (Absence by Selector)
+// ===================================================================================
+
+/**
+ * Asserts that no element matching the given selector exists in the DOM.
+ *
+ * ```gherkin
+ * Then I see element {string} does not exist
+ * ```
+ *
+ * @param selector - The CSS selector of the element expected NOT to exist.
+ *
+ * @example
+ * Then I see element ".old-feature-flag" does not exist
+ *
+ * @remarks
+ * This step uses Playwright's `expect(locator).toHaveCount(0)` as a robust way to
+ * assert that no matching elements are present in the DOM.
+ * @category Assertion Steps
+ */
+export async function Then_I_see_element_does_not_exist(this: CustomWorld, selector: string) {
+  const locator = this.page.locator(selector);
+  await expect(locator).toHaveCount(0, { timeout: 5000 });
+  this.log?.(`✅ Verified element "${selector}" does NOT exist in the DOM.`);
+}
+Then(/^I see element "([^"]+)" does not exist$/, Then_I_see_element_does_not_exist);
+
+// ===================================================================================
+// ASSERTIONS: ELEMENT VISIBILITY (by Selector)
+// ===================================================================================
+
+/**
+ * Asserts that an element matching the given selector is visible in the viewport.
+ *
+ * ```gherkin
+ * Then I see element {string} is visible
+ * ```
+ *
+ * @param selector - The CSS selector of the element expected to be visible.
+ *
+ * @example
+ * Then I see element ".main-content" is visible
+ *
+ * @remarks
+ * This step uses Playwright's `expect(locator).toBeVisible()` which automatically waits
+ * for the element to become visible.
+ * @category Assertion Steps
+ */
+export async function Then_I_see_element_is_visible(this: CustomWorld, selector: string) {
+  const locator = this.page.locator(selector);
+  await expect(locator).toBeVisible({ timeout: 5000 });
+  this.log?.(`✅ Verified element "${selector}" is visible.`);
+}
+Then(/^I see element "([^"]+)" is visible$/, Then_I_see_element_is_visible);
+
+/**
+ * Asserts that an element matching the given selector is NOT visible in the viewport.
+ *
+ * ```gherkin
+ * Then I see element {string} is not visible
+ * ```
+ *
+ * @param selector - The CSS selector of the element expected NOT to be visible.
+ *
+ * @example
+ * Then I see element ".modal-overlay" is not visible
+ *
+ * @remarks
+ * This step uses Playwright's `expect(locator).not.toBeVisible()` which automatically waits
+ * for the element to become hidden.
+ * @category Assertion Steps
+ */
+export async function Then_I_see_element_is_not_visible(this: CustomWorld, selector: string) {
+  const locator = this.page.locator(selector);
+  await expect(locator).not.toBeVisible({ timeout: 5000 });
+  this.log?.(`✅ Verified element "${selector}" is NOT visible.`);
+}
+Then(/^I see element "([^"]+)" is not visible$/, Then_I_see_element_is_not_visible);
+
+// ===================================================================================
+// ASSERTIONS: ATTRIBUTE VALUES
+// ===================================================================================
+
+/**
+ * Asserts that an element matching the given selector has a specific attribute with an exact value.
+ *
+ * ```gherkin
+ * Then I see element {string} attribute {string} equals {string}
+ * ```
+ *
+ * @param selector - The CSS selector of the element to check.
+ * @param attribute - The name of the attribute (e.g., "id", "class", "data-test").
+ * @param expectedValue - The exact expected value of the attribute.
+ *
+ * @example
+ * Then I see element ".submit-button" attribute "disabled" equals "true"
+ *
+ * @remarks
+ * This step uses Playwright's `expect(locator).toHaveAttribute()`.
+ * @category Attribute Assertion Steps
+ */
+export async function Then_I_see_element_attribute_equals(
+  this: CustomWorld,
+  selector: string,
+  attribute: string,
+  expectedValue: string
+) {
+  const locator = this.page.locator(selector);
+  await expect(locator).toHaveAttribute(attribute, expectedValue, { timeout: 5000 });
+  this.log?.(
+    `✅ Verified element "${selector}" has attribute "${attribute}" equal to "${expectedValue}".`
+  );
+}
 Then(
   /^I see element "([^"]+)" attribute "([^"]+)" equals "(.*)"$/,
-  async function (this: any, selector: string, attribute: string, expected: string) {
-    const el = this.page.locator(selector);
-    await expect(el).toHaveAttribute(attribute, expected);
-  }
+  Then_I_see_element_attribute_equals
 );
+
+/**
+ * Asserts that the previously stored element has a specific attribute with an exact value.
+ *
+ * ```gherkin
+ * Then I see element attribute {string} equals {string}
+ * ```
+ *
+ * @param attr - The name of the attribute to check.
+ * @param expectedValue - The exact expected value of the attribute.
+ *
+ * @example
+ * When I find element by selector "input[name='rememberMe']"
+ * Then I see element attribute "checked" equals "checked"
+ *
+ * @remarks
+ * This step requires a preceding step that sets the {@link CustomWorld.element | current element}.
+ * It uses Playwright's `expect(locator).toHaveAttribute()`.
+ * @category Attribute Assertion Steps
+ */
+export async function Then_I_see_stored_element_attribute_equals(
+  this: CustomWorld,
+  attr: string,
+  expectedValue: string
+) {
+  if (!this.element) {
+    throw new Error(
+      "No element is currently selected. Use a 'find' step before asserting its attributes."
+    );
+  }
+  await expect(this.element).toHaveAttribute(attr, expectedValue, { timeout: 5000 });
+  this.log?.(`✅ Verified stored element has attribute "${attr}" equal to "${expectedValue}".`);
+}
 Then(
   'I see element attribute "{word}" equals {string}',
-  async function (this: CustomWorld, attr: string, expected: string) {
-    if (!this.element) {
-      throw new Error("No element is currently selected. Use a 'find' step before asserting.");
-    }
-    await expect(this.element).toHaveAttribute(attr, expected);
-  }
+  Then_I_see_stored_element_attribute_equals
 );
 
-Then("I see element has attribute {string}", async function (this: CustomWorld, attr: string) {
-  if (!this.element) throw new Error("No element in context");
-  const value = await this.element.getAttribute(attr);
-  if (value === null) throw new Error(`Attribute "${attr}" not found`);
-});
+/**
+ * Asserts that the previously stored element has a specific attribute, regardless of its value.
+ *
+ * ```gherkin
+ * Then I see element has attribute {string}
+ * ```
+ *
+ * @param attr - The name of the attribute expected to exist.
+ *
+ * @example
+ * When I find element by selector "img.user-avatar"
+ * Then I see element has attribute "alt"
+ *
+ * @remarks
+ * This step requires a preceding step that sets the {@link CustomWorld.element | current element}.
+ * It retrieves the attribute's value and asserts that it's not `null` (meaning the attribute is present).
+ * @category Attribute Assertion Steps
+ */
+export async function Then_I_see_stored_element_has_attribute(this: CustomWorld, attr: string) {
+  if (!this.element) throw new Error("No element stored in context to check for attribute.");
+
+  // Use Playwright's expect.toHaveAttribute for robust checking of existence (value can be empty string, but not null)
+  // For simply checking existence, we can assert that the attribute is not null or undefined.
+  const attributeValue = await this.element.getAttribute(attr, { timeout: 5000 });
+  expect(attributeValue).not.toBeNull();
+  this.log?.(`✅ Verified stored element has attribute "${attr}".`);
+}
+Then("I see element has attribute {string}", Then_I_see_stored_element_has_attribute);
+
+/**
+ * Asserts that the previously stored element's specific attribute contains a given substring.
+ *
+ * ```gherkin
+ * Then I see element attribute {string} contains {string}
+ * ```
+ *
+ * @param attr - The name of the attribute to check.
+ * @param part - The substring expected to be contained within the attribute's value.
+ *
+ * @example
+ * When I find element by selector ".product-image"
+ * Then I see element attribute "src" contains "thumbnail"
+ *
+ * @remarks
+ * This step requires a preceding step that sets the {@link CustomWorld.element | current element}.
+ * It retrieves the attribute's value and asserts that it includes the `part` substring.
+ * @category Attribute Assertion Steps
+ */
+export async function Then_I_see_stored_element_attribute_contains(
+  this: CustomWorld,
+  attr: string,
+  part: string
+) {
+  if (!this.element) throw new Error("No element stored in context to check attribute content.");
+
+  // Use Playwright's expect.toHaveAttribute with a regex for 'contains' check
+  await expect(this.element).toHaveAttribute(attr, new RegExp(part), { timeout: 5000 });
+  this.log?.(`✅ Verified stored element attribute "${attr}" contains "${part}".`);
+}
 Then(
   'I see element attribute "{word}" contains {string}',
-  async function (this: CustomWorld, attr: string, part: string) {
-    if (!this.element) throw new Error("No element in context");
-    const value = await this.element.getAttribute(attr);
-    if (!value?.includes(part)) {
-      throw new Error(`Attribute "${attr}" does not contain "${part}". Got: "${value}"`);
-    }
-  }
+  Then_I_see_stored_element_attribute_contains
 );
 
+/**
+ * Asserts that an element matching the given selector has a specific attribute containing a given substring.
+ *
+ * ```gherkin
+ * Then I see element {string} attribute {string} contains {string}
+ * ```
+ *
+ * @param selector - The CSS selector of the element to check.
+ * @param attribute - The name of the attribute.
+ * @param substring - The substring expected to be contained within the attribute's value.
+ *
+ * @example
+ * Then I see element "a.download-link" attribute "href" contains ".pdf"
+ *
+ * @remarks
+ * This step retrieves the attribute's value from the element matching the selector
+ * and asserts that it includes the `substring`.
+ * @category Attribute Assertion Steps
+ */
+export async function Then_I_see_element_attribute_contains(
+  this: CustomWorld,
+  selector: string,
+  attribute: string,
+  substring: string
+) {
+  const locator = this.page.locator(selector);
+  // Use Playwright's expect.toHaveAttribute with a regex for 'contains' check
+  await expect(locator).toHaveAttribute(attribute, new RegExp(substring), { timeout: 5000 });
+  this.log?.(`✅ Verified element "${selector}" attribute "${attribute}" contains "${substring}".`);
+}
 Then(
   /^I see element "([^"]+)" attribute "([^"]+)" contains "(.*)"$/,
-  async function (this: any, selector: string, attribute: string, substring: string) {
-    const attr = await this.page.locator(selector).getAttribute(attribute);
-    expect(attr?.includes(substring)).toBeTruthy();
-  }
+  Then_I_see_element_attribute_contains
 );
 
-Then(
-  /^I see element "([^"]+)" has attribute "([^"]+)"$/,
-  async function (this: any, selector: string, attribute: string) {
-    const attr = await this.page.locator(selector).getAttribute(attribute);
-    expect(attr).not.toBeNull();
-  }
-);
+/**
+ * Asserts that an element matching the given selector has a specific attribute, regardless of its value.
+ *
+ * ```gherkin
+ * Then I see element {string} has attribute {string}
+ * ```
+ *
+ * @param selector - The CSS selector of the element to check.
+ * @param attribute - The name of the attribute expected to exist.
+ *
+ * @example
+ * Then I see element "img.avatar" has attribute "src"
+ *
+ * @remarks
+ * This step retrieves the attribute's value from the element matching the selector
+ * and asserts that it's not `null` (meaning the attribute is present).
+ * @category Attribute Assertion Steps
+ */
+export async function Then_I_see_element_has_attribute(
+  this: CustomWorld,
+  selector: string,
+  attribute: string
+) {
+  const locator = this.page.locator(selector);
+  // Playwright's toHaveAttribute with an empty string or regex can assert existence effectively.
+  // toHaveAttribute(attr, /.+/) ensures it exists and has *some* non-empty value.
+  // For just existence, checking if getAttribute is not null is explicit.
+  const attributeValue = await locator.getAttribute(attribute, { timeout: 5000 });
+  expect(attributeValue).not.toBeNull();
+  this.log?.(`✅ Verified element "${selector}" has attribute "${attribute}".`);
+}
+Then(/^I see element "([^"]+)" has attribute "([^"]+)"$/, Then_I_see_element_has_attribute);