playwright-cucumber-ts-steps 1.0.2 → 1.0.3

package/README.md

@@ -5,6 +5,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 [![Playwright](https://img.shields.io/badge/tested%20with-Playwright-blueviolet?style=flat-square&logo=playwright)](https://playwright.dev)
 [![TypeScript](https://img.shields.io/badge/written%20in-TypeScript-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
+[![GitHub stars](https://img.shields.io/github/stars/qaPaschalE/playwright-cucumber-ts-steps)](https://github.com/qaPaschalE/playwright-cucumber-ts-steps/stargazers)
 
 **The "Low-Code" BDD Framework for Playwright.**
 
@@ -193,6 +194,92 @@ Feature: Admin Panel
 
 ```
 
+### 4. Data Tables (Forms)
+
+Fill out entire forms in a single step using a Data Table. You can type, click, check, or assert visibility in one go.
+
+```gherkin
+Scenario: Registration
+  When I fill the following "Registration" form data:
+    | #first-name | John           |
+    | #last-name  | Doe            |
+    | #email      | john@test.com  |
+    | #newsletter | check          |
+    | #submit-btn | click          |
+    | .success    | assert:visible |
+```
+
+### 5. API Testing (Tables & Files)
+
+Validate your backend directly. You can send payloads via Tables or JSON Files.
+
+#### Option A: Data Table Payload
+
+```gherkin
+Scenario: Create User (Table)
+  When I make a POST request to "[https://reqres.in/api/users](https://reqres.in/api/users)" with data:
+    | name | Neo        |
+    | job  | The Chosen |
+  Then I expect the response status to be 201
+  And I expect the response property "name" to be "Neo"
+```
+
+#### Option B: File Payload
+
+```gherkin
+Scenario: Create User (File)
+  # Reads from 'data/user.json' in your project root
+  When I make a POST request to "/api/users" with payload from "data/user.json"
+  Then I expect the response status to be 201
+```
+
+### 6. Network Mocking
+
+Simulate backend responses to test UI behavior without relying on real APIs.
+
+```gherkin
+Scenario: Mocking User Profile
+  # Intercept calls to /api/user/1 and return fake data
+  Given I mock the API endpoint "*/**/api/user/1" with body '{"name": "Mocked User"}'
+
+  # When the UI calls the API, it gets our fake data
+  When I visit "/profile"
+  Then I expect "#username-display" to have text "Mocked User"
+
+```
+
+### 7. Database Testing (Adapter Pattern)
+
+You can validate database states by injecting your own DB driver into the runner.
+
+**1. In your `bdd.spec.ts`:**
+
+```typescript
+import { runTests } from "playwright-cucumber-ts-steps";
+import pg from "pg"; // Your driver (pg, mysql, mongo, etc)
+
+// wrapper function
+const queryDb = async (query: string) => {
+  const client = new pg.Client(process.env.DB_URL);
+  await client.connect();
+  const res = await client.query(query);
+  await client.end();
+  return res.rows; // Must return an array of objects
+};
+
+runTests("features/*.feature", { dbQuery: queryDb });
+```
+
+**2. In your `Feature file`:**
+
+```gherkin
+Scenario: Create User
+  When I run the database query "INSERT INTO users (name) VALUES ('Bob')"
+  Then I expect the database to return 1 record
+  And I expect the first database record to contain:
+    | name | Bob |
+```
+
 ---
 
 ## 📖 Step Glossary (Cheat Sheet)

package/dist/backend/actions/formTable.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const registry_1 = require("../../core/registry");
+const test_1 = require("@playwright/test");
+// CHANGE: Removed the ':' at the end of the string below
+(0, registry_1.Step)("I fill the following {string} form data", async (page, formName, tableData) => {
+    console.log(`📝 Processing Form: ${formName}`);
+    // The runner passes the table data as the last argument
+    // tableData = [ ['#username', 'tomsmith'], ['#password', '...'] ]
+    // Guard clause: Ensure tableData exists to prevent crashes if user forgets the table
+    if (!tableData || !Array.isArray(tableData)) {
+        throw new Error(`❌ The step "I fill the following '${formName}' form data" requires a Data Table below it.`);
+    }
+    for (const row of tableData) {
+        const selector = row[0];
+        const value = row[1];
+        if (value === "click") {
+            await page.click(selector);
+        }
+        else if (value === "check") {
+            await page.check(selector);
+        }
+        else if (value === "assert:visible") {
+            await (0, test_1.expect)(page.locator(selector)).toBeVisible();
+        }
+        else if (value.startsWith("assert:text:")) {
+            const text = value.replace("assert:text:", "");
+            await (0, test_1.expect)(page.locator(selector)).toHaveText(text);
+        }
+        else {
+            await page.fill(selector, value);
+        }
+    }
+});

package/dist/backend/actions/index.js

@@ -2,3 +2,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 require("./navigation");
 require("./interactions");
+require("./formTable");

package/dist/backend/api/index.js

@@ -2,3 +2,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 require("./requests");
 require("./assertions");
+require("./mock");

package/dist/backend/api/mock.js

@@ -0,0 +1,75 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const registry_1 = require("../../core/registry");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+// 1. Mock with Inline JSON
+// Usage: Given I mock the API endpoint "/api/users" with body '{"id": 1, "name": "Fake"}'
+(0, registry_1.Step)("I mock the API endpoint {string} with body {string}", async (page, urlPattern, jsonBody) => {
+    await page.route(urlPattern, async (route) => {
+        const json = JSON.parse(jsonBody);
+        await route.fulfill({
+            status: 200,
+            contentType: "application/json",
+            body: JSON.stringify(json),
+        });
+    });
+    console.log(`🎭 Mocked ${urlPattern} with inline JSON`);
+});
+// 2. Mock with File
+// Usage: Given I mock the API endpoint "/api/users" with response from "mocks/users.json"
+(0, registry_1.Step)("I mock the API endpoint {string} with response from {string}", async (page, urlPattern, filePath) => {
+    const fullPath = path.resolve(process.cwd(), filePath);
+    if (!fs.existsSync(fullPath)) {
+        throw new Error(`❌ Mock file not found at: ${fullPath}`);
+    }
+    const bodyContent = fs.readFileSync(fullPath, "utf8");
+    await page.route(urlPattern, async (route) => {
+        await route.fulfill({
+            status: 200,
+            contentType: "application/json",
+            body: bodyContent,
+        });
+    });
+    console.log(`🎭 Mocked ${urlPattern} with file: ${filePath}`);
+});
+// 3. Mock Status Code Only (Simulate Errors)
+// Usage: Given I mock the API endpoint "/api/broken" with status 500
+(0, registry_1.Step)("I mock the API endpoint {string} with status {int}", async (page, urlPattern, statusCode) => {
+    await page.route(urlPattern, async (route) => {
+        await route.fulfill({ status: statusCode });
+    });
+});

package/dist/backend/api/requests.js

@@ -1,7 +1,42 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 const registry_1 = require("../../core/registry");
 const state_1 = require("./state");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
 // GET Request
 (0, registry_1.Step)("I make a GET request to {string}", async (page, url) => {
     const response = await page.request.get(url);
@@ -13,11 +48,38 @@ const state_1 = require("./state");
     const response = await page.request.delete(url);
     state_1.apiState.setResponse(response);
 });
-// POST Request with JSON Body
-// Usage: I make a POST request to "/api/login" with body '{"user": "admin"}'
-(0, registry_1.Step)("I make a POST request to {string} with body {string}", async (page, url, bodyString) => {
+// 1. POST with Data Table
+// Usage:
+// When I make a POST request to "/api/users" with data:
+//   | name | John |
+//   | job  | Dev  |
+(0, registry_1.Step)("I make a POST request to {string} with data", async (page, url, tableData) => {
+    if (!tableData)
+        throw new Error("This step requires a Data Table.");
+    // Convert Table [ ["key", "val"], ["k2", "v2"] ] -> Object { key: "val", k2: "v2" }
+    const payload = tableData.reduce((acc, row) => {
+        acc[row[0]] = row[1];
+        return acc;
+    }, {});
+    const response = await page.request.post(url, {
+        data: payload,
+        headers: { "Content-Type": "application/json" },
+    });
+    state_1.apiState.setResponse(response);
+});
+// 2. POST with File Payload
+// Usage: When I make a POST request to "/api/users" with payload from "data/user.json"
+(0, registry_1.Step)("I make a POST request to {string} with payload from {string}", async (page, url, filePath) => {
+    // Resolve file path (relative to root)
+    const fullPath = path.resolve(process.cwd(), filePath);
+    if (!fs.existsSync(fullPath)) {
+        throw new Error(`❌ Payload file not found at: ${fullPath}`);
+    }
+    // Read and parse JSON
+    const fileContent = fs.readFileSync(fullPath, "utf8");
+    const payload = JSON.parse(fileContent);
     const response = await page.request.post(url, {
-        data: JSON.parse(bodyString), // Parse the string input into a JSON object
+        data: payload,
         headers: { "Content-Type": "application/json" },
     });
     state_1.apiState.setResponse(response);

package/dist/backend/db/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dbState = void 0;
+require("./steps");
+var state_1 = require("./state");
+Object.defineProperty(exports, "dbState", { enumerable: true, get: function () { return state_1.dbState; } });

package/dist/backend/db/state.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dbState = void 0;
+// Holds the user's custom DB function
+let dbAdapter = null;
+let lastResult = null;
+exports.dbState = {
+    // Runner calls this to register the user's function
+    setAdapter: (fn) => {
+        dbAdapter = fn;
+    },
+    // Step calls this to run a query
+    executeQuery: async (query) => {
+        if (!dbAdapter) {
+            throw new Error("❌ No Database Adapter found. Pass a 'dbQuery' function to runTests().");
+        }
+        const result = await dbAdapter(query);
+        lastResult = result;
+        console.log(`🗄️ DB Result:`, JSON.stringify(lastResult));
+        return result;
+    },
+    // Assertions use this to check results
+    getLastResult: () => lastResult,
+};

package/dist/backend/db/steps.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const registry_1 = require("../../core/registry");
+const state_1 = require("./state");
+const test_1 = require("@playwright/test");
+// 1. Run Query
+(0, registry_1.Step)("I run the database query {string}", async (page, query) => {
+    await state_1.dbState.executeQuery(query);
+});
+// 2. Count Check
+(0, registry_1.Step)("I expect the database to return {int} record(s)", async (page, count) => {
+    const result = state_1.dbState.getLastResult();
+    if (Array.isArray(result)) {
+        (0, test_1.expect)(result.length).toBe(count);
+    }
+    else {
+        throw new Error(`Expected array result but got: ${typeof result}`);
+    }
+});
+// 3. JSON/Table Check
+// CHANGE: Removed the colon ':' at the end of the string below
+(0, registry_1.Step)("I expect the first database record to contain", async (page, tableData) => {
+    const result = state_1.dbState.getLastResult();
+    // Guard Clauses
+    if (!Array.isArray(result) || result.length === 0) {
+        throw new Error("Database returned no records to check.");
+    }
+    if (!tableData) {
+        throw new Error("This step requires a Data Table.");
+    }
+    const firstRow = result[0]; // Check the first record found
+    // tableData is [ ["name", "Alice"], ["email", "alice@db.com"] ]
+    for (const row of tableData) {
+        const key = row[0];
+        const expectedValue = row[1];
+        // Check if the key exists in the DB result
+        if (!(key in firstRow)) {
+            throw new Error(`DB Record does not have column: ${key}`);
+        }
+        // Loose equality check (DB might return int, Gherkin sends string)
+        (0, test_1.expect)(String(firstRow[key])).toBe(expectedValue);
+    }
+});

package/dist/core/runner.js

@@ -45,19 +45,17 @@ require("../backend/assertions/index");
 require("../backend/elements/index");
 require("../backend/api/index");
 require("../backend/auth/index");
+const state_1 = require("../backend/db/state");
+require("../backend/db/index"); // Register DB steps
 /**
  * The main test runner. Parses feature files and executes them as Playwright tests.
- * * @param featureGlob - Glob pattern to find feature files (e.g., 'features/*.feature')
- * @param options - Configuration options for filtering tags
- * * @example
- * ```ts
- * // Run all features
- * runTests('features/*.feature');
- * * // Run only @smoke tests
- * runTests('features/*.feature', { tags: '@smoke' });
- * ```
+ * Includes support for Data Tables and Auto-Screenshots.
  */
 function runTests(featureGlob, options) {
+    // 1. Register DB Adapter if provided
+    if (options?.dbQuery) {
+        state_1.dbState.setAdapter(options.dbQuery);
+    }
     const files = (0, glob_1.globSync)(featureGlob);
     for (const file of files) {
         const content = fs.readFileSync(file, "utf8");
@@ -70,53 +68,70 @@ function runTests(featureGlob, options) {
             let match;
             while ((match = scenarioRegex.exec(content)) !== null) {
                 // 1. CAPTURE DATA IMMEDIATELY
-                // We calculate everything here so we don't rely on 'match' later
                 const foundTags = match[1] || "";
                 const scenarioName = match[2].trim();
                 const startIndex = match.index + match[0].length;
                 const nextMatchIndex = content.slice(startIndex).search(/Scenario:/);
                 const blockEnd = nextMatchIndex === -1 ? content.length : startIndex + nextMatchIndex;
-                // This variable 'scenarioBlock' is now safe to use inside the test
                 const scenarioBlock = content.slice(startIndex, blockEnd);
                 if (options?.tags && !foundTags.includes(options.tags)) {
                     continue;
                 }
                 (0, test_1.test)(scenarioName, async ({ page }, testInfo) => {
-                    // 1. Calculate the scenario block (Same as before)
                     const lines = scenarioBlock
                         .trim()
                         .split("\n")
                         .map((l) => l.trim())
                         .filter((l) => l);
-                    for (const stepText of lines) {
+                    // CHANGED: Use index loop to handle Data Tables (look-ahead)
+                    for (let i = 0; i < lines.length; i++) {
+                        const stepText = lines[i];
                         if (stepText.startsWith("#") ||
                             stepText.startsWith("@") ||
                             stepText === "")
                             continue;
-                        const cleanStep = stepText.replace(/^(Given|When|Then|And|But)\s+/i, "");
+                        // 2. CHECK FOR DATA TABLE
+                        // We look at the NEXT lines to see if they start with a pipe '|'
+                        const tableData = [];
+                        while (i + 1 < lines.length && lines[i + 1].startsWith("|")) {
+                            i++; // Move the index forward so we don't process this line as a step
+                            const row = lines[i]
+                                .split("|")
+                                .map((cell) => cell.trim())
+                                .filter((cell) => cell !== ""); // Remove empty start/end strings from split
+                            tableData.push(row);
+                        }
+                        // 3. CLEAN STEP TEXT
+                        // Remove "Given/When/..." and trailing colons ":"
+                        const cleanStep = stepText
+                            .replace(/^(Given|When|Then|And|But)\s+/i, "")
+                            .replace(/:$/, "")
+                            .trim();
                         const stepDef = findMatchingStep(cleanStep);
                         if (!stepDef) {
                             throw new Error(`❌ Undefined Step: "${cleanStep}"`);
                         }
-                        // 2. ERROR HANDLING WRAPPER
+                        // 4. EXECUTE WITH ERROR HANDLING
                         try {
-                            // Execute the step
-                            await stepDef.fn(page, ...stepDef.args);
+                            // Construct arguments: Regex args + Table data (if exists)
+                            const args = [...stepDef.args];
+                            if (tableData.length > 0) {
+                                args.push(tableData);
+                            }
+                            // Pass 'page' + args to the step function
+                            await stepDef.fn(page, ...args);
                         }
                         catch (error) {
-                            // 3. CAPTURE EVIDENCE ON FAILURE
                             console.error(`❌ Failed at step: "${stepText}"`);
                             // Take a screenshot immediately
                             const screenshot = await page.screenshot({
                                 fullPage: true,
                                 type: "png",
                             });
-                            // Attach it to the report (HTML/JSON/Slack will pick this up)
                             await testInfo.attach("failure-screenshot", {
                                 body: screenshot,
                                 contentType: "image/png",
                             });
-                            // Re-throw the error so the test is marked as Failed
                             throw error;
                         }
                     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "playwright-cucumber-ts-steps",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "private": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",