socialseed-e2e 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

socialseed_e2e/templates/agent_docs/AGENT_GUIDE.md.template

@@ -0,0 +1,412 @@
+# 📘 Guía para Agentes de IA - SocialSeed E2E Framework
+
+> **Versión 2.0 - Actualizado para evitar errores comunes**
+
+Esta guía te permite generar tests E2E funcionales sin errores de importación, serialización o configuración.
+
+---
+
+## 🚨 REGLAS DE ORO (Lee esto primero)
+
+### 1. **Imports SIEMPRE Absolutos**
+```python
+# ❌ NUNCA uses imports relativos
+from ..data_schema import RegisterRequest  # PROHIBIDO
+
+# ✅ SIEMPRE uses imports absolutos
+from services.auth_service.data_schema import RegisterRequest
+from services.auth_service.auth_page import AuthServicePage
+```
+
+### 2. **Serialización con Aliases**
+```python
+# ❌ NUNCA sin by_alias=True (envía refresh_token en lugar de refreshToken)
+data = request.model_dump()
+
+# ✅ SIEMPRE con by_alias=True (envía refreshToken como espera Java)
+data = request.model_dump(by_alias=True)
+```
+
+### 3. **Modelos Pydantic con Config**
+```python
+class RefreshTokenRequest(BaseModel):
+    # SIEMPRE incluye esto
+    model_config = {"populate_by_name": True}
+
+    # Campos compuestos SIEMPRE con alias camelCase
+    refresh_token: str = Field(
+        ...,
+        alias="refreshToken",
+        serialization_alias="refreshToken"
+    )
+```
+
+### 4. **Manejo Manual de Headers**
+```python
+# ❌ NO existe update_headers()
+self.update_headers({"Authorization": f"Bearer {token}"})
+
+# ✅ Implementa _get_headers() manualmente
+def _get_headers(self, extra=None):
+    headers = {"Content-Type": "application/json"}
+    if self.access_token:
+        headers["Authorization"] = f"Bearer {self.access_token}"
+    return headers
+```
+
+### 5. **Nombres de Métodos sin Conflicto**
+```python
+# ❌ Conflicto: atributo refresh_token vs método refresh_token()
+self.refresh_token = token  # Atributo
+
+# ✅ Usa prefijo do_ para métodos
+self.refresh_token = token  # Atributo
+self.do_refresh_token()      # Método
+```
+
+---
+
+## 📦 Dependencias Requeridas
+
+El archivo `requirements.txt` debe incluir:
+
+```
+pydantic>=2.0.0
+email-validator>=2.0.0  # REQUERIDO para EmailStr
+dnspython>=2.0.0          # Para validación de email
+```
+
+**Si falta email-validator:**
+```
+ImportError: email-validator is not installed
+```
+
+**Solución:**
+```bash
+pip install -r requirements.txt
+```
+
+---
+
+## 🎯 Templates Actualizados
+
+### data_schema.py - Estructura Base
+
+```python
+"""Data schema for <service> API.
+
+⚠️ IMPORTANTE: Todos los campos compuestos usan camelCase aliases.
+"""
+from pydantic import BaseModel, Field, EmailStr
+from typing import Optional
+
+
+class LoginRequest(BaseModel):
+    """Login request."""
+    model_config = {"populate_by_name": True}
+
+    email: EmailStr
+    password: str
+
+
+class RefreshTokenRequest(BaseModel):
+    """Refresh token request."""
+    model_config = {"populate_by_name": True}
+
+    # ⚠️ camelCase alias requerido para backend Java
+    refresh_token: str = Field(
+        ...,
+        alias="refreshToken",
+        serialization_alias="refreshToken"
+    )
+```
+
+### service_page.py - Estructura Base
+
+```python
+"""Page object for <service> API."""
+from typing import Optional, Dict, Any
+from playwright.sync_api import APIResponse
+from socialseed_e2e.core.base_page import BasePage
+
+from .data_schema import (
+    ENDPOINTS,
+    LoginRequest,
+    RefreshTokenRequest,
+)
+
+
+class AuthPage(BasePage):
+    """Page for auth service."""
+
+    def __init__(self, base_url: str, **kwargs):
+        super().__init__(base_url=base_url, **kwargs)
+        self.access_token: Optional[str] = None
+        self.refresh_token: Optional[str] = None
+
+    def _get_headers(self, extra: Optional[Dict] = None) -> Dict[str, str]:
+        headers = {"Content-Type": "application/json"}
+        if self.access_token:
+            headers["Authorization"] = f"Bearer {self.access_token}"
+        if extra:
+            headers.update(extra)
+        return headers
+
+    def do_login(self, request: LoginRequest) -> APIResponse:
+        """Login and store tokens."""
+        response = self.post(
+            ENDPOINTS["login"],
+            data=request.model_dump(by_alias=True)  # ✅ SIEMPRE by_alias=True
+        )
+        if response.ok:
+            data = response.json()["data"]
+            self.access_token = data.get("token")
+            self.refresh_token = data.get("refreshToken")
+        return response
+
+    def do_refresh_token(self) -> APIResponse:
+        """Refresh access token."""
+        if not self.refresh_token:
+            raise ValueError("No refresh token")
+
+        request = RefreshTokenRequest(refresh_token=self.refresh_token)
+        response = self.post(
+            ENDPOINTS["refresh"],
+            data=request.model_dump(by_alias=True)  # ✅ SIEMPRE by_alias=True
+        )
+        if response.ok:
+            data = response.json()["data"]
+            self.access_token = data.get("token")
+            self.refresh_token = data.get("refreshToken")
+        return response
+```
+
+### modules/01_login_flow.py - Estructura Base
+
+```python
+"""Test module 01: Login flow."""
+from services.auth_service.data_schema import LoginRequest, TEST_USER
+
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from services.auth_service.auth_page import AuthPage
+
+
+def run(page: "AuthPage"):
+    """Execute login test."""
+    print("STEP 01: Testing Login")
+
+    login_data = LoginRequest(
+        email=TEST_USER["email"],
+        password=TEST_USER["password"]
+    )
+
+    response = page.do_login(login_data)
+
+    assert response.ok, f"Login failed: {response.status}"
+    assert page.access_token is not None, "Token not stored"
+
+    print(f"✓ Login successful")
+    print(f"✓ Token: {page.access_token[:20]}...")
+```
+
+---
+
+## 🔧 Solución de Problemas
+
+### Problema 1: `ImportError: email-validator is not installed`
+
+**Causa:** Falta la dependencia email-validator.
+
+**Solución:**
+1. Asegúrate de que `requirements.txt` incluya `email-validator>=2.0.0`
+2. Ejecuta: `pip install -r requirements.txt`
+
+### Problema 2: `cannot import name '_01_register_flow'`
+
+**Causa:** Los módulos con nombres numéricos no pueden importarse normalmente.
+
+**Solución - Tres métodos:**
+
+**Método A: importlib (recomendado para scripts)**
+```python
+import importlib.util
+import importlib.machinery
+
+def load_module(name, path):
+    loader = importlib.machinery.SourceFileLoader(name, path)
+    spec = importlib.util.spec_from_loader(name, loader)
+    module = importlib.util.module_from_spec(spec)
+    loader.exec_module(module)
+    return module
+
+register_module = load_module(
+    "register_flow",
+    "/path/to/services/auth/modules/01_register_flow.py"
+)
+register_module.run(page)
+```
+
+**Método B: Import directo**
+```python
+from services.auth.modules._01_register_flow import run
+run(page)
+```
+
+**Método C: Import función**
+```python
+from services.auth.modules import _01_register_flow
+_01_register_flow.run(page)
+```
+
+### Problema 3: `Refresh token is required` (400 error)
+
+**Causa:** Pydantic serializa `refresh_token` en lugar de `refreshToken`.
+
+**Solución:**
+1. En el modelo, usa alias camelCase:
+```python
+refresh_token: str = Field(
+    ...,
+    alias="refreshToken",
+    serialization_alias="refreshToken"
+)
+```
+
+2. Al serializar, usa by_alias=True:
+```python
+data = request.model_dump(by_alias=True)
+```
+
+### Problema 4: `Method declaration "logout" is obscured`
+
+**Causa:** Conflicto entre atributo y método con mismo nombre.
+
+**Solución:**
+```python
+# Atributo
+self.refresh_token: Optional[str] = None
+
+# Método con prefijo do_
+def do_refresh_token(self):
+    pass
+
+def do_logout(self):
+    pass
+```
+
+### Problema 5: `update_headers not found`
+
+**Causa:** El método `update_headers()` no existe en `BasePage`.
+
+**Solución:** Implementa manejo manual:
+```python
+def _get_headers(self, extra=None):
+    headers = {"Content-Type": "application/json"}
+    if self.access_token:
+        headers["Authorization"] = f"Bearer {self.access_token}"
+    if extra:
+        headers.update(extra)
+    return headers
+```
+
+---
+
+## ✅ Checklist Pre-Entrega
+
+Antes de decir "terminado", verifica:
+
+- [ ] `email-validator` está en requirements.txt
+- [ ] Todos los modelos tienen `model_config = {"populate_by_name": True}`
+- [ ] Campos compuestos tienen `alias` y `serialization_alias` en camelCase
+- [ ] En todos los métodos de page: `request.model_dump(by_alias=True)`
+- [ ] NINGÚN import relativo (`from ..x`)
+- [ ] Todos los imports son absolutos (`from services.xxx`)
+- [ ] Métodos conflictivos usan prefijo `do_` (do_refresh_token, do_logout)
+- [ ] Headers manejados manualmente (no update_headers)
+- [ ] Funciones `run(page)` bien definidas en módulos
+- [ ] Type hints usando `TYPE_CHECKING` para evitar imports circulares
+
+---
+
+## 🎯 Flujo de Trabajo Recomendado
+
+### Para Agentes de IA:
+
+1. **Lee los controladores Java** del servicio target
+2. **Identifica endpoints**: rutas, métodos HTTP, body params
+3. **Crea data_schema.py**:
+   - Modelos Pydantic con aliases camelCase
+   - Constantes de endpoints
+   - Datos de test
+4. **Crea service_page.py**:
+   - Hereda de BasePage
+   - Implementa _get_headers()
+   - Métodos para cada endpoint
+   - Usa by_alias=True siempre
+5. **Crea modules/**:
+   - 01_*_flow.py: Crear/Login
+   - 02_*_flow.py: Operaciones CRUD
+   - 99_*_flow.py: Cleanup/Logout
+6. **Verifica** ejecutando: `python verify_installation.py`
+
+---
+
+## 📚 Recursos Adicionales
+
+- **Ejemplo Completo:** Ver `.agent/EXAMPLE_TEST.md`
+- **Flujo de Generación:** Ver `.agent/WORKFLOW_GENERATION.md`
+- **Documentación Framework:** https://daironpf.github.io/socialseed-e2e/
+- **Pydantic v2:** https://docs.pydantic.dev/latest/
+
+---
+
+## 🎓 Tips para Éxito
+
+1. **Siempre verifica serialización:**
+   ```python
+   print(request.model_dump(by_alias=True))
+   # Debe mostrar camelCase: {'refreshToken': 'xxx'}
+   # NO snake_case: {'refresh_token': 'xxx'}
+   ```
+
+2. **Test incremental:**
+   - Ejecuta test 01 primero
+   - Verifica que el estado se guarda en `page`
+   - Luego ejecuta test 02
+
+3. **Manejo de errores:**
+   ```python
+   assert response.ok, f"Failed: {response.status} - {response.text()[:100]}"
+   ```
+
+4. **Compartir estado:**
+   - Guarda en `page` (ej: `page.user_id = data["id"]`)
+   - Recupera en siguiente test
+
+5. **Ejecución Flexible:**
+   Si ejecutas desde el root del proyecto y el config está en una subcarpeta:
+   ```bash
+   e2e run -c otrotest/e2e.conf
+   ```
+   El framework encontrará los servicios automáticamente.
+
+---
+
+## 🚀 Resultado Esperado
+
+Siguiendo esta guía, los agentes de IA pueden generar:
+
+- ✅ Tests funcionales sin errores de importación
+- ✅ Serialización correcta camelCase ↔ snake_case
+- ✅ Manejo de autenticación entre tests
+- ✅ Tests secuenciales con estado compartido
+
+**Tiempo estimado:** 2-5 minutos por servicio
+**Intervención humana:** Mínima o ninguna
+
+---
+
+**Versión:** 2.0
+**Última actualización:** 2026-02-03
+**Framework:** socialseed-e2e v0.1.0+

socialseed_e2e/templates/agent_docs/EXAMPLE_TEST.md.template

@@ -0,0 +1,152 @@
+# Ejemplo Completo de Test Generado
+
+Este archivo sirve como referencia "Gold Standard" de lo que se espera generar.
+
+**IMPORTANT PRINCIPLES:**
+- NO relative imports (from ..x import y) - use absolute imports from `services.xxx.data_schema`
+- Always use `by_alias=True` when serializing Pydantic models
+- Handle authentication headers manually (no `update_headers` method)
+- Use `do_*` prefix for methods to avoid name conflicts with attributes
+
+Supongamos una API de Tareas (TODOs).
+
+## 1. services/todo_app/data_schema.py
+
+```python
+from pydantic import BaseModel, Field
+from typing import Optional
+
+class TodoItem(BaseModel):
+    id: Optional[str] = None
+    title: str
+    completed: bool = False
+
+    class Config:
+        populate_by_name = True
+
+ENDPOINTS = {
+    "list": "/todos",
+    "create": "/todos",
+    "get": "/todos/{id}",
+    "update": "/todos/{id}",
+    "delete": "/todos/{id}"
+}
+```
+
+## 2. services/todo_app/todo_app_page.py
+
+```python
+from socialseed_e2e.core.base_page import BasePage
+from playwright.sync_api import APIResponse, APIRequestContext
+from services.todo_app.data_schema import TodoItem, ENDPOINTS
+
+class TodoAppPage(BasePage):
+    def __init__(self, base_url: str, **kwargs):
+        super().__init__(base_url=base_url, **kwargs)
+        self.created_todo_id = None  # Estado compartido
+        self.auth_token = None
+
+    def do_create_todo(self, item: TodoItem) -> APIResponse:
+        """Create a new todo item."""
+        return self.post(
+            ENDPOINTS["create"],
+            data=item.model_dump(by_alias=True, exclude={"id"})
+        )
+
+    def do_get_todo(self, todo_id: str) -> APIResponse:
+        """Retrieve a todo by ID."""
+        path = ENDPOINTS["get"].format(id=todo_id)
+        return self.get(path)
+
+    def do_delete_todo(self, todo_id: str) -> APIResponse:
+        """Delete a todo by ID."""
+        path = ENDPOINTS["delete"].format(id=todo_id)
+        return self.delete(path)
+
+    def do_authenticate(self, token: str) -> None:
+        """Set authentication token manually."""
+        self.auth_token = token
+        # Manually handle headers - don't use update_headers()
+        self.headers = {**self.headers, "Authorization": f"Bearer {token}"}
+```
+
+## 3. services/todo_app/modules/01_create_todo.py
+
+```python
+from services.todo_app.data_schema import TodoItem
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from services.todo_app.todo_app_page import TodoAppPage
+
+def run(page: 'TodoAppPage'):
+    print("STEP: Create Todo")
+
+    new_todo = TodoItem(title="Learn SocialSeed E2E", completed=False)
+
+    response = page.do_create_todo(new_todo)
+    assert response.ok, f"Failed to create todo: {response.status} - {response.text()}"
+
+    data = response.json()
+    assert data["title"] == new_todo.title, f"Title mismatch: expected {new_todo.title}, got {data.get('title')}"
+    assert "id" in data, "No 'id' field in response"
+
+    # Guardar ID para el siguiente paso
+    page.created_todo_id = data["id"]
+    print(f"✓ Created Todo with ID: {page.created_todo_id}")
+```
+
+## 4. services/todo_app/modules/02_get_todo.py
+
+```python
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from services.todo_app.todo_app_page import TodoAppPage
+
+def run(page: 'TodoAppPage'):
+    print("STEP: Get Todo")
+
+    # Recuperar ID del paso anterior
+    todo_id = page.created_todo_id
+    assert todo_id, "No created_todo_id found from previous step"
+
+    response = page.do_get_todo(todo_id)
+    assert response.ok, f"Failed to get todo: {response.status} - {response.text()}"
+
+    data = response.json()
+    assert data["id"] == todo_id, f"ID mismatch: expected {todo_id}, got {data.get('id')}"
+    print("✓ Todo retrieved successfully")
+```
+
+## 5. services/todo_app/modules/03_authenticated_request.py
+
+```python
+from services.todo_app.data_schema import TodoItem
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from services.todo_app.todo_app_page import TodoAppPage
+
+def run(page: 'TodoAppPage'):
+    print("STEP: Authenticated Request Example")
+
+    # Perform authentication and store token
+    auth_response = page.post("/auth/login", data={
+        "username": "test@example.com",
+        "password": "password123"
+    })
+    assert auth_response.ok, f"Authentication failed: {auth_response.status}"
+
+    token = auth_response.json().get("token")
+    assert token, "No token in authentication response"
+
+    # Manually set the authentication token
+    page.do_authenticate(token)
+
+    # Now make authenticated request
+    new_todo = TodoItem(title="Authenticated Todo", completed=False)
+
+    # Use by_alias=True when serializing
+    response = page.do_create_todo(new_todo)
+    assert response.ok, f"Failed to create todo: {response.status} - {response.text()}"
+
+    print("✓ Authenticated request successful")
+```

socialseed_e2e/templates/agent_docs/FRAMEWORK_CONTEXT.md.template

@@ -0,0 +1,55 @@
+# Contexto del Framework socialseed-e2e para Agentes de IA
+
+Este documento te proporciona el contexto necesario para trabajar con el framework `socialseed-e2e`. Tu objetivo es ayudar al desarrollador a crear pruebas end-to-end (E2E) para APIs REST de manera autónoma.
+
+## 1. Arquitectura del Framework
+
+El framework sigue una arquitectura hexagonal simplificada para desacoplar la lógica de prueba de la lógica del servicio.
+
+### Estructura de Directorios Clave
+
+```
+.
+├── e2e.conf                 # Configuración principal (URLs, timeouts)
+├── services/               # Directorio de definición de servicios
+│   └── <service-name>/     # Cada API/Microservicio tiene su carpeta
+│       ├── __init__.py
+│       ├── config.py       # Configuración específica del servicio
+│       ├── data_schema.py  # DTOs (Pydantic), Endpoints y Constantes
+│       ├── <name>_page.py  # Page Object Model (hereda de BasePage)
+│       └── modules/        # Tests individuales
+│           ├── 01_register_flow.py
+│           ├── 02_login_flow.py
+│           └── ...
+└── tests/                  # Tests generales o de integración del propio framework
+```
+
+## 2. Conceptos Principales
+
+### Service Page (Page Object)
+Cada servicio tiene una clase "Page" (ej. `UsersApiPage`) que hereda de `BasePage`.
+- **Responsabilidad**: Abstraer las llamadas HTTP.
+- **Ubicación**: `services/<service-name>/<name>_page.py`.
+- **Métodos**: Deben corresponder a acciones de negocio (ej. `register_user`, `get_profile`) y retornar `APIResponse` de Playwright.
+
+### Test Modules
+Los tests se dividen en archivos pequeños y numerados dentro de `services/<service-name>/modules/`.
+- **Naming**: `XX_description_flow.py` (ej. `01_register_flow.py`).
+- **Estructura**: Cada módulo debe tener una función `run(context)` o `run(page)`.
+- **Orden**: Se ejecutan secuencialmente según su numeración.
+- **Estado**: El estado se comparte a través de la instancia de la `Page`. Si el test 01 guarda un token en `page.auth_token`, el test 02 puede usarlo.
+
+### Data Schema
+- **Ubicación**: `services/<service-name>/data_schema.py`.
+- **Contenido**: Modelos Pydantic para request/response bodies y costantes de rutas.
+
+## 3. Tu Rol como Agente
+
+Cuando el usuario te pida "generar tests", debes:
+1. **Analizar** el código fuente del controlador REST que te provea el usuario.
+2. **Identificar** los endpoints, métodos HTTP, y estructuras de datos.
+3. **Mapear** estos endpoints a métodos en la `ServicePage`.
+4. **Generar** módulos de prueba secuenciales que cubran flujos lógicos (crear -> obtener -> actualizar -> borrar).
+
+---
+Lee `WORKFLOW_GENERATION.md` para instrucciones paso a paso sobre cómo generar código.