mobile-automator 0.23.8

package/src/schemas/scenario_schema.json

@@ -0,0 +1,587 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Mobile QA Test Scenario",
+  "description": "Schema for mobile QA test scenario files generated by mauto generate. Supports dynamic waits, optional steps, conditional branching, nested sub-flows, variable capture/reuse, retry policies, and pattern-based assertions.",
+  "type": "object",
+  "required": [
+    "$schema_version",
+    "scenario_id",
+    "name",
+    "description",
+    "platform",
+    "app_package",
+    "metadata",
+    "steps",
+    "assertions"
+  ],
+  "properties": {
+    "$schema_version": {
+      "type": "string",
+      "enum": ["2.0", "2.1"],
+      "default": "2.0",
+      "description": "Schema version identifier. '2.0' or '2.1'."
+    },
+    "scenario_id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_]*$",
+      "description": "Unique identifier in snake_case (e.g., 'loyalty_voucher_redemption')"
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable name of the test scenario"
+    },
+    "description": {
+      "type": "string",
+      "description": "What this scenario tests and what business value it validates"
+    },
+    "platform": {
+      "type": "string",
+      "enum": [
+        "android",
+        "ios",
+        "cross-platform"
+      ]
+    },
+    "app_package": {
+      "type": "string",
+      "description": "Bundle ID or package name of the app under test"
+    },
+    "metadata": {
+      "type": "object",
+      "required": [
+        "app_version",
+        "environment"
+      ],
+      "description": "Design-time metadata only. Execution-time data (device_model, api_level, timestamp) belongs in the result schema.",
+      "properties": {
+        "app_version": {
+          "type": "string",
+          "description": "Build variant or version targeted by this scenario (e.g., 'staging-latest', '2.4.1-debug')"
+        },
+        "environment": {
+          "type": "string",
+          "description": "Target environment (e.g., 'production', 'staging', 'development')"
+        },
+        "target_version": {
+          "type": "string",
+          "description": "Optional: target app major version (e.g., 'v4.x') for scenario compatibility tracking"
+        }
+      },
+      "additionalProperties": false
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9][a-z0-9-]*$",
+        "maxLength": 20
+      },
+      "maxItems": 10,
+      "uniqueItems": true,
+      "description": "Categorization tags for filtering. Format: lowercase alphanumeric + hyphens only (e.g., 'smoke', 'regression', 'p0', 'auth'). Max 10 tags per scenario, max 20 characters per tag."
+    },
+    "variables": {
+      "type": "object",
+      "description": "Declare variables that will be captured during test execution and used in later steps or assertions.",
+      "additionalProperties": {
+        "type": "object",
+        "required": [
+          "type",
+          "description"
+        ],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": [
+              "string",
+              "integer",
+              "number",
+              "boolean"
+            ],
+            "description": "Data type of the captured variable"
+          },
+          "description": {
+            "type": "string",
+            "description": "Human-readable description of what this variable represents"
+          }
+        }
+      }
+    },
+    "preconditions": {
+      "type": "object",
+      "description": "Required state and setup actions before test execution begins.",
+      "properties": {
+        "app_state": {
+          "type": "string",
+          "enum": [
+            "fresh_install",
+            "logged_in",
+            "logged_out",
+            "any"
+          ],
+          "description": "Required app state before the test begins"
+        },
+        "device_actions": {
+          "type": "array",
+          "description": "Automated setup actions to perform on the device before the scenario starts",
+          "items": {
+            "type": "object",
+            "required": [
+              "action"
+            ],
+            "properties": {
+              "action": {
+                "type": "string",
+                "enum": [
+                  "clear_app_data",
+                  "uninstall_app",
+                  "install_app",
+                  "enable_wifi",
+                  "disable_wifi",
+                  "set_orientation"
+                ],
+                "description": "The setup action to perform"
+              },
+              "target_package": {
+                "type": "string",
+                "description": "App package to target (for clear_app_data and uninstall_app)"
+              },
+              "value": {
+                "type": "string",
+                "description": "Value parameter for the action (e.g., orientation value)"
+              },
+              "description": {
+                "type": "string",
+                "description": "Human-readable description of why this action is needed"
+              }
+            }
+          }
+        },
+        "device_properties": {
+          "type": "object",
+          "description": "Required device properties at test start",
+          "properties": {
+            "network": {
+              "type": "string",
+              "enum": [
+                "connected",
+                "wifi",
+                "cellular",
+                "disconnected"
+              ]
+            },
+            "location_services": {
+              "type": "string",
+              "enum": [
+                "enabled",
+                "disabled"
+              ]
+            },
+            "orientation": {
+              "type": "string",
+              "enum": [
+                "portrait",
+                "landscape"
+              ]
+            }
+          }
+        },
+        "notes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Human-readable notes about preconditions that cannot be automated (e.g., backend requirements, test account setup)"
+        }
+      }
+    },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Ordered list of test steps to execute.",
+      "items": {
+        "$ref": "#/definitions/step"
+      }
+    },
+    "assertions": {
+      "type": "array",
+      "description": "Verifications to run at specific points during the scenario.",
+      "items": {
+        "$ref": "#/definitions/assertion"
+      }
+    }
+  },
+  "definitions": {
+    "step": {
+      "type": "object",
+      "required": [
+        "id",
+        "action",
+        "description"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9_]*$",
+          "description": "Unique step identifier in snake_case (e.g., 'tap_login', 'wait_for_home'). Used for screenshot naming and assertion references."
+        },
+        "action": {
+          "type": "string",
+          "enum": [
+            "launch_app",
+            "tap",
+            "long_press",
+            "double_tap",
+            "type",
+            "swipe",
+            "scroll_to_element",
+            "press_button",
+            "wait_for_element",
+            "wait_for_element_gone",
+            "wait_for_loading_complete",
+            "capture_value",
+            "clear_app_data",
+            "open_url",
+            "press_back",
+            "dismiss_keyboard",
+            "grant_permission",
+            "deny_permission"
+          ],
+          "description": "The automation action to perform. Supported types: wait_for_element, wait_for_element_gone, wait_for_loading_complete, capture_value, clear_app_data, long_press, double_tap, scroll_to_element, press_back, dismiss_keyboard, grant_permission, deny_permission."
+        },
+        "description": {
+          "type": "string",
+          "description": "What this step does in plain language — should explain the intent, not just the mechanics"
+        },
+        "target": {
+          "type": "string",
+          "description": "Semantic description of the element to interact with or wait for. Used by the AI to locate the element via mobile_list_elements_on_screen."
+        },
+        "target_pattern": {
+          "type": "string",
+          "description": "Optional: regex pattern to match against element text when the element cannot be described with a static string (e.g., '\\\\d+ points' for a dynamic points tab label)"
+        },
+        "value": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Input value for the action: text to type, swipe direction (up/down/left/right), button name (HOME/BACK/ENTER), URL to open, or scroll direction"
+        },
+        "checkpoint": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether to capture a reference screenshot after this step. Screenshots are saved as mobile-automator/screenshots/<scenario_id>/step_<id>.png"
+        },
+        "expected_state": {
+          "type": "string",
+          "description": "Description of the expected visual state after this step completes — used by the executor for semantic validation"
+        },
+        "optional": {
+          "type": "boolean",
+          "default": false,
+          "description": "If true, failure to find or interact with the target element is silently ignored. Execution continues to the next step. Use for UI elements that only appear sometimes (A/B tests, dialogs, promotions)."
+        },
+        "condition": {
+          "type": "object",
+          "description": "When to execute this step. If the condition evaluates to false, the step is skipped.",
+          "required": [
+            "type"
+          ],
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": [
+                "device_property",
+                "previous_step_skipped",
+                "variable_value",
+                "element_visible"
+              ],
+              "description": "The type of condition to evaluate"
+            },
+            "property": {
+              "type": "string",
+              "description": "Device property name for device_property conditions (e.g., 'api_level', 'orientation', 'platform')"
+            },
+            "step_id": {
+              "type": "string",
+              "description": "Step ID reference for previous_step_skipped conditions"
+            },
+            "variable_name": {
+              "type": "string",
+              "description": "Variable name for variable_value conditions"
+            },
+            "element_description": {
+              "type": "string",
+              "description": "Element to check for element_visible conditions"
+            },
+            "operator": {
+              "type": "string",
+              "enum": [
+                "==",
+                "!=",
+                ">=",
+                "<=",
+                ">",
+                "<"
+              ],
+              "description": "Comparison operator"
+            },
+            "value": {
+              "description": "Value to compare against",
+              "type": [
+                "string",
+                "number",
+                "boolean"
+              ]
+            }
+          }
+        },
+        "on_failure": {
+          "type": "string",
+          "enum": [
+            "fail",
+            "skip",
+            "retry"
+          ],
+          "default": "fail",
+          "description": "What to do when this step fails. 'fail' = mark scenario failed (default). 'skip' = continue to next step silently. 'retry' = attempt retry_policy before failing."
+        },
+        "retry_policy": {
+          "type": "object",
+          "description": "Retry configuration. Only applicable when on_failure is 'retry'.",
+          "required": [
+            "max_attempts"
+          ],
+          "properties": {
+            "max_attempts": {
+              "type": "integer",
+              "minimum": 2,
+              "maximum": 5,
+              "description": "Total number of attempts including the first (e.g., 3 means 1 initial + 2 retries)"
+            },
+            "backoff_ms": {
+              "type": "integer",
+              "minimum": 0,
+              "default": 1000,
+              "description": "Milliseconds to wait between retry attempts"
+            }
+          }
+        },
+        "wait_config": {
+          "type": "object",
+          "description": "Configuration for wait-type actions (wait_for_element, wait_for_element_gone, wait_for_loading_complete).",
+          "required": [
+            "type",
+            "timeout_ms"
+          ],
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": [
+                "element_visible",
+                "element_gone",
+                "loading_complete"
+              ],
+              "description": "The wait condition to poll for"
+            },
+            "indicator": {
+              "type": "string",
+              "enum": [
+                "shimmer",
+                "spinner",
+                "progress_bar",
+                "skeleton",
+                "any"
+              ],
+              "default": "any",
+              "description": "For loading_complete: which type of loading indicator to wait for disappearance of"
+            },
+            "timeout_ms": {
+              "type": "integer",
+              "minimum": 1000,
+              "maximum": 60000,
+              "description": "Maximum time to wait in milliseconds before failing the step"
+            }
+          }
+        },
+        "capture_to": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9_]*$",
+          "description": "Variable name to store the captured value in. Must match a variable declared in the root 'variables' block. Used with capture_value action."
+        },
+        "permission_name": {
+          "type": "string",
+          "description": "Optional. Names a specific permission for grant_permission/deny_permission actions (e.g., 'camera', 'location'). Semantic-only — does not affect runtime resolution."
+        },
+        "sub_steps": {
+          "type": "array",
+          "description": "Nested sub-flow to execute when this step's condition is met. After all sub-steps complete, execution resumes at the next top-level step. Use for NESTED_CONDITIONAL patterns where an entire branching sub-flow must run under a specific condition.",
+          "items": {
+            "$ref": "#/definitions/step"
+          }
+        }
+      }
+    },
+    "assertion": {
+      "type": "object",
+      "required": [
+        "id",
+        "after_step",
+        "type",
+        "description"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9_]*$",
+          "description": "Unique assertion identifier in snake_case (e.g., 'assert_login_success')"
+        },
+        "after_step": {
+          "type": "string",
+          "description": "Step ID (by name) after which this assertion runs. Must reference a valid step id."
+        },
+        "type": {
+          "type": "string",
+          "enum": [
+            "screenshot_match",
+            "element_exists",
+            "element_text",
+            "element_not_exists",
+            "pattern_match",
+            "value_matches_variable",
+            "element_count",
+            "visual_state",
+            "text_changed",
+            "element_state",
+            "element_visible",
+            "text_contains",
+            "text_not_empty",
+            "element_hint",
+            "content_description",
+            "list_item_count",
+            "list_is_empty",
+            "element_fully_visible",
+            "color_style",
+            "screen_title",
+            "alert_present",
+            "alert_text",
+            "toast_visible",
+            "keyboard_visible",
+            "has_accessibility_label",
+            "permission_dialog_shown",
+            "dark_mode_active"
+          ],
+          "description": "Assertion type. Supported types: screenshot_match, element_exists, element_text, element_not_exists, pattern_match, value_matches_variable, element_count, visual_state, text_changed, element_state, element_visible, text_contains, text_not_empty, element_hint, content_description, list_item_count, list_is_empty, element_fully_visible, color_style, screen_title, alert_present, alert_text, toast_visible, keyboard_visible, has_accessibility_label, permission_dialog_shown, dark_mode_active."
+        },
+        "description": {
+          "type": "string",
+          "description": "Human-readable description of what this assertion validates and why it matters"
+        },
+        "element_description": {
+          "type": "string",
+          "description": "Semantic description of the element to check (for element_exists, element_text, element_not_exists, element_count, pattern_match, value_matches_variable, text_changed)"
+        },
+        "expected_value": {
+          "type": "string",
+          "description": "Expected text value for element_text assertions"
+        },
+        "pattern": {
+          "type": "string",
+          "description": "Regex pattern to match against element text for pattern_match assertions. Also used as a format hint in value_matches_variable assertions."
+        },
+        "variable_name": {
+          "type": "string",
+          "description": "Variable name (declared in 'variables' block) whose captured value to compare against for value_matches_variable assertions"
+        },
+        "operator": {
+          "type": "string",
+          "enum": [
+            "==",
+            "!=",
+            ">=",
+            "<=",
+            ">",
+            "<"
+          ],
+          "default": "==",
+          "description": "Comparison operator for element_count and list_item_count assertions"
+        },
+        "expected_count": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Expected element count for element_count assertions"
+        },
+        "expected_visual_state": {
+          "type": "string",
+          "enum": [
+            "loaded",
+            "loading",
+            "empty",
+            "error"
+          ],
+          "description": "Expected visual state for visual_state assertions"
+        },
+        "reference_screenshot": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Relative path to the reference baseline screenshot for screenshot_match assertions"
+        },
+        "tolerance": {
+          "type": "number",
+          "minimum": 0.0,
+          "maximum": 1.0,
+          "default": 0.9,
+          "description": "Similarity threshold for screenshot_match assertions (0.0 = any match, 1.0 = pixel-perfect)"
+        },
+        "state_property": {
+          "type": "string",
+          "enum": [
+            "enabled",
+            "disabled",
+            "selected",
+            "not_selected",
+            "focused",
+            "clickable"
+          ],
+          "description": "For element_state: the specific interactive state to verify on the target element."
+        },
+        "expected_visible": {
+          "type": "boolean",
+          "description": "For element_visible and keyboard_visible: true = must be visible/showing, false = must be hidden/dismissed."
+        },
+        "expected_substring": {
+          "type": "string",
+          "description": "For text_contains: the substring to search for within the element's text content. Pass if the element's text includes this value anywhere."
+        },
+        "expected_text": {
+          "type": "string",
+          "description": "For toast_visible, alert_text, screen_title, element_hint, content_description: the exact text content to match."
+        },
+        "expected_theme": {
+          "type": "string",
+          "enum": [
+            "dark",
+            "light"
+          ],
+          "description": "For dark_mode_active: the expected system theme."
+        },
+        "color_hex": {
+          "type": "string",
+          "pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$",
+          "description": "For color_style: the expected element color in hex format (e.g., '#0057FF')."
+        },
+        "label_value": {
+          "type": "string",
+          "description": "For has_accessibility_label and content_description: the expected accessibility label / content description text."
+        },
+        "permission_name": {
+          "type": "string",
+          "description": "For permission_dialog_shown: the permission being requested (e.g., 'camera', 'location', 'microphone', 'notifications', 'contacts')."
+        }
+      }
+    }
+  }
+}

package/src/setup/scaffold.js

@@ -0,0 +1,53 @@
+'use strict';
+
+// Workspace scaffolding for `mauto setup`.
+//
+// Creates the mobile-automator/{scenarios,screenshots,results} tree and a
+// skeleton config.json. Idempotent: re-running never clobbers an existing
+// config's other fields — it only ensures the requested `mode` is set.
+
+const fs = require('fs');
+const path = require('path');
+
+const manager = require('../config/manager');
+
+const SUBDIRS = ['scenarios', 'screenshots', 'results', 'memory'];
+
+function scaffold(projectRoot, { mode } = {}) {
+  const created = [];
+
+  const baseDir = path.join(projectRoot, 'mobile-automator');
+  ensureDir(baseDir, created);
+  for (const sub of SUBDIRS) {
+    ensureDir(path.join(baseDir, sub), created);
+  }
+
+  const cfgPath = manager.configPath(projectRoot);
+  let configWritten = false;
+  if (!fs.existsSync(cfgPath)) {
+    // Fresh skeleton — single source of truth for the day-one config shape.
+    const skeleton = {
+      mode,
+      project_name: null,
+      environments: [],
+      default_environment: null,
+    };
+    fs.writeFileSync(cfgPath, JSON.stringify(skeleton, null, 2) + '\n');
+    created.push(cfgPath);
+    configWritten = true;
+  } else {
+    // Pre-existing config: only set the mode, preserving every other field.
+    manager.set(projectRoot, 'mode', mode);
+  }
+
+  return { created, mode, configWritten };
+}
+
+function ensureDir(dir, created) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+    created.push(dir);
+  }
+}
+
+module.exports = { scaffold };

package/src/util/atomic.js

@@ -0,0 +1,41 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// Atomic write: stream into a hidden temp file in the same directory,
+// fsync, then rename over the target. rename(2) within one dir is atomic, so
+// a concurrent reader or a crash sees the old-complete or new-complete file,
+// never a truncated one. On any failure the temp file is cleaned up.
+function atomicWrite(file, contents) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = path.join(
+    path.dirname(file),
+    `.${path.basename(file)}.tmp.${process.pid}.${Date.now()}`
+  );
+  let fd;
+  try {
+    fd = fs.openSync(tmp, 'w');
+    fs.writeFileSync(fd, contents);
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = undefined;
+    fs.renameSync(tmp, file);
+  } catch (e) {
+    if (fd !== undefined) {
+      try {
+        fs.closeSync(fd);
+      } catch (_) {
+        /* ignore */
+      }
+    }
+    try {
+      fs.unlinkSync(tmp);
+    } catch (_) {
+      /* ignore */
+    }
+    throw e;
+  }
+}
+
+module.exports = { atomicWrite };