looking-glass-mcp 2.1.0 → 2.2.0

package/README.md

@@ -132,7 +132,7 @@ These tools exist because an AI is the operator — they would be useless to a h
 
 | Tool | What it does |
 |------|-------------|
-| `test_scenario_run` | Execute multi-step test scenarios defined in JSON |
+| `test_scenario_run` | Execute multi-step test scenarios with smart element resolution, self-healing selectors, composite steps, and data-driven testing |
 | `test_scenario_status` | Check progress of a running scenario |
 | `test_assert` | Run a single assertion (12 types: exists, textContains, urlEquals, isVisible, etc.) |
 | `test_fill_form` | Auto-fill form fields by selector mapping |
@@ -169,7 +169,9 @@ These tools exist because an AI is the operator — they would be useless to a h
 
 ## Test Scenarios
 
-Define multi-step test flows in JSON and run them with `test_scenario_run`:
+Define multi-step test flows in JSON and run them with `test_scenario_run`. Steps support **smart element resolution** — use `query` for natural language element matching, `selector` for CSS selectors, or both (selector is tried first, query is the self-healing fallback).
+
+### Basic scenario with CSS selectors
 
 ```json
 {
@@ -185,7 +187,71 @@ Define multi-step test flows in JSON and run them with `test_scenario_run`:
 }
 ```
 
-**14 step actions**: navigate, click, type, select, hover, scroll, press, waitForSelector, waitForText, waitForNavigation, waitForNetworkIdle, assert, screenshot, evaluate, sleep
+### Smart scenario with natural language queries
+
+```json
+{
+  "name": "Login Flow (smart)",
+  "steps": [
+    { "name": "Navigate", "action": "navigate", "url": "http://localhost:3000/login" },
+    { "name": "Enter email", "action": "type", "query": "email input", "value": "user@test.com" },
+    { "name": "Enter password", "action": "type", "query": "password field", "value": "secret" },
+    { "name": "Submit", "action": "click", "query": "sign in button" },
+    { "name": "Verify redirect", "action": "assert", "type": "urlContains", "expected": "/dashboard" }
+  ]
+}
+```
+
+### Self-healing selectors
+
+Provide both `selector` and `query`. The selector is tried first (fast). If it fails (DOM changed, class renamed), the query resolves the element semantically via the accessibility tree. The step is marked `[HEALED]` in the results so you know it happened.
+
+```json
+{ "name": "Submit", "action": "click", "selector": "button.btn-login", "query": "the login button" }
+```
+
+### Composite steps
+
+High-level actions that replace 5-6 atomic steps:
+
+```json
+{ "name": "Log in", "action": "login", "url": "/login", "value": "admin@co.com", "password": "P@ssw0rd", "waitForSelector": ".dashboard" }
+```
+
+```json
+{ "name": "Fill signup", "action": "fill_form", "fields": { "Email": "test@co.com", "Name": "Jane" }, "selector": "button.submit" }
+```
+
+```json
+{ "name": "Wait for page", "action": "wait_stable", "timeout": 5000 }
+```
+
+### Data-driven testing
+
+Use `{{variable}}` placeholders and provide `dataSets` to run the same scenario with multiple inputs:
+
+```json
+{
+  "name": "Login with {{role}} user",
+  "steps": [
+    { "name": "Enter email", "action": "type", "query": "email input", "value": "{{username}}" },
+    { "name": "Enter password", "action": "type", "query": "password field", "value": "{{password}}" },
+    { "name": "Submit", "action": "click", "query": "sign in button" },
+    { "name": "Verify", "action": "assert", "type": "urlContains", "expected": "{{expectedUrl}}" }
+  ],
+  "dataSets": [
+    { "label": "admin", "variables": { "role": "admin", "username": "admin@co.com", "password": "Admin1!", "expectedUrl": "/dashboard" } },
+    { "label": "viewer", "variables": { "role": "viewer", "username": "view@co.com", "password": "View1!", "expectedUrl": "/readonly" } },
+    { "label": "invalid", "variables": { "role": "invalid", "username": "bad@co.com", "password": "wrong", "expectedUrl": "/login" } }
+  ]
+}
+```
+
+### Full observability
+
+Every step automatically captures a screenshot, page state (URL, console errors, network failures), and resolution details (method, confidence score, whether self-healing was used). Scenario results include aggregated resolution metrics.
+
+**18 step actions**: navigate, click, type, select, hover, scroll, press, waitForSelector, waitForText, waitForNavigation, waitForNetworkIdle, assert, screenshot, evaluate, sleep, login, fill_form, wait_stable
 
 **12 assertion types**: exists, notExists, textContains, textEquals, hasAttribute, hasClass, isVisible, isEnabled, urlContains, urlEquals, countEquals, consoleNoErrors