playwright-cucumber-ts-steps 1.0.0 → 1.0.1

package/lib/actions/inputSteps.js

@@ -0,0 +1,343 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.When_I_type_random = exports.When_I_type_stored = exports.When_I_type = void 0;
+exports.When_I_check = When_I_check;
+exports.When_I_uncheck = When_I_uncheck;
+exports.When_I_check_input = When_I_check_input;
+exports.When_I_uncheck_input = When_I_uncheck_input;
+exports.When_I_set_value = When_I_set_value;
+exports.When_I_clear = When_I_clear;
+exports.When_I_submit = When_I_submit;
+exports.When_I_select_option = When_I_select_option;
+exports.When_I_select_file = When_I_select_file;
+// e2e/step_definitions/common/actions/inputSteps.ts
+const cucumber_1 = require("@cucumber/cucumber");
+const fakerUtils_1 = require("../helpers/utils/fakerUtils"); // Assuming this path is correct
+const optionsUtils_1 = require("../helpers/utils/optionsUtils"); // Assuming this path is correct
+// =============================
+// WHEN I CHECK / UNCHECK
+// =============================
+/**
+ * Checks the previously selected element (e.g., a checkbox or radio button).
+ *
+ * ```gherkin
+ * When I check
+ * ```
+ *
+ * @example
+ * When I find element by label text "Remember me"
+ * And I check
+ *
+ * @remarks
+ * This step requires a preceding step that sets the {@link CustomWorld.element | current element}
+ * to a checkbox or radio button. It will mark the element as checked. Optional Playwright
+ * `CheckOptions` can be provided via a data table.
+ */
+async function When_I_check(...rest) {
+    if (!this.element)
+        throw new Error("No element selected to check.");
+    const maybeTable = rest[0];
+    const options = maybeTable?.rowsHash ? (0, optionsUtils_1.parseCheckOptions)(maybeTable) : {};
+    await this.element.check(options);
+    this.log?.("✅ Checked stored element.");
+}
+(0, cucumber_1.When)("I check", When_I_check);
+/**
+ * Unchecks the previously selected element (e.g., a checkbox).
+ *
+ * ```gherkin
+ * When I uncheck
+ * ```
+ *
+ * @example
+ * When I find element by label text "Agree to terms"
+ * And I uncheck
+ *
+ * @remarks
+ * This step requires a preceding step that sets the {@link CustomWorld.element | current element}
+ * to a checkbox. It will mark the element as unchecked. Optional Playwright
+ * `CheckOptions` can be provided via a data table.
+ */
+async function When_I_uncheck(...rest) {
+    if (!this.element)
+        throw new Error("No element selected to uncheck.");
+    const maybeTable = rest[0];
+    const options = maybeTable?.rowsHash ? (0, optionsUtils_1.parseCheckOptions)(maybeTable) : {};
+    await this.element.uncheck(options);
+    this.log?.("✅ Unchecked stored element.");
+}
+(0, cucumber_1.When)("I uncheck", When_I_uncheck);
+/**
+ * Checks a specific input element, requiring a preceding step to select it.
+ *
+ * ```gherkin
+ * When I check input
+ * ```
+ *
+ * @example
+ * When I find element by selector "input#myCheckbox"
+ * And I check input
+ *
+ * @remarks
+ * This is an alias for "I check". It requires a preceding step that sets the
+ * {@link CustomWorld.element | current element} to an input element (like a checkbox or radio).
+ * Optional Playwright `CheckOptions` can be provided via a data table.
+ */
+async function When_I_check_input(...rest) {
+    if (!this.element)
+        throw new Error("No input selected to check.");
+    const maybeTable = rest[0];
+    const options = maybeTable?.rowsHash ? (0, optionsUtils_1.parseCheckOptions)(maybeTable) : {};
+    await this.element.check(options);
+    this.log?.("✅ Checked stored input.");
+}
+(0, cucumber_1.When)("I check input", When_I_check_input);
+/**
+ * Unchecks a specific input element, requiring a preceding step to select it.
+ *
+ * ```gherkin
+ * When I uncheck input
+ * ```
+ *
+ * @example
+ * When I find element by selector "input#newsletter"
+ * And I uncheck input
+ *
+ * @remarks
+ * This is an alias for "I uncheck". It requires a preceding step that sets the
+ * {@link CustomWorld.element | current element} to an input element (like a checkbox).
+ * Optional Playwright `CheckOptions` can be provided via a data table.
+ */
+async function When_I_uncheck_input(...rest) {
+    if (!this.element)
+        throw new Error("No input selected to uncheck.");
+    const maybeTable = rest[0];
+    const options = maybeTable?.rowsHash ? (0, optionsUtils_1.parseCheckOptions)(maybeTable) : {};
+    await this.element.uncheck(options);
+    this.log?.("✅ Unchecked stored input.");
+}
+(0, cucumber_1.When)("I uncheck input", When_I_uncheck_input);
+// =============================
+// WHEN I TYPE / SET VALUE
+// =============================
+/**
+ * Shared implementation for typing steps.
+ * @internal
+ */
+const typeStepImplementation = async function (textOrAlias, ...rest) {
+    if (!this.element)
+        throw new Error("No element selected to type into.");
+    const maybeTable = rest[0];
+    const options = maybeTable?.rowsHash ? (0, optionsUtils_1.parseFillOptions)(maybeTable) : {};
+    const text = textOrAlias.startsWith("@")
+        ? (this.data[textOrAlias.slice(1)] ??
+            (() => {
+                throw new Error(`No value found for alias "${textOrAlias}".`);
+            })())
+        : (0, fakerUtils_1.evaluateFaker)(textOrAlias); // Evaluate faker directly here if it's not an alias
+    // Playwright's fill clears the field by default, but explicitly clearing can be safer
+    // await this.element.fill(""); // This explicit clear might not be necessary depending on Playwright version/behavior
+    await this.element.fill(text, options);
+    this.data.lastTyped = text; // Store the actual text typed for potential later use
+    this.log?.(`⌨️ Typed "${text}" into selected element.`);
+};
+/**
+ * Types the given text into the previously selected element.
+ *
+ * ```gherkin
+ * When I type {string}
+ * ```
+ *
+ * @example
+ * When I find element by selector "input[name='email']"
+ * And I type "user@example.com"
+ *
+ * @remarks
+ * This step requires a preceding step that sets the {@link CustomWorld.element | current element}
+ * to an input field (or any element that supports `fill`). The provided text can be a literal
+ * string or a faker expression (e.g., `{{internet.email}}`).
+ * Optional Playwright `FillOptions` can be provided via a data table.
+ */
+exports.When_I_type = typeStepImplementation;
+(0, cucumber_1.When)("I type {string}", exports.When_I_type);
+/**
+ * Types the value stored in an alias into the previously selected element.
+ *
+ * ```gherkin
+ * When I type stored {string}
+ * ```
+ *
+ * @example
+ * Given I store "my.user@example.com" as "userEmail"
+ * When I find element by selector "input[name='email']"
+ * And I type stored "userEmail"
+ *
+ * @remarks
+ * This step requires a preceding step that sets the {@link CustomWorld.element | current element}
+ * to an input field. The `string` argument must be an alias (e.g., `userEmail`).
+ * The value associated with this alias in `this.data` will be typed into the element.
+ * Optional Playwright `FillOptions` can be provided via a data table.
+ */
+exports.When_I_type_stored = typeStepImplementation;
+(0, cucumber_1.When)("I type stored {string}", exports.When_I_type_stored);
+/**
+ * Types a randomly generated value (using Faker.js) into the previously selected element.
+ *
+ * ```gherkin
+ * When I type random {string}
+ * ```
+ *
+ * @example
+ * When I find element by selector "input[name='username']"
+ * And I type random "internet.userName"
+ *
+ * @remarks
+ * This step requires a preceding step that sets the {@link CustomWorld.element | current element}
+ * to an input field. The `string` argument should be a Faker.js path (e.g., `internet.email`,
+ * `person.firstName`). A random value generated by Faker will be typed into the element.
+ * Optional Playwright `FillOptions` can be provided via a data table.
+ */
+exports.When_I_type_random = typeStepImplementation;
+(0, cucumber_1.When)("I type random {string}", exports.When_I_type_random);
+/**
+ * Sets the value of the previously selected element.
+ *
+ * ```gherkin
+ * When I set value {string}
+ * ```
+ *
+ * @example
+ * When I find element by selector "input[name='password']"
+ * And I set value "@userPassword"
+ *
+ * @remarks
+ * This step requires a preceding step that sets the {@link CustomWorld.element | current element}
+ * to an input field (or any element that supports `fill`). The provided `valueOrAlias` can be
+ * a literal string, an alias (prefixed with `@`), or a Faker expression. This will directly
+ * set the input's value, which is generally faster than typing for non-interactive scenarios.
+ * Optional Playwright `FillOptions` can be provided via a data table.
+ */
+async function When_I_set_value(valueOrAlias, ...rest) {
+    if (!this.element)
+        throw new Error("No element selected to set value.");
+    const maybeTable = rest[0];
+    const options = maybeTable?.rowsHash ? (0, optionsUtils_1.parseFillOptions)(maybeTable) : {};
+    const value = valueOrAlias.startsWith("@")
+        ? (this.data[valueOrAlias.slice(1)] ??
+            (() => {
+                throw new Error(`No value found for alias "${valueOrAlias}".`);
+            })())
+        : (0, fakerUtils_1.evaluateFaker)(valueOrAlias); // Evaluate faker directly here if it's not an alias
+    await this.element.fill(value, options);
+    this.data.lastValueSet = value; // Store the actual value set for potential later use
+    this.log?.(`📝 Set value of selected element to "${value}".`);
+}
+(0, cucumber_1.When)("I set value {string}", When_I_set_value);
+/**
+ * Clears the value of the previously selected element.
+ *
+ * ```gherkin
+ * When I clear
+ * ```
+ *
+ * @example
+ * When I find element by selector "input[name='search']"
+ * And I clear
+ *
+ * @remarks
+ * This step requires a preceding step that sets the {@link CustomWorld.element | current element}
+ * to an input field (or any element that supports `fill`). It effectively empties the input field.
+ */
+async function When_I_clear() {
+    if (!this.element)
+        throw new Error("No element selected to clear.");
+    await this.element.fill("");
+    this.log?.("🧼 Cleared value of selected element.");
+}
+(0, cucumber_1.When)("I clear", When_I_clear);
+/**
+ * Submits the form associated with the previously selected element, or the first form on the page.
+ *
+ * ```gherkin
+ * When I submit
+ * ```
+ *
+ * @example
+ * When I find element by selector "form#loginForm"
+ * And I submit
+ * # OR (submits the first form found if no element is selected)
+ * When I go to "/login"
+ * And I submit
+ *
+ * @remarks
+ * This step will find a form to submit. If {@link CustomWorld.element | this.element}
+ * is a form or an element within a form, that form will be submitted. Otherwise, it will
+ * attempt to submit the first `<form>` element found on the page.
+ * It uses a direct DOM `submit()` call, which bypasses Playwright's default event handling
+ * and can be useful for testing native form submission behavior.
+ */
+async function When_I_submit() {
+    // Use the current element if it's a form or within a form, otherwise default to the first form on the page.
+    const formLocator = this.element
+        ? this.element.locator("xpath=ancestor-or-self::form")
+        : this.page.locator("form").first();
+    if (!(await formLocator.isVisible())) {
+        throw new Error("No visible form found to submit. Ensure an element within a form is selected, or a form exists on the page.");
+    }
+    await formLocator.evaluate((f) => f.submit());
+    this.log?.("📨 Submitted form.");
+}
+(0, cucumber_1.When)("I submit", When_I_submit);
+/**
+ * Selects an option by its visible text label in a `<select>` element.
+ *
+ * ```gherkin
+ * When I select option {string}
+ * ```
+ *
+ * @example
+ * When I find element by selector "select[name='role']"
+ * And I select option "Administrator"
+ *
+ * @remarks
+ * This step requires a preceding step that sets the {@link CustomWorld.element | current element}
+ * to a `<select>` HTML element. It will then select the option whose visible text matches
+ * the provided `option` string.
+ * Optional Playwright `SelectOptionOptions` can be provided via a data table.
+ */
+async function When_I_select_option(option, ...rest) {
+    if (!this.element)
+        throw new Error("No select element stored to select an option.");
+    const maybeTable = rest[0];
+    const options = maybeTable?.rowsHash ? (0, optionsUtils_1.parseSelectOptions)(maybeTable) : {};
+    await this.element.selectOption({ label: option }, options);
+    this.log?.(`🔽 Selected option "${option}".`);
+}
+(0, cucumber_1.When)("I select option {string}", When_I_select_option);
+/**
+ * Sets the file input of the previously selected element to the specified file path.
+ *
+ * ```gherkin
+ * When I select file {string}
+ * ```
+ *
+ * @example
+ * When I find element by selector "input[type='file']"
+ * And I select file "path/to/my/document.pdf"
+ *
+ * @remarks
+ * This step requires a preceding step that sets the {@link CustomWorld.element | current element}
+ * to an `input` element of `type="file"`. The `filePath` should be relative to your project's
+ * root or an absolute path. Playwright will automatically handle making the file available
+ * for upload.
+ * Optional Playwright `SetInputFilesOptions` can be provided via a data table.
+ */
+async function When_I_select_file(filePath, ...rest) {
+    if (!this.element)
+        throw new Error("No file input selected to set a file.");
+    const maybeTable = rest[0];
+    const options = maybeTable?.rowsHash ? (0, optionsUtils_1.parseSelectOptions)(maybeTable) : {}; // Note: parseSelectOptions is used here, assuming it returns `SetInputFilesOptions` compatible object or is generic enough. If not, a new parser for SetInputFilesOptions would be ideal.
+    await this.element.setInputFiles(filePath, options);
+    this.log?.(`📁 Set input file to "${filePath}".`);
+}
+(0, cucumber_1.When)("I select file {string}", When_I_select_file);

package/lib/actions/interceptionSteps.d.ts

@@ -0,0 +1,169 @@
+import { DataTable } from "@cucumber/cucumber";
+import { CustomWorld } from "../helpers/world";
+/**
+ * Intercepts a network request to the given URL and stubs its response body with the provided JSON.
+ * This step should be used *before* the action that triggers the request (e.g., navigating to a page
+ * or clicking a button that makes an API call).
+ *
+ * ```gherkin
+ * When I intercept URL {string} and stub body:
+ * """
+ * { "foo": "bar" }
+ * """
+ * ```
+ *
+ * @param url - The URL to intercept. This can be a full URL, a URL glob, or a regular expression string.
+ * @param body - A DocString containing the JSON string to use as the response body.
+ *
+ * @example
+ * Scenario: Stubbing an API response
+ * When I intercept URL "https://api.example.com/data" and stub body:
+ * """
+ * { "status": "success", "items": ["item1", "item2"] }
+ * """
+ * And I go to "/dashboard"
+ * Then I should see text "item1"
+ *
+ * @remarks
+ * The intercepted request will respond with a `200 OK` status and a `Content-Type` of `application/json`.
+ * The `body` provided must be valid JSON. Playwright's `page.route()` is used internally.
+ * Make sure this step executes *before* the network request is initiated.
+ * @category Network Interception Steps
+ */
+export declare function When_I_intercept_URL_and_stub_body(this: CustomWorld, url: string, body: string): Promise<void>;
+/**
+ * Intercepts a network request to the given URL and allows it to continue unmodified.
+ * This can be useful for ensuring that specific requests are *not* blocked or for logging
+ * requests without altering their behavior.
+ *
+ * ```gherkin
+ * When I intercept URL {string}
+ * ```
+ *
+ * @param url - The URL to intercept. This can be a full URL, a URL glob, or a regular expression string.
+ *
+ * @example
+ * Scenario: Allowing a specific request to pass through
+ * When I intercept URL "https://analytics.example.com/*"
+ * And I go to "/dashboard"
+ * Then the page title should be "Dashboard"
+ *
+ * @remarks
+ * This step uses Playwright's `page.route()` with `route.continue()`. No changes are made
+ * to the request or its response. This is essentially a "monitor" step.
+ * @category Network Interception Steps
+ */
+export declare function When_I_intercept_URL(this: CustomWorld, url: string): Promise<void>;
+/**
+ * Intercepts a network request to the given URL and stubs its response body with a raw string.
+ * This is useful for returning non-JSON content or simple string responses.
+ *
+ * ```gherkin
+ * When I intercept URL {string} and stub body {string}
+ * ```
+ *
+ * @param url - The URL to intercept. This can be a full URL, a URL glob, or a regular expression string.
+ * @param body - The raw string content to use as the response body.
+ *
+ * @example
+ * Scenario: Stubbing a simple text response
+ * When I intercept URL "https://api.example.com/status" and stub body "OK"
+ * And I visit page with JS that fetches "/status"
+ * Then I should see text "OK"
+ *
+ * @remarks
+ * The intercepted request will respond with a `200 OK` status and a `Content-Type` of `application/json`
+ * by default (though the `body` is a raw string). If a different `contentType` is needed, consider
+ * using the `I intercept URL {string} and stub response with:` step if available, or extending this step.
+ * @category Network Interception Steps
+ */
+export declare function When_I_intercept_URL_and_stub_raw_body(this: CustomWorld, url: string, body: string): Promise<void>;
+/**
+ * Makes a GET request to the given URL and stores the response details (status and body)
+ * in the test context.
+ *
+ * ```gherkin
+ * When I make request to {string}
+ * ```
+ *
+ * @param url - The URL to which the GET request will be made.
+ *
+ * @example
+ * Scenario: Verify API endpoint status
+ * When I make request to "https://api.example.com/health"
+ * Then the last response status should be 200
+ * And the last response body should contain "healthy"
+ *
+ * @remarks
+ * The response object (including status and body) is stored in
+ * {@link CustomWorld.data.lastResponse | this.data.lastResponse}. Subsequent assertion steps
+ * can then access this data.
+ * @category API Request Steps
+ */
+export declare function When_I_make_GET_request_to(this: CustomWorld, url: string): Promise<void>;
+/**
+ * Makes a POST request to the given URL with the provided JSON body and stores the response details.
+ *
+ * ```gherkin
+ * When I make a POST request to {string} with JSON body:
+ * """
+ * { "username": "user", "password": "pass" }
+ * """
+ * ```
+ *
+ * @param url - The URL to which the POST request will be made.
+ * @param docString - A Cucumber DocString containing the JSON payload for the request body.
+ *
+ * @example
+ * Scenario: Login via API
+ * When I make a POST request to "https://api.example.com/login" with JSON body:
+ * """
+ * { "email": "test@example.com", "password": "password123" }
+ * """
+ * Then the last response status should be 200
+ * And the last response body should contain "token"
+ *
+ * @remarks
+ * The `docString` must contain valid JSON. The request will have a `Content-Type` of `application/json`.
+ * The response object (including status and body) is stored in
+ * {@link CustomWorld.data.lastResponse | this.data.lastResponse}.
+ * @category API Request Steps
+ */
+export declare function When_I_make_POST_request_with_JSON_body(this: CustomWorld, url: string, docString: string): Promise<void>;
+/**
+ * Makes a generic HTTP request with a specified method and optional headers/body from a data table.
+ *
+ * ```gherkin
+ * When I make a "{word}" request to {string}
+ * | header | value |
+ * | Content-Type | application/json |
+ * | ...    | ...   |
+ * ```
+ *
+ * @param method - The HTTP method (e.g., "GET", "POST", "PUT", "DELETE").
+ * @param url - The URL for the request.
+ * @param table - (Optional) A Cucumber DataTable with `header` and `value` columns for headers,
+ * and a `body` row for the request body.
+ *
+ * @example
+ * Scenario: Make a PUT request with custom headers
+ * When I make a "PUT" request to "https://api.example.com/resource/123"
+ * | Content-Type | application/json |
+ * | Authorization | Bearer my-token |
+ * | body | { "status": "updated" } |
+ * Then the last response status should be 200
+ *
+ * @remarks
+ * This step constructs a `fetch` request using the provided method, URL, and options from the
+ * data table. The `body` provided in the data table (if any) will be automatically
+ * JSON.parsed and then JSON.stringified. The entire `Response` object from `fetch` is
+ * stored in {@link CustomWorld.data.lastResponse | this.data.lastResponse}.
+ *
+ * **Note on `fetch`:** This step uses the browser's `fetch` API, which runs in the browser context.
+ * If you need to make Node.js-based requests (e.g., for backend APIs that are not accessible from the browser),
+ * you might prefer `page.request` (as used in `When_I_make_GET_request_to` or `When_I_make_POST_request_with_JSON_body`).
+ * This step stores the raw `Response` object, so you might need to call `.json()` or `.text()`
+ * on `this.data.lastResponse` in subsequent steps if you need to assert on its content.
+ * @category API Request Steps
+ */
+export declare function When_I_make_HTTP_request_with_options(this: CustomWorld, method: string, url: string, table?: DataTable): Promise<void>;