mcp-state-machine-test-framework 1.2.1 → 1.2.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +29 -59
- package/SMS_Protocol.md +45 -47
- package/agent_protocol.md +27 -17
- package/index.js +727 -510
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,61 +1,31 @@
|
|
|
1
|
-
# 🚀
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
npm install
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
## 🏁 Basic Workflow
|
|
30
|
-
1. **Initialize Project**: Run `init_project` to setup folders and templates.
|
|
31
|
-
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.
|
|
32
|
-
3. **Automatic Visualization**: Every map change regenerates a Mermaid diagram in `/maps`.
|
|
33
|
-
4. **Execution**: Run `execute_suite` to launch the automated flow.
|
|
34
|
-
|
|
35
|
-
## 🤖 AI Agent Interaction (Guided Design)
|
|
36
|
-
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.
|
|
37
|
-
|
|
38
|
-
## 📚 Technical Documentation
|
|
39
|
-
- [🧠 Technical Protocol & History](./SMS_Protocol.md)
|
|
40
|
-
- [📱 Perfecto Mobile Cloud Setup](./DOCUMENTATION/Perfecto_Setup.md)
|
|
41
|
-
- [🤖 Agent Guidelines](./agent_protocol.md)
|
|
42
|
-
|
|
43
|
-
## 🤖 AI Agent Quickstart (For Copilot/Cursor/Antigravity)
|
|
44
|
-
If you are an AI agent helping with this project, follow these rules:
|
|
45
|
-
1. **Environment**: This is a Node.js project. Always use `npm`.
|
|
46
|
-
2. **Setup**: Install via `npm install mcp-state-machine-test-framework`.
|
|
47
|
-
3. **Configuration**: Use `npx mcp-sms` as the command in `mcp_config.json`.
|
|
48
|
-
4. **Initialization**: Your very first action after installation **MUST** be calling the `init_project` tool to create the directory structure and templates.
|
|
49
|
-
5. **Workflow**: Use `inspect_framework` to understand the current state before proposing changes.
|
|
50
|
-
|
|
51
|
-
## 🚀 Mission Bootstrap (Copy & Paste to any AI Agent)
|
|
52
|
-
> **⚠️ CRITICAL SCHEMA WARNING**: This framework **DOES NOT** use `nodes[]` or `edges[]` arrays. It uses a `nodos` object map. **ALWAYS** use the `upsert_node` tool.
|
|
53
|
-
>
|
|
54
|
-
> **YOUR ONLY MISSION**:
|
|
55
|
-
> 1. Run `npx -y -p mcp-state-machine-test-framework mcp-sms-init` to setup EVERYTHING.
|
|
56
|
-
> 2. Read `.mcp_agent_rules` to understand the workflow.
|
|
57
|
-
>
|
|
58
|
-
> "Run `npx -y -p mcp-state-machine-test-framework mcp-sms-init`. This will setup the project, folders, templates and `mcp_config.json` automatically. Then read `.mcp_agent_rules` and start mapping using ONLY the provided MCP tools."
|
|
1
|
+
# 🚀 SMS Framework: State Machine Testing V12.0
|
|
2
|
+
|
|
3
|
+
> **Orquestación de Pruebas E2E de Alta Fidelidad mediante Máquina de Estados Procedural.**
|
|
4
|
+
|
|
5
|
+
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.
|
|
6
|
+
|
|
7
|
+
## 🌟 Características Principales
|
|
8
|
+
|
|
9
|
+
* **🛡️ 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.
|
|
10
|
+
* **⚙️ Ejecución Híbrida (MCP + SH)**: Soporte nativo para comandos de cualquier servidor MCP y comandos de Shell (`sh:`) en un mismo flujo.
|
|
11
|
+
* **🧪 Asserts Técnicos por Paso**: Cada paso del test puede incluir validaciones profundas (DB, API, Logs) mediante el campo `assert`.
|
|
12
|
+
* **🧙♂️ Wizards Integrados**: Asistentes guiados (`design_wizard` y `test_wizard`) para construir mapas y pruebas sin errores de sintaxis.
|
|
13
|
+
* **📊 Dashboard Premium**: Reportes HTML con glassmorphism que distinguen visualmente entre acciones, validaciones de identidad y asserts.
|
|
14
|
+
|
|
15
|
+
## 🚀 Inicio Rápido
|
|
16
|
+
|
|
17
|
+
1. **Instalación**: `npm install`
|
|
18
|
+
2. **Inicialización**: Usa el comando `init_project` para generar la estructura de carpetas.
|
|
19
|
+
3. **Diseño**: Usa `design_wizard` para crear tu primer mapa con identidad protegida.
|
|
20
|
+
4. **Prueba**: Usa `test_wizard` para ensamblar tu flujo de prueba.
|
|
21
|
+
5. **Ejecución**: `ejecutarSuite(suiteName)`
|
|
22
|
+
|
|
23
|
+
## 📁 Estructura del Proyecto
|
|
24
|
+
|
|
25
|
+
* `/maps`: Definiciones de la Máquina de Estados (Nodos, Fingerprints, Transiciones).
|
|
26
|
+
* `/test_cases`: Pasos lógicos de prueba con acciones y asserts.
|
|
27
|
+
* `/suites`: El pegamento que une mapas, pruebas y hooks globales.
|
|
28
|
+
* `/reports`: Evidencia técnica y visual con alta fidelidad.
|
|
59
29
|
|
|
60
30
|
---
|
|
61
|
-
*
|
|
31
|
+
*Desarrollado para la era de la automatización autónoma.*
|
package/SMS_Protocol.md
CHANGED
|
@@ -1,49 +1,47 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
Este documento
|
|
4
|
-
|
|
5
|
-
##
|
|
6
|
-
|
|
7
|
-
###
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
- **`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.
|
|
46
|
-
- **`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.
|
|
1
|
+
# 📑 SMS Protocol: Referencia Técnica V12.0
|
|
2
|
+
|
|
3
|
+
Este documento detalla los esquemas de datos para la orquestación de la Máquina de Estados.
|
|
4
|
+
|
|
5
|
+
## 🗺️ Esquema del Mapa (`/maps/*.json`)
|
|
6
|
+
|
|
7
|
+
### Estructura de Nodo
|
|
8
|
+
```json
|
|
9
|
+
"NOMBRE_NODO": {
|
|
10
|
+
"fingerprint": {
|
|
11
|
+
"selectors": ["~logo", "id:main_container"],
|
|
12
|
+
"timeout": 5000
|
|
13
|
+
},
|
|
14
|
+
"transiciones": {
|
|
15
|
+
"NOMBRE_TRANSICION": {
|
|
16
|
+
"destino": "OTRO_NODO",
|
|
17
|
+
"accion": "mcp:wdio-mcp/click_element { \"selector\": \"~btn\" }"
|
|
18
|
+
}
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## 🧪 Esquema del Test Case (`/test_cases/*.json`)
|
|
24
|
+
|
|
25
|
+
### Estructura de Paso
|
|
26
|
+
```json
|
|
27
|
+
{
|
|
28
|
+
"name": "TC_Ejemplo",
|
|
29
|
+
"steps": [
|
|
30
|
+
{
|
|
31
|
+
"name": "Paso 1",
|
|
32
|
+
"action": "TRANSICION_O_COMANDO",
|
|
33
|
+
"assert": "mcp:wdio-mcp/wait_for_element { \"selector\": \"~success_icon\" }"
|
|
34
|
+
}
|
|
35
|
+
]
|
|
36
|
+
}
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## ⚙️ Lógica del Motor de Ejecución
|
|
40
|
+
|
|
41
|
+
1. **Resolución de Acción**: Si la acción empieza por `transicion:`, el motor busca en el mapa cargado.
|
|
42
|
+
2. **Ejecución Principal**: Corre la acción (MCP o SH).
|
|
43
|
+
3. **Check de Identidad**: Si el destino tiene `fingerprint`, el motor itera por todos sus `selectors` y valida su presencia.
|
|
44
|
+
4. **Check de Assert**: Si el paso tiene `assert`, se ejecuta como una validación final antes de marcar el paso como "Passed".
|
|
47
45
|
|
|
48
46
|
---
|
|
49
|
-
*
|
|
47
|
+
*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
CHANGED
|
@@ -1,24 +1,34 @@
|
|
|
1
|
-
# 🤖 Protocolo de Operación del Agente: SMS Framework
|
|
1
|
+
# 🤖 Protocolo de Operación del Agente: SMS Framework V12.0
|
|
2
2
|
|
|
3
|
-
Este protocolo es de **obligado cumplimiento** para
|
|
3
|
+
Este protocolo es de **obligado cumplimiento** para asegurar la integridad de la Máquina de Estados y la calidad de los reportes.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## 🛠️ Herramientas de Gestión (MANDATORIO)
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
- **PROHIBIDO**: Crear o editar archivos en `/maps` usando herramientas genéricas de escritura de archivos.
|
|
9
|
-
- **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.
|
|
7
|
+
Los agentes **NO** deben crear archivos JSON manualmente si existe un Wizard disponible:
|
|
10
8
|
|
|
11
|
-
|
|
12
|
-
|
|
9
|
+
1. **Diseño de Mapas**: Usar `design_wizard`.
|
|
10
|
+
* Cada nodo **DEBE** tener una `fingerprint` (huella digital).
|
|
11
|
+
* Se recomienda usar **Múltiples Selectores** (Multivectorial) para evitar ambigüedades entre pantallas similares.
|
|
12
|
+
2. **Creación de Pruebas**: Usar `test_wizard`.
|
|
13
|
+
* Definir un `assert` técnico en pasos críticos (Login, Submit, Delete).
|
|
14
|
+
* Usar el prefijo `sh:` para validaciones de sistema/archivos y `mcp:` para validaciones de UI.
|
|
13
15
|
|
|
14
|
-
|
|
15
|
-
- **MANDATORIO**: Usar `save_suite`. El agente debe verificar que el `state_map` referenciado exista antes de guardar la suite.
|
|
16
|
+
## ⚖️ Reglas de Oro
|
|
16
17
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
2. **Registrar**: Inmediatamente usar `upsert_node` para añadir el hallazgo al mapa de estados.
|
|
20
|
-
3. **Validar**: Ejecutar un `save_test_case` rápido para confirmar que la nueva transición funciona.
|
|
21
|
-
4. **Reportar**: Usar `execute_suite` para generar la evidencia visual del nuevo flujo descubierto.
|
|
18
|
+
### 1. Sincronización de Identidad
|
|
19
|
+
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".
|
|
22
20
|
|
|
23
|
-
|
|
24
|
-
*
|
|
21
|
+
### 2. Validaciones (Asserts)
|
|
22
|
+
* **Acción**: Lo que el agente hace para mover la app.
|
|
23
|
+
* **Assert**: Lo que el agente verifica para confirmar el éxito del negocio.
|
|
24
|
+
* *Nota*: El motor fallará el paso si el `assert` devuelve un error, capturando automáticamente la evidencia en ese punto.
|
|
25
|
+
|
|
26
|
+
### 3. Prefijos de Acción
|
|
27
|
+
* `transicion:NOMBRE`: Ejecuta una ruta definida en el mapa.
|
|
28
|
+
* `mcp:SERVIDOR/HERRAMIENTA {args}`: Ejecución directa de herramienta.
|
|
29
|
+
* `sh:COMANDO`: Ejecución directa en consola del host.
|
|
30
|
+
|
|
31
|
+
## 📊 Reportes y Diagnóstico
|
|
32
|
+
Si una suite falla, el agente debe revisar el Dashboard:
|
|
33
|
+
* Si el error es de **Identidad**: El mapa o el selector de la huella están desactualizados.
|
|
34
|
+
* Si el error es de **Assert**: La funcionalidad de la aplicación bajo prueba ha fallado.
|