playwright-cucumber-ts-steps 0.1.5 → 0.1.7

package/src/assertions/locationSteps.ts

@@ -0,0 +1,99 @@
+import { Then, DataTable } from "@cucumber/cucumber";
+import { expect } from "@playwright/test";
+import { CustomWorld } from "../helpers/world";
+//
+// 🌐 URL
+//
+
+Then("I see URL {string}", async function (this: CustomWorld, expected: string) {
+  const url = this.page.url();
+  expect(url).toBe(expected);
+});
+
+Then("I do not see URL {string}", async function (this: CustomWorld, notExpected: string) {
+  const url = this.page.url();
+  if (url === notExpected) throw new Error(`Expected not to be on URL "${notExpected}"`);
+});
+
+Then("I see URL contains {string}", async function (this: CustomWorld, expected: string) {
+  const url = this.page.url();
+  expect(url).toContain(expected);
+});
+
+Then("I do not see URL contains {string}", async function (this: CustomWorld, notExpected: string) {
+  const url = this.page.url();
+  if (url.includes(notExpected)) {
+    throw new Error(`URL should not contain "${notExpected}", but got "${url}"`);
+  }
+});
+
+//
+// 📍 LOCATION PARTS
+//
+
+Then("I see location {string}", async function (this: CustomWorld, expected: string) {
+  const location = await this.page.evaluate(() => window.location.href);
+  if (location !== expected) {
+    throw new Error(`Expected location to be "${expected}", but got "${location}"`);
+  }
+});
+
+Then("I see pathname {string}", async function (this: CustomWorld, expected: string) {
+  const pathname = await this.page.evaluate(() => window.location.pathname);
+  if (pathname !== expected) {
+    throw new Error(`Expected pathname "${expected}", but got "${pathname}"`);
+  }
+});
+
+Then("I see pathname contains {string}", async function (this: CustomWorld, part: string) {
+  const pathname = await this.page.evaluate(() => window.location.pathname);
+  if (!pathname.includes(part)) {
+    throw new Error(`Pathname does not contain "${part}". Got: "${pathname}"`);
+  }
+});
+
+Then("I see hash {string}", async function (this: CustomWorld, expected: string) {
+  const hash = await this.page.evaluate(() => window.location.hash);
+  if (hash !== expected) {
+    throw new Error(`Expected hash "${expected}", but got "${hash}"`);
+  }
+});
+
+Then("I see hash contains {string}", async function (this: CustomWorld, part: string) {
+  const hash = await this.page.evaluate(() => window.location.hash);
+  if (!hash.includes(part)) {
+    throw new Error(`Expected hash to contain "${part}", but got "${hash}"`);
+  }
+});
+
+Then("I see search {string}", async function (this: CustomWorld, expected: string) {
+  const search = await this.page.evaluate(() => window.location.search);
+  if (search !== expected) {
+    throw new Error(`Expected search to be "${expected}", but got "${search}"`);
+  }
+});
+
+Then("I see search contains {string}", async function (this: CustomWorld, part: string) {
+  const search = await this.page.evaluate(() => window.location.search);
+  if (!search.includes(part)) {
+    throw new Error(`Search does not contain "${part}". Got: "${search}"`);
+  }
+});
+
+Then("I see location", async function (table: DataTable) {
+  const location = await this.page.evaluate(() => ({
+    href: window.location.href,
+    origin: window.location.origin,
+    protocol: window.location.protocol,
+    host: window.location.host,
+    hostname: window.location.hostname,
+    port: window.location.port,
+    pathname: window.location.pathname,
+    search: window.location.search,
+    hash: window.location.hash,
+  }));
+
+  for (const [key, expected] of table.rows()) {
+    expect(location[key as keyof typeof location]).toBe(expected);
+  }
+});

package/src/assertions/roleTestIdSteps.ts

@@ -0,0 +1,36 @@
+import { Then } from "@cucumber/cucumber";
+import { expect } from "@playwright/test";
+
+//
+// 🧩 ROLE-BASED ELEMENTS
+//
+
+Then(
+  /^I see role "(.*)" with name "(.*)"$/,
+  async function (this: any, role: string, name: string) {
+    const el = this.page.getByRole(role, { name, exact: true });
+    await expect(el).toBeVisible();
+  }
+);
+
+Then(
+  /^I do not see role "(.*)" with name "(.*)"$/,
+  async function (this: any, role: string, name: string) {
+    const el = this.page.getByRole(role, { name, exact: true });
+    await expect(el).toHaveCount(0);
+  }
+);
+
+//
+// 🏷️ TEST ID-BASED ELEMENTS
+//
+
+Then(/^I see testid "(.*)"$/, async function (this: any, testId: string) {
+  const el = this.page.getByTestId(testId);
+  await expect(el).toBeVisible();
+});
+
+Then(/^I do not see testid "(.*)"$/, async function (this: any, testId: string) {
+  const el = this.page.getByTestId(testId);
+  await expect(el).toHaveCount(0);
+});

package/src/assertions/semanticSteps.ts

@@ -0,0 +1,79 @@
+import { Then, DataTable } from "@cucumber/cucumber";
+import { expect } from "@playwright/test";
+import { parseExpectOptions } from "../helpers/utils/optionsUtils";
+import type { CustomWorld } from "../helpers/world";
+//
+// 🧠 HEADINGS
+//
+
+Then("I see heading {string}", async function (this: CustomWorld, text: string) {
+  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`);
+  }
+});
+
+Then("I do not see heading {string}", async function (this: CustomWorld, text: string) {
+  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
+//
+
+Then("I see label {string}", async function (this: CustomWorld, text: string) {
+  const label = this.page.getByLabel(text);
+  if (!(await label.isVisible())) {
+    throw new Error(`Label "${text}" not visible`);
+  }
+});
+
+Then("I do not see label {string}", async function (this: CustomWorld, text: string) {
+  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
+//
+Then("I see link {string}", async function (this: CustomWorld, text: string) {
+  const link = this.page.getByRole("link", { name: text });
+  if (!(await link.isVisible())) {
+    throw new Error(`Link "${text}" not visible`);
+  }
+});
+
+Then("I do not see link {string}", async function (this: CustomWorld, text: string) {
+  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`);
+  }
+});
+Then("I count {int} element", async function (count: number) {
+  const locator = this.currentLocator ?? this.page.locator("*");
+  await expect(locator).toHaveCount(count);
+});
+//document title assertions
+Then(
+  "I see document title {string}",
+  async function (this: CustomWorld, expected: string, table?: DataTable) {
+    const options = parseExpectOptions(table);
+    await expect(this.page).toHaveTitle(expected, options);
+  }
+);
+
+Then(
+  "I see document title contains {string}",
+  async function (this: CustomWorld, substring: string, table?: DataTable) {
+    const options = parseExpectOptions(table);
+    await expect(this.page).toHaveTitle(new RegExp(substring, "i"), options);
+  }
+);

package/src/assertions/storageSteps.ts

@@ -0,0 +1,89 @@
+import fs from "fs";
+import path from "path";
+import { When, Then } from "@cucumber/cucumber";
+import type { CustomWorld } from "../helpers/world";
+//
+// 🗃 LOCAL STORAGE
+//
+
+Then("I see local storage item {string}", async function (this: CustomWorld, key: string) {
+  const value = await this.page.evaluate((k) => localStorage.getItem(k), key);
+  if (value === null) throw new Error(`Local storage item "${key}" not found`);
+});
+
+Then("I do not see local storage item {string}", async function (this: CustomWorld, key: string) {
+  const value = await this.page.evaluate((k) => localStorage.getItem(k), key);
+  if (value !== null)
+    throw new Error(`Expected localStorage["${key}"] to be null, but got "${value}"`);
+});
+
+Then(
+  "I see local storage item {string} equals {string}",
+  async function (this: CustomWorld, key: string, expected: string) {
+    const actual = await this.page.evaluate((k) => localStorage.getItem(k), key);
+    if (actual !== expected) {
+      throw new Error(`Expected localStorage["${key}"] to be "${expected}", but got "${actual}"`);
+    }
+  }
+);
+
+Then(
+  "I see local storage item {string} contains {string}",
+  async function (this: CustomWorld, key: string, part: string) {
+    const value = await this.page.evaluate((k) => localStorage.getItem(k), key);
+    if (!value || !value.includes(part)) {
+      throw new Error(`localStorage["${key}"] does not contain "${part}". Got: "${value}"`);
+    }
+  }
+);
+
+//
+// 🗂 SESSION STORAGE
+//
+
+Then("I see session storage item {string}", async function (this: CustomWorld, key: string) {
+  const value = await this.page.evaluate((k) => sessionStorage.getItem(k), key);
+  if (value === null) throw new Error(`Session storage item "${key}" not found`);
+});
+
+Then("I do not see session storage item {string}", async function (this: CustomWorld, key: string) {
+  const value = await this.page.evaluate((k) => sessionStorage.getItem(k), key);
+  if (value !== null)
+    throw new Error(`Expected sessionStorage["${key}"] to be null, but got "${value}"`);
+});
+When("I clear all saved session files", async function (this: CustomWorld) {
+  const authDir = path.resolve("e2e/support/helper/auth");
+
+  if (fs.existsSync(authDir)) {
+    const files = fs.readdirSync(authDir);
+
+    for (const file of files) {
+      const filePath = path.join(authDir, file);
+      if (fs.lstatSync(filePath).isFile()) {
+        fs.unlinkSync(filePath);
+        this.log?.(`🧹 Deleted session file: ${file}`);
+      }
+    }
+  } else {
+    this.log?.(`⚠️ Auth directory not found at ${authDir}`);
+  }
+});
+Then(
+  "I see session storage item {string} equals {string}",
+  async function (this: CustomWorld, key: string, expected: string) {
+    const actual = await this.page.evaluate((k) => sessionStorage.getItem(k), key);
+    if (actual !== expected) {
+      throw new Error(`Expected sessionStorage["${key}"] to be "${expected}", but got "${actual}"`);
+    }
+  }
+);
+
+Then(
+  "I see session storage item {string} contains {string}",
+  async function (this: CustomWorld, key: string, part: string) {
+    const value = await this.page.evaluate((k) => sessionStorage.getItem(k), key);
+    if (!value || !value.includes(part)) {
+      throw new Error(`sessionStorage["${key}"] does not contain "${part}". Got: "${value}"`);
+    }
+  }
+);

package/src/assertions/visualSteps.ts

@@ -0,0 +1,98 @@
+import fs from "fs";
+import path from "path";
+import { Then } from "@cucumber/cucumber";
+import { expect } from "@playwright/test";
+import pixelmatch from "pixelmatch";
+import { PNG } from "pngjs";
+import type { CustomWorld } from "../helpers/world";
+
+const BASELINE_DIR = path.resolve("e2e/snapshots/baseline");
+const CURRENT_DIR = path.resolve("e2e/snapshots/current");
+const DIFF_DIR = path.resolve("e2e/snapshots/diff");
+
+function getSnapshotPaths(name: string) {
+  const safeName = name.replace(/[^a-z0-9]/gi, "_").toLowerCase();
+  return {
+    baseline: path.join(BASELINE_DIR, `${safeName}.png`),
+    current: path.join(CURRENT_DIR, `${safeName}.png`),
+    diff: path.join(DIFF_DIR, `${safeName}.diff.png`),
+  };
+}
+
+Then(
+  "I should see the page matches the snapshot {string}",
+  async function (this: CustomWorld, name: string) {
+    const { page } = this;
+    const paths = getSnapshotPaths(name);
+
+    fs.mkdirSync(BASELINE_DIR, { recursive: true });
+    fs.mkdirSync(CURRENT_DIR, { recursive: true });
+    fs.mkdirSync(DIFF_DIR, { recursive: true });
+
+    await page.screenshot({ path: paths.current, fullPage: true });
+
+    if (!fs.existsSync(paths.baseline)) {
+      fs.copyFileSync(paths.current, paths.baseline);
+      this.log?.(`📸 Created baseline snapshot: ${paths.baseline}`);
+      return;
+    }
+
+    const baseline = PNG.sync.read(fs.readFileSync(paths.baseline));
+    const current = PNG.sync.read(fs.readFileSync(paths.current));
+    const { width, height } = baseline;
+
+    const diff = new PNG({ width, height });
+    const pixelDiff = pixelmatch(baseline.data, current.data, diff.data, width, height, {
+      threshold: 0.1,
+    });
+
+    if (pixelDiff > 0) {
+      fs.writeFileSync(paths.diff, PNG.sync.write(diff));
+      this.log?.(`❌ Visual mismatch detected, diff: ${paths.diff}`);
+    }
+
+    expect(pixelDiff, "Pixels that differ").toBe(0);
+  }
+);
+
+Then(
+  "I capture a snapshot of the element {string} as {string}",
+  async function (this: CustomWorld, selector: string, alias: string) {
+    const element = this.getScope().locator(selector);
+    const pathCurrent = path.join(CURRENT_DIR, `${alias}.png`);
+    fs.mkdirSync(CURRENT_DIR, { recursive: true });
+    await element.screenshot({ path: pathCurrent });
+    this.log?.(`📸 Snapshot for ${selector} saved as ${alias}`);
+  }
+);
+
+Then(
+  "The snapshot {string} should match baseline",
+  async function (this: CustomWorld, alias: string) {
+    const paths = getSnapshotPaths(alias);
+    const current = PNG.sync.read(fs.readFileSync(paths.current));
+    const baseline = fs.existsSync(paths.baseline)
+      ? PNG.sync.read(fs.readFileSync(paths.baseline))
+      : null;
+
+    if (!baseline) {
+      fs.copyFileSync(paths.current, paths.baseline);
+      this.log?.(`📸 Created new baseline for ${alias}`);
+      return;
+    }
+
+    const { width, height } = baseline;
+    const diff = new PNG({ width, height });
+
+    const pixelDiff = pixelmatch(baseline.data, current.data, diff.data, width, height, {
+      threshold: 0.1,
+    });
+
+    if (pixelDiff > 0) {
+      fs.writeFileSync(paths.diff, PNG.sync.write(diff));
+      this.log?.(`⚠️ Snapshot mismatch: ${alias}`);
+    }
+
+    expect(pixelDiff).toBe(0);
+  }
+);

package/src/custom_setups/loginHooks.ts

@@ -0,0 +1,135 @@
+import fs from "fs";
+import { When } from "@cucumber/cucumber";
+import { resolveSessionPath } from "../helpers/utils/resolveUtils";
+import { CustomWorld } from "../helpers/world";
+
+// Step 1: Check and load existing session if valid
+When(
+  "I login with a session data {string}",
+  async function (this: CustomWorld, sessionName: string) {
+    const sessionPath = resolveSessionPath(this, sessionName);
+    this.data.sessionFile = sessionPath;
+
+    if (fs.existsSync(sessionPath)) {
+      try {
+        await this.context?.addCookies(
+          JSON.parse(fs.readFileSync(sessionPath, "utf-8")).cookies || []
+        );
+        this.log?.(`✅ Loaded session from ${sessionPath}`);
+      } catch (err) {
+        this.log?.(`⚠️ Failed to apply session: ${(err as Error).message}`);
+      }
+    } else {
+      this.log?.(`⚠️ Session file not found: ${sessionPath}`);
+    }
+  }
+);
+
+// Step 2: Save current context as session
+When(/^I save session as "([^"]+)"$/, async function (this: CustomWorld, sessionName: string) {
+  const sessionPath = resolveSessionPath(this, sessionName);
+
+  const cookies = await this.context.cookies();
+
+  const [localStorageData, sessionStorageData]: [
+    { origin: string; values: [string, string][] }[],
+    { origin: string; values: [string, string][] }[],
+  ] = await this.page.evaluate(() => {
+    const toPairs = (store: Storage): [string, string][] => Object.entries(store);
+
+    return [
+      [{ origin: location.origin, values: toPairs(localStorage) }],
+      [{ origin: location.origin, values: toPairs(sessionStorage) }],
+    ];
+  });
+
+  const sessionData = {
+    cookies,
+    localStorage: localStorageData,
+    sessionStorage: sessionStorageData,
+  };
+
+  try {
+    fs.writeFileSync(sessionPath, JSON.stringify(sessionData, null, 2));
+    this.log?.(`💾 Saved session as "${sessionName}"`);
+  } catch (err) {
+    this.log?.(`❌ Failed to save session "${sessionName}": ${(err as Error).message}`);
+  }
+});
+// Step 3: Remove a session
+When("I clear session {string}", function (this: CustomWorld, sessionName: string) {
+  const sessionPath = resolveSessionPath(this, sessionName);
+  if (fs.existsSync(sessionPath)) {
+    fs.unlinkSync(sessionPath);
+    this.log?.(`🧹 Cleared session: ${sessionPath}`);
+  } else {
+    this.log?.(`⚠️ Session not found: ${sessionPath}`);
+  }
+});
+When(
+  /^I restore session cookies "([^"]+)"(?: with reload "(true|false)")?$/,
+  async function (this: CustomWorld, sessionName: string, reload = "true") {
+    const sessionPath = resolveSessionPath(this, sessionName);
+
+    if (!fs.existsSync(sessionPath)) {
+      this.log?.(`❌ Session file not found: ${sessionPath}`);
+      return;
+    }
+
+    const sessionData = JSON.parse(fs.readFileSync(sessionPath, "utf-8"));
+    const { cookies = [], localStorage = [], sessionStorage = [] } = sessionData;
+
+    try {
+      // Clear & set cookies
+      if (cookies.length) {
+        const existing = await this.context.cookies();
+        if (existing.length) await this.context.clearCookies();
+        await this.context.addCookies(cookies);
+        this.log?.(`🍪 Cookies restored from "${sessionName}"`);
+      }
+
+      // Apply storage into page context
+      await this.page.goto("about:blank");
+
+      if (localStorage.length > 0) {
+        for (const entry of localStorage) {
+          await this.page.addInitScript(
+            ([origin, values]) => {
+              if (window.origin === origin) {
+                for (const [key, val] of values) {
+                  localStorage.setItem(key, val);
+                }
+              }
+            },
+            [entry.origin, entry.values]
+          );
+        }
+        this.log?.("📦 localStorage restored");
+      }
+
+      if (sessionStorage.length > 0) {
+        for (const entry of sessionStorage) {
+          await this.page.addInitScript(
+            ([origin, values]) => {
+              if (window.origin === origin) {
+                for (const [key, val] of values) {
+                  sessionStorage.setItem(key, val);
+                }
+              }
+            },
+            [entry.origin, entry.values]
+          );
+        }
+        this.log?.("🗄️ sessionStorage restored");
+      }
+
+      // Final reload to apply context if requested
+      if (reload !== "false") {
+        await this.page.reload();
+        this.log?.("🔄 Page reloaded to apply restored session");
+      }
+    } catch (err) {
+      this.log?.(`❌ Error restoring session: ${(err as Error).message}`);
+    }
+  }
+);

package/src/helpers/checkPeerDeps.ts

@@ -0,0 +1,19 @@
+export function checkPeerDependencies(dependencies: string[]) {
+  const missing: string[] = [];
+
+  for (const dep of dependencies) {
+    try {
+      require.resolve(dep);
+    } catch {
+      missing.push(dep);
+    }
+  }
+
+  if (missing.length) {
+    console.warn(
+      `\n❌ Missing peer dependencies: ${missing.join(", ")}` +
+        `\nPlease install them in your project:\n\n` +
+        `npm install --save-dev ${missing.join(" ")}\n`
+    );
+  }
+}

package/src/helpers/compareSnapshots.ts

@@ -0,0 +1,35 @@
+import fs from "fs";
+import pixelmatch from "pixelmatch";
+import { PNG } from "pngjs";
+
+export function compareSnapshots({
+  actualPath,
+  baselinePath,
+  diffPath,
+  threshold = 0.1,
+}: {
+  actualPath: string;
+  baselinePath: string;
+  diffPath: string;
+  threshold?: number;
+}): number {
+  const actual = PNG.sync.read(fs.readFileSync(actualPath));
+  const baseline = PNG.sync.read(fs.readFileSync(baselinePath));
+
+  if (actual.width !== baseline.width || actual.height !== baseline.height) {
+    throw new Error("Snapshot size mismatch");
+  }
+
+  const diff = new PNG({ width: actual.width, height: actual.height });
+  const numDiffPixels = pixelmatch(
+    actual.data,
+    baseline.data,
+    diff.data,
+    actual.width,
+    actual.height,
+    { threshold }
+  );
+
+  fs.writeFileSync(diffPath, PNG.sync.write(diff));
+  return numDiffPixels;
+}