mcp-state-machine-test-framework 1.2.3 → 1.2.6

package/README.md

@@ -1,60 +1,31 @@
-# 🚀 MCP State Machine Test Framework (SMS)
-
-The high-fidelity, autonomous orchestration engine for Next-Generation E2E Testing.
-
-## 🌟 Key Features
-- **Pure-MCP Architecture**: 100% compliant with the Model Context Protocol for seamless AI agent integration.
-- **Universal**: Supports Web, Mobile, and API testing through modular MCP tool aggregation.
-- **Secure by Design**: Automatic masking of sensitive data (tokens, JWTs) in reports and logs.
-- **Premium Reporting**: Generates high-fidelity HTML/JSON dashboards with glassmorphism aesthetics.
-- **Data-Driven Core**: Native support for complex testing scenarios via CSV and JSON data injection.
-
-## 🛠️ Quick Installation
-
-You can install it as a dependency in your project:
-
-```bash
-npm install mcp-state-machine-test-framework
-```
-
-Or run it directly via MCP in your configuration:
-
-```json
-"mcp-sms": {
-  "command": "npx",
-  "args": ["mcp-state-machine-test-framework"]
-}
-```
-
-## 🏁 Basic Workflow
-1. **Initialize Project**: Run `init_project` to setup folders and templates.
-2. **Guided Design**: Tell the agent to "Create a new node". The agent will ask for the mandatory fields (Map, Node Name, Transitions) before executing.
-3. **Automatic Visualization**: Every map change regenerates a Mermaid diagram in `/maps`.
-4. **Execution**: Run `execute_suite` to launch the automated flow.
-
-## 🤖 AI Agent Interaction (Guided Design)
-This framework enforces a "Strict Contract" via MCP tools. Agents are instructed NOT to edit JSON files directly, but to use the management tools (`upsert_node`, `save_test_case`, `save_suite`) which provide validation and structure.
-
-## 📚 Technical Documentation
-- [🧠 Technical Protocol & History](./SMS_Protocol.md)
-- [📱 Perfecto Mobile Cloud Setup](./DOCUMENTATION/Perfecto_Setup.md)
-- [🤖 Agent Guidelines](./agent_protocol.md)
-
-## 🤖 AI Agent Quickstart (For Copilot/Cursor/Antigravity)
-If you are an AI agent helping with this project, follow these rules:
-1. **Environment**: This is a Node.js project. Always use `npm`.
-2. **Setup**: Install via `npm install mcp-state-machine-test-framework`.
-3. **Configuration**: Use `npx mcp-sms` as the command in `mcp_config.json`.
-4. **Initialization**: Your very first action after installation **MUST** be calling the `init_project` tool to create the directory structure and templates.
-5. **Workflow**: Use `inspect_framework` to understand the current state before proposing changes.
-
-## 🚀 Mission Bootstrap (Copy & Paste to any AI Agent)
-> **YOUR ONLY MISSION**: 
-> 1. Run `npx -y -p mcp-state-machine-test-framework mcp-sms-init` to setup EVERYTHING.
-> 2. Use `design_wizard` (action: 'start') to design nodes step-by-step.
-> 3. **STRICT RULE**: Never edit JSON files manually.
-> 
-> "Run `npx -y -p mcp-state-machine-test-framework mcp-sms-init`. Then start a design session using `design_wizard` (action: 'start'). Follow the wizard steps to create nodes and transitions."
+# 🚀 SMS Framework: State Machine Testing V12.0
+
+> **Orquestación de Pruebas E2E de Alta Fidelidad mediante Máquina de Estados Procedural.**
+
+Este framework transforma la automatización tradicional en un sistema de orquestación autónomo donde la **Identidad de los Nodos** y la **Verificación Técnica** garantizan pruebas irrompibles en Web, Mobile y API.
+
+## 🌟 Características Principales
+
+*   **🛡️ Identidad Multivectorial (Fingerprinting)**: Los nodos no son solo nombres; tienen una huella digital (múltiples selectores) que el motor valida automáticamente para asegurar la sincronización total entre el mapa y la realidad.
+*   **⚙️ Ejecución Híbrida (MCP + SH)**: Soporte nativo para comandos de cualquier servidor MCP y comandos de Shell (`sh:`) en un mismo flujo.
+*   **🧪 Asserts Técnicos por Paso**: Cada paso del test puede incluir validaciones profundas (DB, API, Logs) mediante el campo `assert`.
+*   **🧙‍♂️ Wizards Integrados**: Asistentes guiados (`design_wizard` y `test_wizard`) para construir mapas y pruebas sin errores de sintaxis.
+*   **📊 Dashboard Premium**: Reportes HTML con glassmorphism que distinguen visualmente entre acciones, validaciones de identidad y asserts.
+
+## 🚀 Inicio Rápido
+
+1.  **Instalación**: `npm install`
+2.  **Inicialización**: Usa el comando `init_project` para generar la estructura de carpetas.
+3.  **Diseño**: Usa `design_wizard` para crear tu primer mapa con identidad protegida.
+4.  **Prueba**: Usa `test_wizard` para ensamblar tu flujo de prueba.
+5.  **Ejecución**: `ejecutarSuite(suiteName)`
+
+## 📁 Estructura del Proyecto
+
+*   `/maps`: Definiciones de la Máquina de Estados (Nodos, Fingerprints, Transiciones).
+*   `/test_cases`: Pasos lógicos de prueba con acciones y asserts.
+*   `/suites`: El pegamento que une mapas, pruebas y hooks globales.
+*   `/reports`: Evidencia técnica y visual con alta fidelidad.
 
 ---
-*Developed with ❤️ for maximum automation efficiency.*
+*Desarrollado para la era de la automatización autónoma.*

package/SMS_Protocol.md

@@ -1,49 +1,47 @@
-# 🧠 Historial Técnico y Protocolo: SMS MCP Server
-
-Este documento registra el aprendizaje evolutivo sobre el uso del **State Machine Server (SMS)** y su integración con otros servidores MCP (ej. `wdio-mcp`). **No contiene lógica de negocio**, sino maestría técnica.
-
-## 🛠️ Integración con WDIO-MCP (Aprendizajes Clave)
-
-### 1. Gestión de Capacidades (Mobile Cloud)
-- **Timeouts**: En entornos cloud (Perfecto), las sesiones tardan en inicializarse. Es vital usar `timeout: 30000` en acciones críticas de navegación.
-- **Capabilities Estables**: Para Android en Perfecto, el set mínimo estable es:
-    - `automationName: "UiAutomator2"`
-    - `useVirtualDevice: true`
-    - `app: "PRIVATE:NombreDeLaApp.apk"`
-- **Ciclo de Sesión**: Es preferible cerrar y abrir sesiones entre suites independientes para evitar colisiones de estado en el driver.
-
-### 2. Estrategias de Selectores en MCP
-- **Prioridad de Accesibilidad**: Siempre intentar primero `~ID_Accesibilidad`. Es el método más rápido y compatible con MCP.
-- **XPaths Robustos**: Cuando no hay IDs, usar `//*[@resource-id='com.id.app:id/elemento']//android.widget.EditText`. La doble barra `//` ayuda a mitigar cambios menores en la jerarquía.
-- **Scroll Automático**: Para elementos fuera de vista, usar el selector nativo de Android: `android=new UiScrollable(new UiSelector().scrollable(true)).scrollIntoView(new UiSelector().resourceId("..."))`.
-
-### 3. Autenticación y Credenciales
-- **Estrategia de Descubrimiento**: Si las variables de entorno están vacías, rastrear archivos de "scratch" o scripts de verificación (`verify_*.js`) donde el usuario suele dejar tokens hardcodeados para pruebas rápidas.
-- **Formato Perfecto**: El token debe inyectarse en `perfecto:options` -> `securityToken`.
-
-## ⚙️ Arquitectura del Servidor SMS
-
-### 1. Protocolo de Comunicación "Pure MCP"
-- **STDOUT Protegido**: Nunca usar `console.log` para depuración. Cualquier salida no-JSON rompe la conexión. Usar `process.stderr.write` o volcar a un archivo de log externo.
-- **Resolución de Rutas**: Los servidores MCP se lanzan desde contextos variables. Siempre usar `path.join(__dirname, ...)` para localizar mapas, casos y suites.
-
-### 2. Motor de Reportes y Evidencia
-- **Agregación de Resultados**: El servidor SMS itera sobre el array `content` de las respuestas MCP. Captura automáticamente:
-    - `type: "image"` -> Se convierte en miniatura visual.
-    - `type: "text"` -> Se guarda como log técnico expandible.
-- **Interpolación Dinámica**: Soporte para `{{variable}}` en las acciones, permitiendo inyectar datos de archivos CSV/JSON en tiempo de ejecución.
-
-## 🔄 Formatos de Ejecución
-- **Tool Principal**: `execute_suite({ "name": "Nombre_Suite" })`.
-- **Estructura Modular**: Suite -> Test Cases -> Steps -> Actions. Esta jerarquía garantiza que los reportes sean legibles y la evidencia se asocie correctamente a cada paso lógico.
-
-## 🛠️ Herramientas de Gestión (Management Tools)
-
-A partir de la versión 1.0.1, el servidor incluye herramientas para la construcción estructurada del framework:
-
-- **`upsert_node`**: Garantiza la integridad del mapa de estados. Valida que cada nodo tenga sus transiciones correctamente definidas.
-- **`save_test_case`**: Normaliza la creación de pasos de prueba, asegurando que la jerarquía Suite -> Case -> Step se mantenga para el generador de reportes.
-- **`save_suite`**: Orquesta el ensamblaje final, permitiendo la inyección de hooks (`before/afterSuite`) que son críticos para la gestión de sesiones en la nube.
+# 📑 SMS Protocol: Referencia Técnica V12.0
+
+Este documento detalla los esquemas de datos para la orquestación de la Máquina de Estados.
+
+## 🗺️ Esquema del Mapa (`/maps/*.json`)
+
+### Estructura de Nodo
+```json
+"NOMBRE_NODO": {
+  "fingerprint": {
+    "selectors": ["~logo", "id:main_container"],
+    "timeout": 5000
+  },
+  "transiciones": {
+    "NOMBRE_TRANSICION": {
+      "destino": "OTRO_NODO",
+      "accion": "mcp:wdio-mcp/click_element { \"selector\": \"~btn\" }"
+    }
+  }
+}
+```
+
+## 🧪 Esquema del Test Case (`/test_cases/*.json`)
+
+### Estructura de Paso
+```json
+{
+  "name": "TC_Ejemplo",
+  "steps": [
+    {
+      "name": "Paso 1",
+      "action": "TRANSICION_O_COMANDO",
+      "assert": "mcp:wdio-mcp/wait_for_element { \"selector\": \"~success_icon\" }"
+    }
+  ]
+}
+```
+
+## ⚙️ Lógica del Motor de Ejecución
+
+1.  **Resolución de Acción**: Si la acción empieza por `transicion:`, el motor busca en el mapa cargado.
+2.  **Ejecución Principal**: Corre la acción (MCP o SH).
+3.  **Check de Identidad**: Si el destino tiene `fingerprint`, el motor itera por todos sus `selectors` y valida su presencia.
+4.  **Check de Assert**: Si el paso tiene `assert`, se ejecuta como una validación final antes de marcar el paso como "Passed".
 
 ---
-*Documento en evolución constante. Agregue nuevos aprendizajes técnicos aquí.*
+*Nota: Todos los campos de texto dentro de las acciones y asserts soportan interpolación de datos dinámicos mediante `{{campo}}`.*

package/agent_protocol.md

@@ -1,24 +1,34 @@
-# 🤖 Protocolo de Operación del Agente: SMS Framework
+# 🤖 Protocolo de Operación del Agente: SMS Framework V12.0
 
-Este protocolo es de **obligado cumplimiento** para cualquier agente que opere el MCP State Machine Test Framework.
+Este protocolo es de **obligado cumplimiento** para asegurar la integridad de la Máquina de Estados y la calidad de los reportes.
 
-## ⚖️ Reglas de Construcción de Pruebas
+## 🛠️ Herramientas de Gestión (MANDATORIO)
 
-### 1. Gestión de Mapas y Estados
-- **PROHIBIDO**: Crear o editar archivos en `/maps` usando herramientas genéricas de escritura de archivos.
-- **MANDATORIO**: Usar la herramienta `upsert_node` para añadir o modificar nodos. Esto asegura que la estructura de transiciones y acciones sea válida para el motor de ejecución.
+Los agentes **NO** deben crear archivos JSON manualmente si existe un Wizard disponible:
 
-### 2. Definición de Casos de Prueba
-- **MANDATORIO**: Usar `save_test_case`. El agente debe definir los `steps` como un array de objetos, asegurando que cada paso tenga un nombre descriptivo para el reporte final.
+1.  **Diseño de Mapas**: Usar `design_wizard`.
+    *   Cada nodo **DEBE** tener una `fingerprint` (huella digital).
+    *   Se recomienda usar **Múltiples Selectores** (Multivectorial) para evitar ambigüedades entre pantallas similares.
+2.  **Creación de Pruebas**: Usar `test_wizard`.
+    *   Definir un `assert` técnico en pasos críticos (Login, Submit, Delete).
+    *   Usar el prefijo `sh:` para validaciones de sistema/archivos y `mcp:` para validaciones de UI.
 
-### 3. Ensamblaje de Suites
-- **MANDATORIO**: Usar `save_suite`. El agente debe verificar que el `state_map` referenciado exista antes de guardar la suite.
+## ⚖️ Reglas de Oro
 
-## 🔄 Flujo de Trabajo Autónomo (Discovery-to-Code)
-1. **Explorar**: Usar `wdio-mcp/get_elements` para identificar selectores.
-2. **Registrar**: Inmediatamente usar `upsert_node` para añadir el hallazgo al mapa de estados.
-3. **Validar**: Ejecutar un `save_test_case` rápido para confirmar que la nueva transición funciona.
-4. **Reportar**: Usar `execute_suite` para generar la evidencia visual del nuevo flujo descubierto.
+### 1. Sincronización de Identidad
+El agente debe asegurar que el `selector` usado en la `fingerprint` de un nodo sea visible de forma persistente mientras se está en esa pantalla. Si una pantalla es dinámica, usar el elemento más estable como "ancla".
 
----
-*V1.1 - Protocolo de Integridad Estructural*
+### 2. Validaciones (Asserts)
+*   **Acción**: Lo que el agente hace para mover la app.
+*   **Assert**: Lo que el agente verifica para confirmar el éxito del negocio.
+*   *Nota*: El motor fallará el paso si el `assert` devuelve un error, capturando automáticamente la evidencia en ese punto.
+
+### 3. Prefijos de Acción
+*   `transicion:NOMBRE`: Ejecuta una ruta definida en el mapa.
+*   `mcp:SERVIDOR/HERRAMIENTA {args}`: Ejecución directa de herramienta.
+*   `sh:COMANDO`: Ejecución directa en consola del host.
+
+## 📊 Reportes y Diagnóstico
+Si una suite falla, el agente debe revisar el Dashboard:
+*   Si el error es de **Identidad**: El mapa o el selector de la huella están desactualizados.
+*   Si el error es de **Assert**: La funcionalidad de la aplicación bajo prueba ha fallado.