@qubiit/lmagent 2.5.0

package/workflows/testing-strategy.md

@@ -0,0 +1,296 @@
+---
+description: Workflow para testing completo de una aplicación
+level: 2
+personas: [qa-engineer, backend-engineer, frontend-engineer]
+---
+
+# Testing Strategy Workflow
+
+Este workflow define la estrategia de testing para el proyecto.
+
+## Pirámide de Tests
+
+```
+         ┌───────┐
+         │  E2E  │  Pocos, lentos, costosos
+        /─────────\
+       /  Integration\   Algunos, moderados
+      /───────────────\
+     /     Unit Tests   \  Muchos, rápidos, baratos
+    /─────────────────────\
+```
+
+---
+
+## Unit Tests
+
+### Qué testear
+- Funciones de utilidad
+- Lógica de negocio
+- Transformaciones de datos
+- Validaciones
+
+### Python (pytest)
+
+```python
+# tests/unit/test_utils.py
+import pytest
+from app.utils import calculate_discount
+
+class TestCalculateDiscount:
+    def test_percentage_discount(self):
+        result = calculate_discount(100, percentage=10)
+        assert result == 90
+    
+    def test_fixed_discount(self):
+        result = calculate_discount(100, fixed=15)
+        assert result == 85
+    
+    def test_negative_result_returns_zero(self):
+        result = calculate_discount(10, fixed=20)
+        assert result == 0
+    
+    @pytest.mark.parametrize("amount,percentage,expected", [
+        (100, 10, 90),
+        (50, 20, 40),
+        (0, 50, 0),
+    ])
+    def test_parametrized(self, amount, percentage, expected):
+        assert calculate_discount(amount, percentage) == expected
+```
+
+### TypeScript (Jest)
+
+```typescript
+// __tests__/utils.test.ts
+import { formatCurrency } from '../utils';
+
+describe('formatCurrency', () => {
+  it('formats positive numbers', () => {
+    expect(formatCurrency(1234.56)).toBe('$1,234.56');
+  });
+  
+  it('handles zero', () => {
+    expect(formatCurrency(0)).toBe('$0.00');
+  });
+  
+  it('formats negative numbers', () => {
+    expect(formatCurrency(-100)).toBe('-$100.00');
+  });
+});
+```
+
+---
+
+## Integration Tests
+
+### Qué testear
+- Endpoints API
+- Database queries
+- Service interactions
+- External API calls (mocked)
+
+### API Tests (pytest + httpx)
+
+```python
+# tests/integration/test_users_api.py
+import pytest
+from httpx import AsyncClient
+
+@pytest.fixture
+async def client(app):
+    async with AsyncClient(app=app, base_url="http://test") as client:
+        yield client
+
+class TestUsersAPI:
+    async def test_create_user(self, client):
+        response = await client.post("/api/users", json={
+            "email": "test@example.com",
+            "name": "Test User"
+        })
+        
+        assert response.status_code == 201
+        data = response.json()
+        assert data["email"] == "test@example.com"
+        assert "id" in data
+    
+    async def test_create_user_duplicate_email(self, client, existing_user):
+        response = await client.post("/api/users", json={
+            "email": existing_user.email,
+            "name": "Another User"
+        })
+        
+        assert response.status_code == 409
+```
+
+### Database Tests
+
+```python
+# tests/integration/test_user_repository.py
+class TestUserRepository:
+    async def test_create_and_find(self, db_session):
+        repo = UserRepository(db_session)
+        
+        # Create
+        user = await repo.create(UserCreate(email="test@example.com"))
+        
+        # Find
+        found = await repo.get_by_email("test@example.com")
+        
+        assert found is not None
+        assert found.id == user.id
+```
+
+---
+
+## E2E Tests
+
+### Qué testear
+- User flows críticos
+- Happy paths principales
+- Flujos de autenticación
+
+### Playwright
+
+```typescript
+// e2e/login.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Login flow', () => {
+  test('successful login', async ({ page }) => {
+    await page.goto('/login');
+    
+    await page.fill('input[name="email"]', 'user@example.com');
+    await page.fill('input[name="password"]', 'password123');
+    await page.click('button[type="submit"]');
+    
+    await expect(page).toHaveURL('/dashboard');
+    await expect(page.locator('text=Welcome')).toBeVisible();
+  });
+  
+  test('invalid credentials', async ({ page }) => {
+    await page.goto('/login');
+    
+    await page.fill('input[name="email"]', 'wrong@example.com');
+    await page.fill('input[name="password"]', 'wrong');
+    await page.click('button[type="submit"]');
+    
+    await expect(page.locator('text=Invalid credentials')).toBeVisible();
+  });
+});
+```
+
+---
+
+## Component Tests (Frontend)
+
+```tsx
+// __tests__/UserCard.test.tsx
+import { render, screen, fireEvent } from '@testing-library/react';
+import { UserCard } from '../UserCard';
+
+const mockUser = {
+  id: '1',
+  name: 'John Doe',
+  email: 'john@example.com',
+};
+
+describe('UserCard', () => {
+  it('renders user information', () => {
+    render(<UserCard user={mockUser} />);
+    
+    expect(screen.getByText('John Doe')).toBeInTheDocument();
+    expect(screen.getByText('john@example.com')).toBeInTheDocument();
+  });
+  
+  it('calls onEdit when edit button clicked', () => {
+    const onEdit = jest.fn();
+    render(<UserCard user={mockUser} onEdit={onEdit} />);
+    
+    fireEvent.click(screen.getByRole('button', { name: /edit/i }));
+    
+    expect(onEdit).toHaveBeenCalledWith(mockUser);
+  });
+});
+```
+
+---
+
+## Code Coverage
+
+### Objetivos
+
+| Tipo | Cobertura Mínima |
+|------|------------------|
+| Unit Tests | 80% |
+| Integration | Key paths |
+| E2E | Critical flows |
+
+### Comandos
+
+```bash
+# Python
+pytest --cov=app --cov-report=html
+
+# JavaScript
+npm test -- --coverage
+```
+
+---
+
+## Testing Checklist
+
+```markdown
+## Para cada PR
+- [ ] Unit tests para nueva lógica
+- [ ] Integration tests para nuevos endpoints
+- [ ] E2E tests si es flujo crítico
+- [ ] Coverage no disminuyó
+
+## Para refactoring
+- [ ] Tests existentes siguen pasando
+- [ ] No cambios a tests (salvo estructura)
+
+## Para bugs
+- [ ] Test que reproduce el bug
+- [ ] Fix hace pasar el test
+- [ ] Regression test agregado
+```
+
+---
+
+## Test Data
+
+### Fixtures (pytest)
+
+```python
+# conftest.py
+@pytest.fixture
+def sample_user():
+    return User(
+        id=uuid4(),
+        email="test@example.com",
+        name="Test User"
+    )
+
+@pytest.fixture
+async def db_user(db_session, sample_user):
+    db_session.add(sample_user)
+    await db_session.commit()
+    return sample_user
+```
+
+### Factories
+
+```python
+# tests/factories.py
+import factory
+
+class UserFactory(factory.Factory):
+    class Meta:
+        model = User
+    
+    id = factory.LazyFunction(uuid4)
+    email = factory.Sequence(lambda n: f"user{n}@example.com")
+    name = factory.Faker("name")
+```

package/workflows/third-party-integration.md

@@ -0,0 +1,277 @@
+---
+description: Workflow para integración con APIs de terceros
+level: 2
+personas: [backend-engineer, architect]
+---
+
+# Third-Party Integration Workflow
+
+Este workflow guía la integración segura con APIs de terceros.
+
+## Pre-requisitos
+
+1. Documentación de la API externa
+2. Credenciales de prueba
+3. Límites de rate conocidos
+
+---
+
+## Fase 1: Análisis
+
+### 1.1 Evaluar la API
+
+| Aspecto | Verificar |
+|---------|-----------|
+| Autenticación | API Key, OAuth, Bearer? |
+| Rate Limits | Requests por minuto/hora |
+| Formato | REST, GraphQL, SOAP |
+| Versioning | ¿La versión es estable? |
+| SLA | ¿Garantías de uptime? |
+
+### 1.2 Mapear Endpoints Necesarios
+
+```markdown
+| Endpoint | Método | Uso en nuestro sistema |
+|----------|--------|------------------------|
+| /users   | GET    | Sync usuarios          |
+| /orders  | POST   | Crear pedidos          |
+```
+
+### 1.3 Diseñar Abstracción
+
+```python
+# Interfaz abstracta para evitar vendor lock-in
+class PaymentProvider(Protocol):
+    async def create_payment(self, amount: Decimal) -> PaymentResult:
+        ...
+    
+    async def get_payment(self, payment_id: str) -> Payment:
+        ...
+```
+
+---
+
+## Fase 2: Implementación
+
+### 2.1 Configuración
+
+```python
+# config/settings.py
+class ThirdPartySettings(BaseSettings):
+    api_key: str
+    api_url: str = "https://api.example.com/v1"
+    timeout: int = 30
+    max_retries: int = 3
+    
+    class Config:
+        env_prefix = "THIRD_PARTY_"
+```
+
+```bash
+# .env
+THIRD_PARTY_API_KEY=sk_test_xxxx
+```
+
+### 2.2 Cliente HTTP
+
+```python
+# clients/third_party_client.py
+import httpx
+from tenacity import retry, wait_exponential, stop_after_attempt
+
+class ThirdPartyClient:
+    def __init__(self, settings: ThirdPartySettings):
+        self.settings = settings
+        self.client = httpx.AsyncClient(
+            base_url=settings.api_url,
+            headers={"Authorization": f"Bearer {settings.api_key}"},
+            timeout=settings.timeout,
+        )
+    
+    @retry(
+        wait=wait_exponential(min=1, max=10),
+        stop=stop_after_attempt(3)
+    )
+    async def request(self, method: str, path: str, **kwargs):
+        response = await self.client.request(method, path, **kwargs)
+        response.raise_for_status()
+        return response.json()
+    
+    async def get_user(self, user_id: str):
+        return await self.request("GET", f"/users/{user_id}")
+```
+
+### 2.3 Error Handling
+
+```python
+# exceptions/third_party.py
+class ThirdPartyError(Exception):
+    """Base error for third party integration"""
+
+class ThirdPartyRateLimitError(ThirdPartyError):
+    """Rate limit exceeded"""
+    
+class ThirdPartyAuthError(ThirdPartyError):
+    """Authentication failed"""
+
+# En el cliente
+async def request(self, method: str, path: str, **kwargs):
+    try:
+        response = await self.client.request(method, path, **kwargs)
+        response.raise_for_status()
+        return response.json()
+    except httpx.HTTPStatusError as e:
+        if e.response.status_code == 429:
+            raise ThirdPartyRateLimitError("Rate limit exceeded")
+        elif e.response.status_code == 401:
+            raise ThirdPartyAuthError("Invalid API key")
+        raise ThirdPartyError(f"API error: {e}")
+```
+
+### 2.4 Caching
+
+```python
+# services/cached_third_party.py
+from functools import lru_cache
+import redis
+
+redis_client = redis.Redis()
+
+async def get_user_cached(user_id: str) -> dict:
+    cache_key = f"third_party:user:{user_id}"
+    
+    # Check cache
+    cached = await redis_client.get(cache_key)
+    if cached:
+        return json.loads(cached)
+    
+    # Fetch from API
+    user = await client.get_user(user_id)
+    
+    # Cache for 1 hour
+    await redis_client.setex(cache_key, 3600, json.dumps(user))
+    
+    return user
+```
+
+---
+
+## Fase 3: Testing
+
+### 3.1 Mocking
+
+```python
+# tests/conftest.py
+import respx
+
+@pytest.fixture
+def mock_third_party():
+    with respx.mock:
+        respx.get("https://api.example.com/v1/users/123").mock(
+            return_value=httpx.Response(200, json={"id": "123", "name": "Test"})
+        )
+        yield
+```
+
+### 3.2 Test Unitarios
+
+```python
+# tests/test_third_party_client.py
+async def test_get_user(mock_third_party):
+    client = ThirdPartyClient(settings)
+    user = await client.get_user("123")
+    assert user["id"] == "123"
+
+async def test_rate_limit_handling(mock_third_party):
+    respx.get("https://api.example.com/v1/users/123").mock(
+        return_value=httpx.Response(429)
+    )
+    
+    with pytest.raises(ThirdPartyRateLimitError):
+        await client.get_user("123")
+```
+
+### 3.3 Integration Tests
+
+```python
+# tests/integration/test_third_party_real.py
+@pytest.mark.integration
+@pytest.mark.skipif(not os.getenv("THIRD_PARTY_API_KEY"), reason="No API key")
+async def test_real_api_connection():
+    """Test with real API (use sparingly)"""
+    client = ThirdPartyClient(settings)
+    # Use a safe, idempotent endpoint
+    result = await client.health_check()
+    assert result["status"] == "ok"
+```
+
+---
+
+## Fase 4: Monitoring
+
+### 4.1 Métricas
+
+```python
+from prometheus_client import Counter, Histogram
+
+third_party_requests = Counter(
+    'third_party_requests_total',
+    'Total requests to third party API',
+    ['method', 'endpoint', 'status']
+)
+
+third_party_latency = Histogram(
+    'third_party_request_duration_seconds',
+    'Request duration to third party API'
+)
+```
+
+### 4.2 Alertas
+
+```yaml
+# Prometheus alert rules
+groups:
+  - name: third_party
+    rules:
+      - alert: ThirdPartyHighErrorRate
+        expr: |
+          rate(third_party_requests_total{status=~"5.."}[5m]) 
+          / rate(third_party_requests_total[5m]) > 0.05
+        for: 5m
+        annotations:
+          summary: "High error rate with third party API"
+```
+
+---
+
+## Checklist
+
+```markdown
+## Integration: {nombre}
+
+### Seguridad
+- [ ] Credenciales en variables de entorno
+- [ ] No hardcoded secrets
+- [ ] Credenciales rotables
+
+### Reliability
+- [ ] Retry logic implementado
+- [ ] Timeout configurado
+- [ ] Circuit breaker (opcional)
+- [ ] Fallback strategy
+
+### Performance
+- [ ] Caching implementado
+- [ ] Rate limiting respetado
+- [ ] Connection pooling
+
+### Observability
+- [ ] Logging de requests/responses
+- [ ] Métricas expuestas
+- [ ] Alertas configuradas
+
+### Testing
+- [ ] Unit tests con mocks
+- [ ] Integration tests
+- [ ] Error scenarios cubiertos
+```