playwright-step-decorator-plugin 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Emanuele Minotto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,235 @@
+# playwright-step-decorator-plugin
+
+A TypeScript `@step` decorator that wraps Playwright Page Object Model methods in
+[`test.step()`](https://playwright.dev/docs/api/class-test#test-step) and automatically
+generates human-readable step titles — plus an ESLint rule to enforce consistent usage
+across your test suite.
+
+## Installation
+
+```bash
+npm install playwright-step-decorator-plugin
+```
+
+Peer dependencies:
+
+```bash
+npm install --save-dev @playwright/test
+# optional — only needed for the ESLint rule
+npm install --save-dev eslint
+```
+
+## Usage
+
+### `@step` decorator
+
+The decorator wraps any async Page Object Model method in `test.step()`, generating a
+descriptive title from the class name, method name, and the **actual runtime argument
+values** — all without any manual naming.
+
+```ts
+import { step } from 'playwright-step-decorator-plugin';
+
+class LoginPage {
+  constructor(private readonly page: Page) {}
+
+  // Bare usage — fully automatic title
+  @step
+  async login(username: string, password: string) {
+    await this.page.fill('#username', username);
+    await this.page.fill('#password', password);
+    await this.page.click('#submit');
+  }
+  // → 'Login page: login using username "admin@acme.com" and password "s3cr3t"'
+
+  // Custom step name — params are still appended
+  @step('Sign in to the application')
+  async signIn(username: string) {
+    // ...
+  }
+  // → 'Sign in to the application using username "admin@acme.com"'
+
+  // Options only — humanizer still runs, but step is boxed
+  @step({ box: true, timeout: 10_000 })
+  async fillForm(firstName: string, lastName: string) {
+    // ...
+  }
+  // → 'Login page: fill form using first name "Ada" and last name "Lovelace"'
+
+  // Custom name + options
+  @step('Reset password', { box: true })
+  async resetPassword(email: string) {
+    // ...
+  }
+  // → 'Reset password using email "ada@example.com"'
+
+  // Disable the humanizer entirely — raw "ClassName.methodName", no params
+  @step({ noHumanizer: true })
+  async internalReset() {
+    // ...
+  }
+  // → 'LoginPage.internalReset'
+}
+```
+
+### `StepOptions`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `box` | `boolean` | `false` | Box the step so errors point to the call site ([docs](https://playwright.dev/docs/api/class-test#test-step)) |
+| `timeout` | `number` | — | Maximum step duration in milliseconds |
+| `noHumanizer` | `boolean` | `false` | Skip humanization; use `ClassName.methodName` as-is with no params |
+
+### How the humanizer builds step titles
+
+The step title is assembled at **call time** using real argument values:
+
+```
+"<Humanized class name>: <humanized method name> using <top-3 params>"
+```
+
+Parameter rules:
+- At most **3 parameters** are shown; the rest are collapsed into `"and N more options"`.
+- Parameters are ranked by value type: strings/numbers (highest) → arrays/objects → booleans → null/undefined (lowest).
+- Each value is rendered concisely: strings are quoted, booleans become plain names or `"not <name>"`, arrays show their items (up to 3), and large objects are summarised as `"with N fields"`.
+
+```ts
+// searchProducts("laptop", {brand:"apple"}, "price", 1, 20)
+// → 'Search page: search products using query "laptop", sort by "price" and page 1 and 2 more options'
+
+// bulkAddItems([1,2,3], null, {giftWrap:true, note:"birthday"})
+// → 'Cart page: bulk add items using item ids [1, 2, 3], coupon: not provided and options {giftWrap: true, note: "birthday"}'
+```
+
+---
+
+## Why the humanizer matters for debugging
+
+When a Playwright test fails, you open the HTML report or the trace viewer and look for
+the step that broke. Without explicit names, steps show the raw method call —
+`LoginPage.fillCredentials` — which is opaque to everyone except the developer who wrote
+it. With the humanizer you get **"Login page: fill credentials using username
+"admin@acme.com" and password "s3cr3t""** — a sentence that tells you exactly which page,
+which action, and which data were involved, before you even open the trace.
+
+**Concrete benefits:**
+
+1. **Instant triage.** The failing step title reads like a sentence.
+   Non-technical stakeholders in a report can understand at a glance what went wrong
+   without decoding PascalCase identifiers.
+
+2. **Parameters in the title.** The humanizer captures runtime values so the step title
+   contains the actual data (`userId "u_42"`, `role "admin"`) rather than placeholder
+   names. You know exactly which input triggered the failure.
+
+3. **Consistency without discipline.** Manual naming drifts: one developer writes
+   `"Login as user"`, another writes `"loginPage.login"`. The decorator produces a
+   uniform format across the entire codebase automatically.
+
+4. **Better trace viewer UX.** Playwright's trace viewer nests steps visually.
+   Human-readable titles make the step tree self-documenting, reducing the time spent
+   hunting for the right frame.
+
+5. **Regression signal.** When a humanized step title changes between runs (because a
+   parameter changed), it stands out immediately in diff-based report tools.
+
+---
+
+## ESLint rule — `require-step-decorator`
+
+Enforce that every public method on a POM class is decorated with `@step`.
+
+### Setup (ESLint flat config)
+
+```js
+// eslint.config.js
+import { eslintPlugin } from 'playwright-step-decorator-plugin';
+
+export default [
+  eslintPlugin.configs.recommended,
+  // or configure manually:
+  {
+    plugins: { 'playwright-step-decorator': eslintPlugin },
+    rules: {
+      'playwright-step-decorator/require-step-decorator': 'error',
+    },
+  },
+];
+```
+
+### Import (ESLint plugin only)
+
+```js
+import eslintPlugin from 'playwright-step-decorator-plugin/eslint-plugin';
+```
+
+### Rule options
+
+```js
+{
+  'playwright-step-decorator/require-step-decorator': ['error', {
+    // Regex to identify POM classes by name.
+    // Default: "(Page|Component|Widget|Fragment)$"
+    pomPattern: '(Page|Component|Widget|Fragment)$',
+
+    // Name of the decorator to look for.
+    // Default: "step"
+    decoratorName: 'step',
+  }]
+}
+```
+
+### What the rule checks
+
+- Matches classes whose name (or whose parent class name) satisfies `pomPattern`.
+- Reports any **public, non-constructor, non-accessor** method that is missing the
+  `@step` decorator.
+- Private methods (`private` modifier or `#name`), getters, setters, and constructors
+  are excluded.
+
+```ts
+// ✅ OK
+class LoginPage {
+  @step
+  async login(username: string) { ... }
+}
+
+// ❌ Error: Method "login" in POM class "LoginPage" must be decorated with @step.
+class LoginPage {
+  async login(username: string) { ... }
+}
+```
+
+---
+
+## Separate entry points
+
+```ts
+// Full package (decorator + ESLint plugin)
+import { step, eslintPlugin } from 'playwright-step-decorator-plugin';
+
+// Decorator only
+import { step } from 'playwright-step-decorator-plugin/decorator';
+
+// ESLint plugin only
+import eslintPlugin from 'playwright-step-decorator-plugin/eslint-plugin';
+```
+
+---
+
+## Requirements
+
+- TypeScript 5.0+ (Stage 3 decorators — no `experimentalDecorators` flag needed)
+- `@playwright/test` ≥ 1.40
+- Node.js ≥ 18
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). We follow
+[Conventional Commits](https://www.conventionalcommits.org/).
+
+## License
+
+[MIT](LICENSE)

package/dist/decorator/index.d.mts

@@ -0,0 +1,67 @@
+interface StepOptions {
+    /** Box the step in the report so errors point to the call site. Defaults to false. */
+    box?: boolean;
+    /** Maximum time in milliseconds for the step to finish. */
+    timeout?: number;
+    /**
+     * Skip humanization — use the raw "ClassName.methodName" format as the step title,
+     * with no parameter rendering. Defaults to false.
+     */
+    noHumanizer?: boolean;
+}
+
+type AnyMethod = (this: any, ...args: unknown[]) => unknown;
+type StepDecorator = (target: AnyMethod, context: ClassMethodDecoratorContext) => AnyMethod;
+/**
+ * Decorator that wraps a Page Object Model method in a `test.step()` call,
+ * automatically generating a human-readable step title.
+ *
+ * @example Bare usage — humanizes class + method name + runtime params
+ * ```ts
+ * class LoginPage {
+ *   @step
+ *   async login(username: string, password: string) { ... }
+ * }
+ * // → 'Login page: login using username "admin" and password "secret"'
+ * ```
+ *
+ * @example Custom step name — params are still appended
+ * ```ts
+ * class CheckoutPage {
+ *   @step('Proceed to payment')
+ *   async submitOrder(orderId: string) { ... }
+ * }
+ * // → 'Proceed to payment using order id "ord_99"'
+ * ```
+ *
+ * @example Options only — humanizes with box + timeout
+ * ```ts
+ * class ProfilePage {
+ *   @step({ box: true, timeout: 10_000 })
+ *   async updateAvatar(file: string) { ... }
+ * }
+ * ```
+ *
+ * @example Custom name + options
+ * ```ts
+ * class CartPage {
+ *   @step('Add item to cart', { box: true })
+ *   async addItem(product: Product) { ... }
+ * }
+ * ```
+ *
+ * @example Disable humanizer — raw "ClassName.methodName", no params
+ * ```ts
+ * class AdminPage {
+ *   @step({ noHumanizer: true })
+ *   async deleteUser(userId: string) { ... }
+ * }
+ * // → 'AdminPage.deleteUser'
+ * ```
+ */
+declare function step(target: AnyMethod, context: ClassMethodDecoratorContext): AnyMethod;
+declare function step(name: string, options?: StepOptions): StepDecorator;
+declare function step(options: StepOptions): StepDecorator;
+declare function step(): StepDecorator;
+
+export { type StepOptions, step };

package/dist/decorator/index.d.ts

@@ -0,0 +1,67 @@
+interface StepOptions {
+    /** Box the step in the report so errors point to the call site. Defaults to false. */
+    box?: boolean;
+    /** Maximum time in milliseconds for the step to finish. */
+    timeout?: number;
+    /**
+     * Skip humanization — use the raw "ClassName.methodName" format as the step title,
+     * with no parameter rendering. Defaults to false.
+     */
+    noHumanizer?: boolean;
+}
+
+type AnyMethod = (this: any, ...args: unknown[]) => unknown;
+type StepDecorator = (target: AnyMethod, context: ClassMethodDecoratorContext) => AnyMethod;
+/**
+ * Decorator that wraps a Page Object Model method in a `test.step()` call,
+ * automatically generating a human-readable step title.
+ *
+ * @example Bare usage — humanizes class + method name + runtime params
+ * ```ts
+ * class LoginPage {
+ *   @step
+ *   async login(username: string, password: string) { ... }
+ * }
+ * // → 'Login page: login using username "admin" and password "secret"'
+ * ```
+ *
+ * @example Custom step name — params are still appended
+ * ```ts
+ * class CheckoutPage {
+ *   @step('Proceed to payment')
+ *   async submitOrder(orderId: string) { ... }
+ * }
+ * // → 'Proceed to payment using order id "ord_99"'
+ * ```
+ *
+ * @example Options only — humanizes with box + timeout
+ * ```ts
+ * class ProfilePage {
+ *   @step({ box: true, timeout: 10_000 })
+ *   async updateAvatar(file: string) { ... }
+ * }
+ * ```
+ *
+ * @example Custom name + options
+ * ```ts
+ * class CartPage {
+ *   @step('Add item to cart', { box: true })
+ *   async addItem(product: Product) { ... }
+ * }
+ * ```
+ *
+ * @example Disable humanizer — raw "ClassName.methodName", no params
+ * ```ts
+ * class AdminPage {
+ *   @step({ noHumanizer: true })
+ *   async deleteUser(userId: string) { ... }
+ * }
+ * // → 'AdminPage.deleteUser'
+ * ```
+ */
+declare function step(target: AnyMethod, context: ClassMethodDecoratorContext): AnyMethod;
+declare function step(name: string, options?: StepOptions): StepDecorator;
+declare function step(options: StepOptions): StepDecorator;
+declare function step(): StepDecorator;
+
+export { type StepOptions, step };

package/dist/decorator/index.js

@@ -0,0 +1,156 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/decorator/index.ts
+var decorator_exports = {};
+__export(decorator_exports, {
+  step: () => step
+});
+module.exports = __toCommonJS(decorator_exports);
+var import_test = require("@playwright/test");
+
+// src/decorator/humanizer.ts
+var import_string = require("@alduino/humanizer/string");
+function scoreParam(value) {
+  if (value === null || value === void 0) return 0;
+  if (typeof value === "boolean") return 1;
+  if (Array.isArray(value) || typeof value === "object") return 2;
+  return 3;
+}
+function renderParamValue(name, value) {
+  const humanName = (0, import_string.humanize)(name).toLowerCase();
+  if (value === null || value === void 0) {
+    return `${humanName}: not provided`;
+  }
+  if (typeof value === "boolean") {
+    return value ? humanName : `not ${humanName}`;
+  }
+  if (typeof value === "string") {
+    return value === "" ? `${humanName}: empty` : `${humanName} "${value}"`;
+  }
+  if (typeof value === "number") {
+    return `${humanName} ${value}`;
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) return `no ${humanName}`;
+    if (value.length <= 3) return `${humanName} [${value.map((v) => JSON.stringify(v)).join(", ")}]`;
+    return `${value.length} ${humanName}`;
+  }
+  const keys = Object.keys(value);
+  if (keys.length === 0) return `empty ${humanName}`;
+  if (keys.length <= 2) {
+    const entries = keys.map((k) => `${k}: ${JSON.stringify(value[k])}`).join(", ");
+    return `${humanName} {${entries}}`;
+  }
+  return `${humanName} with ${keys.length} fields`;
+}
+function joinParts(parts) {
+  if (parts.length === 0) return "";
+  if (parts.length === 1) return parts[0];
+  return `${parts.slice(0, -1).join(", ")} and ${parts[parts.length - 1]}`;
+}
+function buildParamString(params) {
+  if (params.length === 0) return "";
+  let top;
+  let remaining = 0;
+  if (params.length <= 3) {
+    top = params;
+  } else {
+    const scored = params.map((p, originalIndex) => ({ ...p, score: scoreParam(p.value), originalIndex }));
+    scored.sort((a, b) => {
+      const scoreDiff = b.score - a.score;
+      return scoreDiff !== 0 ? scoreDiff : a.originalIndex - b.originalIndex;
+    });
+    top = scored.slice(0, 3);
+    remaining = params.length - 3;
+  }
+  const parts = top.map((p) => renderParamValue(p.name, p.value));
+  const joined = joinParts(parts);
+  if (remaining > 0) {
+    return `${joined} and ${remaining} more option${remaining === 1 ? "" : "s"}`;
+  }
+  return joined;
+}
+function buildHumanStepTitle(className, methodName, params) {
+  const humanClass = (0, import_string.humanize)(className);
+  const humanMethod = (0, import_string.humanize)(methodName).toLowerCase();
+  const base = `${humanClass}: ${humanMethod}`;
+  const paramStr = buildParamString(params);
+  return paramStr ? `${base} using ${paramStr}` : base;
+}
+function buildCustomStepTitle(customName, params) {
+  const paramStr = buildParamString(params);
+  return paramStr ? `${customName} using ${paramStr}` : customName;
+}
+function extractParamNames(fn) {
+  const fnStr = fn.toString();
+  const match = fnStr.match(/\(([^)]*)\)/);
+  if (!match || !match[1].trim()) return [];
+  return match[1].split(",").map((param) => {
+    const name = param.trim().replace(/^\.\.\./, "").split(/[\s=]/)[0].trim();
+    return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ? name : null;
+  }).filter((name) => name !== null && name.length > 0);
+}
+
+// src/decorator/index.ts
+function isDecoratorContext(v) {
+  return typeof v === "object" && v !== null && v.kind === "method";
+}
+function isStepOptions(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const allowedKeys = /* @__PURE__ */ new Set(["box", "timeout", "noHumanizer"]);
+  return Object.keys(v).every((k) => allowedKeys.has(k));
+}
+function applyStep(target, context, customName, opts) {
+  const paramNames = extractParamNames(target);
+  return function(...args) {
+    let stepTitle;
+    if (opts.noHumanizer) {
+      stepTitle = `${this.constructor.name}.${String(context.name)}`;
+    } else {
+      const params = paramNames.map((name, i) => ({ name, value: args[i] }));
+      if (customName !== void 0) {
+        stepTitle = buildCustomStepTitle(customName, params);
+      } else {
+        stepTitle = buildHumanStepTitle(
+          this.constructor.name,
+          String(context.name),
+          params
+        );
+      }
+    }
+    return import_test.test.step(stepTitle, () => target.call(this, ...args), {
+      box: opts.box,
+      timeout: opts.timeout
+    });
+  };
+}
+function step(nameOrOptionsOrTarget, contextOrOptions) {
+  if (typeof nameOrOptionsOrTarget === "function" && isDecoratorContext(contextOrOptions)) {
+    return applyStep(nameOrOptionsOrTarget, contextOrOptions, void 0, {});
+  }
+  const customName = typeof nameOrOptionsOrTarget === "string" ? nameOrOptionsOrTarget : void 0;
+  const opts = typeof nameOrOptionsOrTarget === "object" && nameOrOptionsOrTarget !== null && isStepOptions(nameOrOptionsOrTarget) ? nameOrOptionsOrTarget : isStepOptions(contextOrOptions) ? contextOrOptions : {};
+  return (target, context) => applyStep(target, context, customName, opts);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  step
+});
+//# sourceMappingURL=index.js.map

package/dist/decorator/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/decorator/index.ts","../../src/decorator/humanizer.ts"],"sourcesContent":["import { test } from '@playwright/test';\nimport {\n  buildCustomStepTitle,\n  buildHumanStepTitle,\n  extractParamNames,\n  type ParamDescriptor,\n} from './humanizer.js';\nimport type { StepOptions } from './types.js';\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\ntype AnyMethod = (this: any, ...args: unknown[]) => unknown;\ntype StepDecorator = (target: AnyMethod, context: ClassMethodDecoratorContext) => AnyMethod;\n\nfunction isDecoratorContext(v: unknown): v is ClassMethodDecoratorContext {\n  return typeof v === 'object' && v !== null && (v as ClassMethodDecoratorContext).kind === 'method';\n}\n\nfunction isStepOptions(v: unknown): v is StepOptions {\n  if (typeof v !== 'object' || v === null) return false;\n  const allowedKeys = new Set(['box', 'timeout', 'noHumanizer']);\n  return Object.keys(v).every(k => allowedKeys.has(k));\n}\n\nfunction applyStep(\n  target: AnyMethod,\n  context: ClassMethodDecoratorContext,\n  customName: string | undefined,\n  opts: StepOptions\n): AnyMethod {\n  const paramNames = extractParamNames(target);\n\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  return function (this: any, ...args: unknown[]): unknown {\n    let stepTitle: string;\n\n    if (opts.noHumanizer) {\n      stepTitle = `${this.constructor.name}.${String(context.name)}`;\n    } else {\n      const params: ParamDescriptor[] = paramNames.map((name, i) => ({ name, value: args[i] }));\n\n      if (customName !== undefined) {\n        stepTitle = buildCustomStepTitle(customName, params);\n      } else {\n        stepTitle = buildHumanStepTitle(\n          this.constructor.name,\n          String(context.name),\n          params\n        );\n      }\n    }\n\n    return test.step(stepTitle, () => target.call(this, ...args), {\n      box: opts.box,\n      timeout: opts.timeout,\n    });\n  };\n}\n\n/**\n * Decorator that wraps a Page Object Model method in a `test.step()` call,\n * automatically generating a human-readable step title.\n *\n * @example Bare usage — humanizes class + method name + runtime params\n * ```ts\n * class LoginPage {\n *   @step\n *   async login(username: string, password: string) { ... }\n * }\n * // → 'Login page: login using username \"admin\" and password \"secret\"'\n * ```\n *\n * @example Custom step name — params are still appended\n * ```ts\n * class CheckoutPage {\n *   @step('Proceed to payment')\n *   async submitOrder(orderId: string) { ... }\n * }\n * // → 'Proceed to payment using order id \"ord_99\"'\n * ```\n *\n * @example Options only — humanizes with box + timeout\n * ```ts\n * class ProfilePage {\n *   @step({ box: true, timeout: 10_000 })\n *   async updateAvatar(file: string) { ... }\n * }\n * ```\n *\n * @example Custom name + options\n * ```ts\n * class CartPage {\n *   @step('Add item to cart', { box: true })\n *   async addItem(product: Product) { ... }\n * }\n * ```\n *\n * @example Disable humanizer — raw \"ClassName.methodName\", no params\n * ```ts\n * class AdminPage {\n *   @step({ noHumanizer: true })\n *   async deleteUser(userId: string) { ... }\n * }\n * // → 'AdminPage.deleteUser'\n * ```\n */\nexport function step(target: AnyMethod, context: ClassMethodDecoratorContext): AnyMethod;\nexport function step(name: string, options?: StepOptions): StepDecorator;\nexport function step(options: StepOptions): StepDecorator;\nexport function step(): StepDecorator;\nexport function step(\n  nameOrOptionsOrTarget?: string | StepOptions | AnyMethod,\n  contextOrOptions?: ClassMethodDecoratorContext | StepOptions\n): AnyMethod | StepDecorator {\n  // Case 1: @step (bare, no parentheses)\n  if (typeof nameOrOptionsOrTarget === 'function' && isDecoratorContext(contextOrOptions)) {\n    return applyStep(nameOrOptionsOrTarget, contextOrOptions, undefined, {});\n  }\n\n  // Cases 2–4: @step(...) factory\n  const customName =\n    typeof nameOrOptionsOrTarget === 'string' ? nameOrOptionsOrTarget : undefined;\n\n  const opts: StepOptions =\n    typeof nameOrOptionsOrTarget === 'object' && nameOrOptionsOrTarget !== null && isStepOptions(nameOrOptionsOrTarget)\n      ? nameOrOptionsOrTarget\n      : isStepOptions(contextOrOptions)\n        ? (contextOrOptions as StepOptions)\n        : {};\n\n  return (target: AnyMethod, context: ClassMethodDecoratorContext): AnyMethod =>\n    applyStep(target, context, customName, opts);\n}\n\nexport type { StepOptions } from './types.js';\n","import { humanize } from '@alduino/humanizer/string';\n\nexport interface ParamDescriptor {\n  name: string;\n  value: unknown;\n}\n\nfunction scoreParam(value: unknown): number {\n  if (value === null || value === undefined) return 0;\n  if (typeof value === 'boolean') return 1;\n  if (Array.isArray(value) || (typeof value === 'object')) return 2;\n  return 3; // string or number\n}\n\nfunction renderParamValue(name: string, value: unknown): string {\n  const humanName = humanize(name).toLowerCase();\n\n  if (value === null || value === undefined) {\n    return `${humanName}: not provided`;\n  }\n  if (typeof value === 'boolean') {\n    return value ? humanName : `not ${humanName}`;\n  }\n  if (typeof value === 'string') {\n    return value === '' ? `${humanName}: empty` : `${humanName} \"${value}\"`;\n  }\n  if (typeof value === 'number') {\n    return `${humanName} ${value}`;\n  }\n  if (Array.isArray(value)) {\n    if (value.length === 0) return `no ${humanName}`;\n    if (value.length <= 3) return `${humanName} [${value.map(v => JSON.stringify(v)).join(', ')}]`;\n    return `${value.length} ${humanName}`;\n  }\n  // object\n  const keys = Object.keys(value as object);\n  if (keys.length === 0) return `empty ${humanName}`;\n  if (keys.length <= 2) {\n    const entries = keys.map(k => `${k}: ${JSON.stringify((value as Record<string, unknown>)[k])}`).join(', ');\n    return `${humanName} {${entries}}`;\n  }\n  return `${humanName} with ${keys.length} fields`;\n}\n\nfunction joinParts(parts: string[]): string {\n  if (parts.length === 0) return '';\n  if (parts.length === 1) return parts[0];\n  return `${parts.slice(0, -1).join(', ')} and ${parts[parts.length - 1]}`;\n}\n\nexport function buildParamString(params: ParamDescriptor[]): string {\n  if (params.length === 0) return '';\n\n  let top: ParamDescriptor[];\n  let remaining = 0;\n\n  if (params.length <= 3) {\n    // All fit — preserve original order\n    top = params;\n  } else {\n    // Select top 3 by significance score, then by original position\n    const scored = params.map((p, originalIndex) => ({ ...p, score: scoreParam(p.value), originalIndex }));\n    scored.sort((a, b) => {\n      const scoreDiff = b.score - a.score;\n      return scoreDiff !== 0 ? scoreDiff : a.originalIndex - b.originalIndex;\n    });\n    top = scored.slice(0, 3);\n    remaining = params.length - 3;\n  }\n\n  const parts = top.map(p => renderParamValue(p.name, p.value));\n  const joined = joinParts(parts);\n\n  if (remaining > 0) {\n    return `${joined} and ${remaining} more option${remaining === 1 ? '' : 's'}`;\n  }\n  return joined;\n}\n\n/**\n * Builds a human-readable step title from a class name, method name, and runtime parameters.\n *\n * Format: \"<Humanized class>: <humanized method> using <params>\"\n *\n * @example\n * buildHumanStepTitle('LoginPage', 'fillCredentials', [])\n * // → \"Login page: fill credentials\"\n *\n * @example\n * buildHumanStepTitle('LoginPage', 'login', [\n *   { name: 'username', value: 'admin@test.com' },\n *   { name: 'password', value: 'secret' },\n * ])\n * // → 'Login page: login using username \"admin@test.com\" and password \"secret\"'\n */\nexport function buildHumanStepTitle(\n  className: string,\n  methodName: string,\n  params: ParamDescriptor[]\n): string {\n  const humanClass = humanize(className);\n  const humanMethod = humanize(methodName).toLowerCase();\n  const base = `${humanClass}: ${humanMethod}`;\n\n  const paramStr = buildParamString(params);\n  return paramStr ? `${base} using ${paramStr}` : base;\n}\n\n/**\n * Builds a human-readable step title from a custom name and runtime parameters.\n *\n * Format: \"<custom name> using <params>\"\n *\n * @example\n * buildCustomStepTitle('Proceed to payment', [\n *   { name: 'orderId', value: 'ord_99' },\n *   { name: 'retry', value: false },\n * ])\n * // → 'Proceed to payment using order id \"ord_99\" and not retry'\n */\nexport function buildCustomStepTitle(customName: string, params: ParamDescriptor[]): string {\n  const paramStr = buildParamString(params);\n  return paramStr ? `${customName} using ${paramStr}` : customName;\n}\n\n/**\n * Extracts parameter names from a function's source code via toString().\n * Handles camelCase, default values and rest params; skips destructured params.\n */\nexport function extractParamNames(fn: (...args: unknown[]) => unknown): string[] {\n  const fnStr = fn.toString();\n  const match = fnStr.match(/\\(([^)]*)\\)/);\n  if (!match || !match[1].trim()) return [];\n\n  return match[1]\n    .split(',')\n    .map(param => {\n      const name = param\n        .trim()\n        .replace(/^\\.\\.\\./, '') // rest params\n        .split(/[\\s=]/)[0]      // default values\n        .trim();\n      // Skip destructured params ({ ... } or [ ... ])\n      return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ? name : null;\n    })\n    .filter((name): name is string => name !== null && name.length > 0);\n}\n"],"mappings":"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","names":[]}