@simplysf/simply-utam 0.2.0 → 0.3.0

package/oclif.manifest.json

@@ -90,7 +90,7 @@
     "init": {
       "aliases": [],
       "args": {},
-      "description": "Inspects the target project, generates generator.config.json, utam.config.json, wdio.conf.mjs, and .utam/namespace-map.json, non-destructively injects standard Wireit tasks into package.json, and adds any missing UTAM rules to .forceignore under a \"# Ignore UTAM\" comment without changing existing lines.",
+      "description": "Inspects the target project, generates generator.config.json, utam.config.json, wdio.conf.mjs, and .utam/namespace-map.json, adds the DOM snapshot capture step to the UTAM test folder, non-destructively injects standard Wireit tasks into package.json, and adds any missing UTAM rules to .forceignore and .gitignore under a \"# Ignore UTAM\" comment without changing existing lines.",
       "examples": [
         "<%= config.bin %> <%= command.id %>",
         "<%= config.bin %> <%= command.id %> --source-dir force-app --app-name my-app",
@@ -165,6 +165,12 @@
           "multiple": false,
           "type": "option"
         },
+        "gitignore": {
+          "name": "gitignore",
+          "summary": "Add .utam/snapshots/ to .gitignore, so DOM snapshots stay out of git.",
+          "allowNo": true,
+          "type": "boolean"
+        },
         "verbose": {
           "char": "v",
           "name": "verbose",
@@ -485,7 +491,551 @@
         "commands",
         "steps.js"
       ]
+    },
+    "snapshot:find": {
+      "aliases": [],
+      "args": {},
+      "description": "Text matching is case-insensitive and substring, over each node's own text, its shadow text and its attribute values (not class). Record values are masked, so search by labels. Visible matches are listed first, in document order; hidden matches are counted, or listed with --all. --attr name=value is a case-insensitive substring match; --class matches one whole class token. --css tests a selector as UTAM's findElement would: every match in document order, the first (the one UTAM takes) marked, hidden ones included. It searches the document, or with --within a node's light DOM (a page object's elements) or, adding --shadow, its shadow root (shadow elements).",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> --text \"Account Name\"",
+        "<%= config.bin %> <%= command.id %> --tag records-record-layout-item --all",
+        "<%= config.bin %> <%= command.id %> --attr title=Edit",
+        "<%= config.bin %> <%= command.id %> --css \"lightning-button.slds-button_brand\"",
+        "<%= config.bin %> <%= command.id %> --css \"lightning-input\" --within n5012 --shadow"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "text": {
+          "name": "text",
+          "summary": "Text to match (case-insensitive substring).",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "attr": {
+          "name": "attr",
+          "summary": "Attribute to match: `name` (present) or `name=value` (substring).",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "tag": {
+          "name": "tag",
+          "summary": "Tag name to match exactly.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "class": {
+          "name": "class",
+          "summary": "A whole class token to match, as `.name` would (case-sensitive).",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "css": {
+          "exclusive": [
+            "text",
+            "attr",
+            "tag",
+            "class"
+          ],
+          "name": "css",
+          "summary": "A CSS selector to test as UTAM would: all matches in document order, the first marked.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "within": {
+          "dependsOn": [
+            "css"
+          ],
+          "name": "within",
+          "summary": "With --css: search under this node (its light DOM).",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "shadow": {
+          "dependsOn": [
+            "css",
+            "within"
+          ],
+          "name": "shadow",
+          "summary": "With --css and --within: search the node's shadow root instead.",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "all": {
+          "name": "all",
+          "summary": "List hidden matches in full rather than as a count.",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "file": {
+          "name": "file",
+          "summary": "Snapshot file to read, relative to the current folder (not --project-dir). Defaults to .utam/snapshots/latest.json in the project, the most recent snapshot.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "project-dir": {
+          "name": "project-dir",
+          "summary": "Root directory of the test project.",
+          "default": ".",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "limit": {
+          "name": "limit",
+          "summary": "Maximum lines of text output (default 200).",
+          "default": 200,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "snapshot:find",
+      "pluginAlias": "@simplysf/simply-utam",
+      "pluginName": "@simplysf/simply-utam",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Find nodes in a DOM snapshot by text, attribute, class, tag or CSS selector.",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "snapshot",
+        "find.js"
+      ]
+    },
+    "snapshot:lookup": {
+      "aliases": [],
+      "args": {
+        "tag": {
+          "description": "A custom element tag, or a page object name.",
+          "name": "tag"
+        }
+      },
+      "description": "Reads the project's own page objects (from utam.config.json) and the page-object packages that generator.config.json namespaces and .utam/namespace-map.json map to, such as salesforce-pageobjects. A tag maps to a page object through a root selector, an element typed as that page object, or the naming convention. Where a tag maps to an implementation of an interface, the interface is reported, since test code loads the interface. Also accepts a page object name (such as recordHomeFlexipage2) instead of a tag. With --search, lists the page objects whose name, import path, tags or description contain every word given.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> lightning-input",
+        "<%= config.bin %> <%= command.id %> one-record-home-flexipage2",
+        "<%= config.bin %> <%= command.id %> recordLayoutItem",
+        "<%= config.bin %> <%= command.id %> --search \"related list\""
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "search": {
+          "name": "search",
+          "summary": "Words to search for in page object names, import paths, tags and descriptions.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "project-dir": {
+          "name": "project-dir",
+          "summary": "Root directory of the test project.",
+          "default": ".",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "limit": {
+          "name": "limit",
+          "summary": "Maximum lines of text output (default 200).",
+          "default": 200,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "snapshot:lookup",
+      "pluginAlias": "@simplysf/simply-utam",
+      "pluginName": "@simplysf/simply-utam",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Show the page objects for a tag, with their import paths, methods and elements; or search them.",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "snapshot",
+        "lookup.js"
+      ]
+    },
+    "snapshot:node": {
+      "aliases": [],
+      "args": {
+        "id": {
+          "description": "The node handle, such as n5012 (from find, path or tree).",
+          "name": "id"
+        }
+      },
+      "description": "Its handle and its address (child positions from the page root, s for a step into a shadow root; the same in another snapshot of the same page). Every recorded attribute, unclipped; its own text and shadow text; its size and position; whether it is hidden, and under which node; its parent; and each of its light DOM and shadow root children in one line. With --ancestors, its ancestors instead, nearest first, one line each, with a line wherever the chain leaves a shadow root: for picking a container to scope a selector with.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> n5012",
+        "<%= config.bin %> <%= command.id %> --node n5012",
+        "<%= config.bin %> <%= command.id %> n5012 --ancestors"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "node": {
+          "name": "node",
+          "summary": "The node handle, instead of the argument.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "ancestors": {
+          "name": "ancestors",
+          "summary": "List the node's ancestors, nearest first, instead.",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "file": {
+          "name": "file",
+          "summary": "Snapshot file to read, relative to the current folder (not --project-dir). Defaults to .utam/snapshots/latest.json in the project, the most recent snapshot.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "project-dir": {
+          "name": "project-dir",
+          "summary": "Root directory of the test project.",
+          "default": ".",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "limit": {
+          "name": "limit",
+          "summary": "Maximum lines of text output (default 200).",
+          "default": 200,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "snapshot:node",
+      "pluginAlias": "@simplysf/simply-utam",
+      "pluginName": "@simplysf/simply-utam",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Show everything a snapshot recorded about one node.",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "snapshot",
+        "node.js"
+      ]
+    },
+    "snapshot:path": {
+      "aliases": [],
+      "args": {},
+      "description": "Marks each shadow crossing and each hidden ancestor, and annotates each custom element with its page object (import path, and root when utam.load can load it), a likely route through a page object above it (\"reachable through\"), or \"no page object found\". With --text, prints the path only when exactly one visible node matches; otherwise lists the candidates and exits with code 1.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> --node n5012",
+        "<%= config.bin %> <%= command.id %> --text \"Account Name\""
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "node": {
+          "name": "node",
+          "summary": "The target node handle, such as n5012 (from find or tree).",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "text": {
+          "name": "text",
+          "summary": "Find the target by text; it must have exactly one visible match.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "file": {
+          "name": "file",
+          "summary": "Snapshot file to read, relative to the current folder (not --project-dir). Defaults to .utam/snapshots/latest.json in the project, the most recent snapshot.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "project-dir": {
+          "name": "project-dir",
+          "summary": "Root directory of the test project.",
+          "default": ".",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "limit": {
+          "name": "limit",
+          "summary": "Maximum lines of text output (default 200).",
+          "default": 200,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "snapshot:path",
+      "pluginAlias": "@simplysf/simply-utam",
+      "pluginName": "@simplysf/simply-utam",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Show the custom elements from the document down to a node, with their page objects.",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "snapshot",
+        "path.js"
+      ]
+    },
+    "snapshot:tree": {
+      "aliases": [],
+      "args": {},
+      "description": "Each line is one node: tag, #id and .classes as CSS, other attributes, its own text and its shadow text, then its node handle (n…). \"#shadow(mode)\" lines mark a shadow root; \"(hidden)\" marks the top of a hidden subtree.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> --node n5012 --depth 3"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "node": {
+          "name": "node",
+          "summary": "The node to start at. Defaults to the snapshot root.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "depth": {
+          "name": "depth",
+          "summary": "How many levels below the node to print.",
+          "default": 3,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "file": {
+          "name": "file",
+          "summary": "Snapshot file to read, relative to the current folder (not --project-dir). Defaults to .utam/snapshots/latest.json in the project, the most recent snapshot.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "project-dir": {
+          "name": "project-dir",
+          "summary": "Root directory of the test project.",
+          "default": ".",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "limit": {
+          "name": "limit",
+          "summary": "Maximum lines of text output (default 200).",
+          "default": 200,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "snapshot:tree",
+      "pluginAlias": "@simplysf/simply-utam",
+      "pluginName": "@simplysf/simply-utam",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Print the pruned tree under a node, to a depth.",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "snapshot",
+        "tree.js"
+      ]
+    },
+    "snapshot:console:import": {
+      "aliases": [],
+      "args": {},
+      "description": "Reads the clipboard by default, or --file (- for standard input). Checks the snapshot, saves it to .utam/snapshots/manual/ as manual--<label or number>.json and to latest.json, and prints the header every snapshot command prints. The rest of the snapshot is kept as captured.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> --label \"account list\"",
+        "<%= config.bin %> <%= command.id %> --file ~/Downloads/dom-snapshot-20261019T120000.json",
+        "pbpaste | <%= config.bin %> <%= command.id %> --file -"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "file": {
+          "name": "file",
+          "summary": "Snapshot file to read instead of the clipboard, relative to the current folder; - for standard input.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "label": {
+          "name": "label",
+          "summary": "Label for the snapshot, used in its file name and header.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "project-dir": {
+          "name": "project-dir",
+          "summary": "Root directory of the test project.",
+          "default": ".",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "snapshot:console:import",
+      "pluginAlias": "@simplysf/simply-utam",
+      "pluginName": "@simplysf/simply-utam",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Save the DOM snapshot the console snippet copied, or any snapshot file.",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "snapshot",
+        "console",
+        "import.js"
+      ]
+    },
+    "snapshot:console:snippet": {
+      "aliases": [],
+      "args": {},
+      "description": "Paste it into the console of the page to capture, with the console's context set to top. It runs the same walker a test run does, masks the page there, copies the snapshot JSON to the clipboard and prints a summary; save it with `snapshot console import`. Where the console's copy() isn't available, it downloads the JSON instead, for `import --file`. The mask is fixed in the snippet.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> --copy",
+        "<%= config.bin %> <%= command.id %> --mask structure --copy",
+        "<%= config.bin %> <%= command.id %> > snippet.js"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "copy": {
+          "name": "copy",
+          "summary": "Copy the snippet to the clipboard instead of printing it.",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "mask": {
+          "name": "mask",
+          "summary": "Mask mode, from least kept to most. Defaults to UTAM_SNAPSHOT_MASK, then labels.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "structure",
+            "labels",
+            "aria",
+            "full"
+          ],
+          "type": "option"
+        },
+        "focus": {
+          "name": "focus",
+          "summary": "Where the walk starts: auto (the active Lightning page or console tab), none, or a CSS selector.",
+          "default": "auto",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "max-nodes": {
+          "name": "max-nodes",
+          "summary": "Most visible nodes to capture.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "max-hidden-nodes": {
+          "name": "max-hidden-nodes",
+          "summary": "Most hidden nodes to capture.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "snapshot:console:snippet",
+      "pluginAlias": "@simplysf/simply-utam",
+      "pluginName": "@simplysf/simply-utam",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "The snippet to paste into a browser's DevTools console to capture a DOM snapshot.",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "snapshot",
+        "console",
+        "snippet.js"
+      ]
     }
   },
-  "version": "0.2.0"
+  "version": "0.3.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@simplysf/simply-utam",
   "description": "Salesforce UTAM UI testing and build automation CLI",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "author": "@ClayChipps",
   "homepage": "https://github.com/SimplySF/simply-utam",
   "bugs": "https://github.com/SimplySF/simply-utam/issues",
@@ -19,6 +19,7 @@
   "files": [
     "/bin",
     "/lib",
+    "/skills",
     "README.md",
     "oclif.manifest.json"
   ],
@@ -42,7 +43,7 @@
   },
   "dependencies": {
     "@oclif/core": "^5.1.8",
-    "@simplysf/simply-utam-core": "0.2.0"
+    "@simplysf/simply-utam-core": "0.3.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.10",
@@ -72,7 +73,17 @@
     "commands": "./lib/commands",
     "topicSeparator": " ",
     "plugins": [],
-    "devPlugins": []
+    "devPlugins": [],
+    "topics": {
+      "snapshot": {
+        "description": "Capture and query DOM snapshots, and look up page objects.",
+        "subtopics": {
+          "console": {
+            "description": "Capture DOM snapshots by pasting a snippet into a browser's DevTools console."
+          }
+        }
+      }
+    }
   },
   "wireit": {
     "build": {
@@ -138,6 +149,7 @@
       },
       "files": [
         "test/**/*.ts",
+        "skills/**",
         "src/**/*.ts",
         "**/tsconfig.json",
         "../../tsconfig.json",
@@ -146,5 +158,5 @@
       "output": []
     }
   },
-  "gitHead": "eedb84621bf157badc522e89b97d998764df32cf"
+  "gitHead": "7a8febc345f771e17a39247082eb47333c75001b"
 }