theus-cli-darwin-x64 0.2.84

package/vendor/theus-arsenal/skills/testing-python/SKILL.md

@@ -0,0 +1,815 @@
+---
+name: testing-python
+description: Estrategias de testing en Python con pytest, metodología TDD, fixtures, mocking, parametrización y requisitos de cobertura.
+---
+
+# Patrones de testing en Python
+
+Estrategias integrales de testing para aplicaciones Python usando pytest, metodología TDD y buenas prácticas.
+
+## Cuándo activar
+
+- Al escribir código Python nuevo (sigue TDD: rojo, verde, refactor)
+- Al diseñar suites de tests para proyectos Python
+- Al revisar la cobertura de tests de Python
+- Al configurar infraestructura de testing
+
+## Filosofía central de testing
+
+### Desarrollo guiado por tests (TDD)
+
+Sigue siempre el ciclo TDD:
+
+1. **ROJO**: escribe un test que falle para el comportamiento deseado
+2. **VERDE**: escribe el código mínimo para que el test pase
+3. **REFACTOR**: mejora el código manteniendo los tests en verde
+
+```python
+# Paso 1: escribir el test que falla (ROJO)
+def test_add_numbers():
+    result = add(2, 3)
+    assert result == 5
+
+# Paso 2: escribir la implementación mínima (VERDE)
+def add(a, b):
+    return a + b
+
+# Paso 3: refactorizar si hace falta (REFACTOR)
+```
+
+### Requisitos de cobertura
+
+- **Objetivo**: 80%+ de cobertura de código
+- **Rutas críticas**: se exige 100% de cobertura
+- Usa `pytest --cov` para medir la cobertura
+
+```bash
+pytest --cov=mypackage --cov-report=term-missing --cov-report=html
+```
+
+## Fundamentos de pytest
+
+### Estructura básica de un test
+
+```python
+import pytest
+
+def test_addition():
+    """Prueba la suma básica."""
+    assert 2 + 2 == 4
+
+def test_string_uppercase():
+    """Prueba pasar una cadena a mayúsculas."""
+    text = "hello"
+    assert text.upper() == "HELLO"
+
+def test_list_append():
+    """Prueba el append de listas."""
+    items = [1, 2, 3]
+    items.append(4)
+    assert 4 in items
+    assert len(items) == 4
+```
+
+### Aserciones
+
+```python
+# Igualdad
+assert result == expected
+
+# Desigualdad
+assert result != unexpected
+
+# Veracidad
+assert result  # Verdadero (truthy)
+assert not result  # Falso (falsy)
+assert result is True  # Exactamente True
+assert result is False  # Exactamente False
+assert result is None  # Exactamente None
+
+# Pertenencia
+assert item in collection
+assert item not in collection
+
+# Comparaciones
+assert result > 0
+assert 0 <= result <= 100
+
+# Comprobación de tipos
+assert isinstance(result, str)
+
+# Prueba de excepciones (enfoque preferido)
+with pytest.raises(ValueError):
+    raise ValueError("error message")
+
+# Comprobar el mensaje de la excepción
+with pytest.raises(ValueError, match="invalid input"):
+    raise ValueError("invalid input provided")
+
+# Comprobar atributos de la excepción
+with pytest.raises(ValueError) as exc_info:
+    raise ValueError("error message")
+assert str(exc_info.value) == "error message"
+```
+
+## Fixtures
+
+### Uso básico de fixtures
+
+```python
+import pytest
+
+@pytest.fixture
+def sample_data():
+    """Fixture que provee datos de ejemplo."""
+    return {"name": "Alice", "age": 30}
+
+def test_sample_data(sample_data):
+    """Test que usa la fixture."""
+    assert sample_data["name"] == "Alice"
+    assert sample_data["age"] == 30
+```
+
+### Fixture con setup/teardown
+
+```python
+@pytest.fixture
+def database():
+    """Fixture con preparación y limpieza."""
+    # Preparación
+    db = Database(":memory:")
+    db.create_tables()
+    db.insert_test_data()
+
+    yield db  # Se entrega al test
+
+    # Limpieza
+    db.close()
+
+def test_database_query(database):
+    """Prueba operaciones de base de datos."""
+    result = database.query("SELECT * FROM users")
+    assert len(result) > 0
+```
+
+### Alcances (scopes) de fixtures
+
+```python
+# Alcance function (por defecto) — se ejecuta en cada test
+@pytest.fixture
+def temp_file():
+    with open("temp.txt", "w") as f:
+        yield f
+    os.remove("temp.txt")
+
+# Alcance module — se ejecuta una vez por módulo
+@pytest.fixture(scope="module")
+def module_db():
+    db = Database(":memory:")
+    db.create_tables()
+    yield db
+    db.close()
+
+# Alcance session — se ejecuta una vez por sesión de tests
+@pytest.fixture(scope="session")
+def shared_resource():
+    resource = ExpensiveResource()
+    yield resource
+    resource.cleanup()
+```
+
+### Fixture con parámetros
+
+```python
+@pytest.fixture(params=[1, 2, 3])
+def number(request):
+    """Fixture parametrizada."""
+    return request.param
+
+def test_numbers(number):
+    """El test corre 3 veces, una por cada parámetro."""
+    assert number > 0
+```
+
+### Uso de varias fixtures
+
+```python
+@pytest.fixture
+def user():
+    return User(id=1, name="Alice")
+
+@pytest.fixture
+def admin():
+    return User(id=2, name="Admin", role="admin")
+
+def test_user_admin_interaction(user, admin):
+    """Test que usa varias fixtures."""
+    assert admin.can_manage(user)
+```
+
+### Fixtures autouse
+
+```python
+@pytest.fixture(autouse=True)
+def reset_config():
+    """Se ejecuta automáticamente antes de cada test."""
+    Config.reset()
+    yield
+    Config.cleanup()
+
+def test_without_fixture_call():
+    # reset_config se ejecuta automáticamente
+    assert Config.get_setting("debug") is False
+```
+
+### conftest.py para fixtures compartidas
+
+```python
+# tests/conftest.py
+import pytest
+
+@pytest.fixture
+def client():
+    """Fixture compartida por todos los tests."""
+    app = create_app(testing=True)
+    with app.test_client() as client:
+        yield client
+
+@pytest.fixture
+def auth_headers(client):
+    """Genera cabeceras de autenticación para probar la API."""
+    response = client.post("/api/login", json={
+        "username": "test",
+        "password": "test"
+    })
+    token = response.json["token"]
+    return {"Authorization": f"Bearer {token}"}
+```
+
+## Parametrización
+
+### Parametrización básica
+
+```python
+@pytest.mark.parametrize("input,expected", [
+    ("hello", "HELLO"),
+    ("world", "WORLD"),
+    ("PyThOn", "PYTHON"),
+])
+def test_uppercase(input, expected):
+    """El test corre 3 veces con distintas entradas."""
+    assert input.upper() == expected
+```
+
+### Varios parámetros
+
+```python
+@pytest.mark.parametrize("a,b,expected", [
+    (2, 3, 5),
+    (0, 0, 0),
+    (-1, 1, 0),
+    (100, 200, 300),
+])
+def test_add(a, b, expected):
+    """Prueba la suma con múltiples entradas."""
+    assert add(a, b) == expected
+```
+
+### Parametrizar con IDs
+
+```python
+@pytest.mark.parametrize("input,expected", [
+    ("valid@email.com", True),
+    ("invalid", False),
+    ("@no-domain.com", False),
+], ids=["valid-email", "missing-at", "missing-domain"])
+def test_email_validation(input, expected):
+    """Prueba la validación de emails con IDs de test legibles."""
+    assert is_valid_email(input) is expected
+```
+
+### Fixtures parametrizadas
+
+```python
+@pytest.fixture(params=["sqlite", "postgresql", "mysql"])
+def db(request):
+    """Prueba contra varios backends de base de datos."""
+    if request.param == "sqlite":
+        return Database(":memory:")
+    elif request.param == "postgresql":
+        return Database("postgresql://localhost/test")
+    elif request.param == "mysql":
+        return Database("mysql://localhost/test")
+
+def test_database_operations(db):
+    """El test corre 3 veces, una por cada base de datos."""
+    result = db.query("SELECT 1")
+    assert result is not None
+```
+
+## Marcadores y selección de tests
+
+### Marcadores personalizados
+
+```python
+# Marcar tests lentos
+@pytest.mark.slow
+def test_slow_operation():
+    time.sleep(5)
+
+# Marcar tests de integración
+@pytest.mark.integration
+def test_api_integration():
+    response = requests.get("https://api.example.com")
+    assert response.status_code == 200
+
+# Marcar tests unitarios
+@pytest.mark.unit
+def test_unit_logic():
+    assert calculate(2, 3) == 5
+```
+
+### Ejecutar tests específicos
+
+```bash
+# Ejecutar solo los tests rápidos
+pytest -m "not slow"
+
+# Ejecutar solo los tests de integración
+pytest -m integration
+
+# Ejecutar tests de integración o lentos
+pytest -m "integration or slow"
+
+# Ejecutar tests marcados como unit pero no slow
+pytest -m "unit and not slow"
+```
+
+### Configurar marcadores en pytest.ini
+
+```ini
+[pytest]
+markers =
+    slow: marca los tests lentos
+    integration: marca los tests de integración
+    unit: marca los tests unitarios
+    django: marca los tests que requieren Django
+```
+
+## Mocking y patching
+
+### Mockear funciones
+
+```python
+from unittest.mock import patch, Mock
+
+@patch("mypackage.external_api_call")
+def test_with_mock(api_call_mock):
+    """Test con la API externa mockeada."""
+    api_call_mock.return_value = {"status": "success"}
+
+    result = my_function()
+
+    api_call_mock.assert_called_once()
+    assert result["status"] == "success"
+```
+
+### Mockear valores de retorno
+
+```python
+@patch("mypackage.Database.connect")
+def test_database_connection(connect_mock):
+    """Test con la conexión a base de datos mockeada."""
+    connect_mock.return_value = MockConnection()
+
+    db = Database()
+    db.connect()
+
+    connect_mock.assert_called_once_with("localhost")
+```
+
+### Mockear excepciones
+
+```python
+@patch("mypackage.api_call")
+def test_api_error_handling(api_call_mock):
+    """Prueba el manejo de errores con una excepción mockeada."""
+    api_call_mock.side_effect = ConnectionError("Network error")
+
+    with pytest.raises(ConnectionError):
+        api_call()
+
+    api_call_mock.assert_called_once()
+```
+
+### Mockear context managers
+
+```python
+@patch("builtins.open", new_callable=mock_open)
+def test_file_reading(mock_file):
+    """Prueba la lectura de archivos con open mockeado."""
+    mock_file.return_value.read.return_value = "file content"
+
+    result = read_file("test.txt")
+
+    mock_file.assert_called_once_with("test.txt", "r")
+    assert result == "file content"
+```
+
+### Uso de autospec
+
+```python
+@patch("mypackage.DBConnection", autospec=True)
+def test_autospec(db_mock):
+    """Test con autospec para detectar mal uso de la API."""
+    db = db_mock.return_value
+    db.query("SELECT * FROM users")
+
+    # Esto fallaría si DBConnection no tuviera el método query
+    db_mock.assert_called_once()
+```
+
+### Mockear instancias de clases
+
+```python
+class TestUserService:
+    @patch("mypackage.UserRepository")
+    def test_create_user(self, repo_mock):
+        """Prueba la creación de usuarios con el repositorio mockeado."""
+        repo_mock.return_value.save.return_value = User(id=1, name="Alice")
+
+        service = UserService(repo_mock.return_value)
+        user = service.create_user(name="Alice")
+
+        assert user.name == "Alice"
+        repo_mock.return_value.save.assert_called_once()
+```
+
+### Mockear propiedades
+
+```python
+@pytest.fixture
+def mock_config():
+    """Crea un mock con una propiedad."""
+    config = Mock()
+    type(config).debug = PropertyMock(return_value=True)
+    type(config).api_key = PropertyMock(return_value="test-key")
+    return config
+
+def test_with_mock_config(mock_config):
+    """Test con propiedades de configuración mockeadas."""
+    assert mock_config.debug is True
+    assert mock_config.api_key == "test-key"
+```
+
+## Testing de código asíncrono
+
+### Tests async con pytest-asyncio
+
+```python
+import pytest
+
+@pytest.mark.asyncio
+async def test_async_function():
+    """Prueba una función async."""
+    result = await async_add(2, 3)
+    assert result == 5
+
+@pytest.mark.asyncio
+async def test_async_with_fixture(async_client):
+    """Test async con fixture async."""
+    response = await async_client.get("/api/users")
+    assert response.status_code == 200
+```
+
+### Fixture async
+
+```python
+@pytest.fixture
+async def async_client():
+    """Fixture async que provee un cliente de pruebas async."""
+    app = create_app()
+    async with app.test_client() as client:
+        yield client
+
+@pytest.mark.asyncio
+async def test_api_endpoint(async_client):
+    """Test que usa la fixture async."""
+    response = await async_client.get("/api/data")
+    assert response.status_code == 200
+```
+
+### Mockear funciones async
+
+```python
+@pytest.mark.asyncio
+@patch("mypackage.async_api_call")
+async def test_async_mock(api_call_mock):
+    """Prueba una función async con mock."""
+    api_call_mock.return_value = {"status": "ok"}
+
+    result = await my_async_function()
+
+    api_call_mock.assert_awaited_once()
+    assert result["status"] == "ok"
+```
+
+## Testing de excepciones
+
+### Probar excepciones esperadas
+
+```python
+def test_divide_by_zero():
+    """Comprueba que dividir por cero lanza ZeroDivisionError."""
+    with pytest.raises(ZeroDivisionError):
+        divide(10, 0)
+
+def test_custom_exception():
+    """Prueba una excepción personalizada con mensaje."""
+    with pytest.raises(ValueError, match="invalid input"):
+        validate_input("invalid")
+```
+
+### Probar atributos de excepciones
+
+```python
+def test_exception_with_details():
+    """Prueba una excepción con atributos personalizados."""
+    with pytest.raises(CustomError) as exc_info:
+        raise CustomError("error", code=400)
+
+    assert exc_info.value.code == 400
+    assert "error" in str(exc_info.value)
+```
+
+## Testing de efectos secundarios
+
+### Probar operaciones con archivos
+
+```python
+import tempfile
+import os
+
+def test_file_processing():
+    """Prueba el procesamiento de archivos con archivo temporal."""
+    with tempfile.NamedTemporaryFile(mode='w', delete=False, suffix='.txt') as f:
+        f.write("test content")
+        temp_path = f.name
+
+    try:
+        result = process_file(temp_path)
+        assert result == "processed: test content"
+    finally:
+        os.unlink(temp_path)
+```
+
+### Probar con la fixture tmp_path de pytest
+
+```python
+def test_with_tmp_path(tmp_path):
+    """Test que usa la fixture integrada de rutas temporales de pytest."""
+    test_file = tmp_path / "test.txt"
+    test_file.write_text("hello world")
+
+    result = process_file(str(test_file))
+    assert result == "hello world"
+    # tmp_path se limpia automáticamente
+```
+
+### Probar con la fixture tmpdir
+
+```python
+def test_with_tmpdir(tmpdir):
+    """Test que usa la fixture tmpdir de pytest."""
+    test_file = tmpdir.join("test.txt")
+    test_file.write("data")
+
+    result = process_file(str(test_file))
+    assert result == "data"
+```
+
+## Organización de los tests
+
+### Estructura de directorios
+
+```
+tests/
+├── conftest.py                 # Fixtures compartidas
+├── __init__.py
+├── unit/                       # Tests unitarios
+│   ├── __init__.py
+│   ├── test_models.py
+│   ├── test_utils.py
+│   └── test_services.py
+├── integration/                # Tests de integración
+│   ├── __init__.py
+│   ├── test_api.py
+│   └── test_database.py
+└── e2e/                        # Tests end-to-end
+    ├── __init__.py
+    └── test_user_flow.py
+```
+
+### Clases de tests
+
+```python
+class TestUserService:
+    """Agrupa tests relacionados en una clase."""
+
+    @pytest.fixture(autouse=True)
+    def setup(self):
+        """La preparación corre antes de cada test de esta clase."""
+        self.service = UserService()
+
+    def test_create_user(self):
+        """Prueba la creación de usuarios."""
+        user = self.service.create_user("Alice")
+        assert user.name == "Alice"
+
+    def test_delete_user(self):
+        """Prueba la eliminación de usuarios."""
+        user = User(id=1, name="Bob")
+        self.service.delete_user(user)
+        assert not self.service.user_exists(1)
+```
+
+## Buenas prácticas
+
+### SÍ
+
+- **Sigue TDD**: escribe los tests antes que el código (rojo-verde-refactor)
+- **Prueba una sola cosa**: cada test debe verificar un único comportamiento
+- **Usa nombres descriptivos**: `test_user_login_with_invalid_credentials_fails`
+- **Usa fixtures**: elimina la duplicación con fixtures
+- **Mockea las dependencias externas**: no dependas de servicios externos
+- **Prueba casos límite**: entradas vacías, valores None, condiciones de frontera
+- **Apunta a 80%+ de cobertura**: enfócate en las rutas críticas
+- **Mantén los tests rápidos**: usa marcadores para separar los tests lentos
+
+### NO
+
+- **No pruebes la implementación**: prueba el comportamiento, no los detalles internos
+- **No uses condicionales complejos en los tests**: mantén los tests simples
+- **No ignores los fallos de tests**: todos los tests deben pasar
+- **No pruebes código de terceros**: confía en que las librerías funcionan
+- **No compartas estado entre tests**: los tests deben ser independientes
+- **No captures excepciones en los tests**: usa `pytest.raises`
+- **No uses sentencias print**: usa aserciones y la salida de pytest
+- **No escribas tests demasiado frágiles**: evita mocks excesivamente específicos
+
+## Patrones comunes
+
+### Probar endpoints de API (FastAPI/Flask)
+
+```python
+@pytest.fixture
+def client():
+    app = create_app(testing=True)
+    return app.test_client()
+
+def test_get_user(client):
+    response = client.get("/api/users/1")
+    assert response.status_code == 200
+    assert response.json["id"] == 1
+
+def test_create_user(client):
+    response = client.post("/api/users", json={
+        "name": "Alice",
+        "email": "alice@example.com"
+    })
+    assert response.status_code == 201
+    assert response.json["name"] == "Alice"
+```
+
+### Probar operaciones de base de datos
+
+```python
+@pytest.fixture
+def db_session():
+    """Crea una sesión de base de datos de pruebas."""
+    session = Session(bind=engine)
+    session.begin_nested()
+    yield session
+    session.rollback()
+    session.close()
+
+def test_create_user(db_session):
+    user = User(name="Alice", email="alice@example.com")
+    db_session.add(user)
+    db_session.commit()
+
+    retrieved = db_session.query(User).filter_by(name="Alice").first()
+    assert retrieved.email == "alice@example.com"
+```
+
+### Probar métodos de clases
+
+```python
+class TestCalculator:
+    @pytest.fixture
+    def calculator(self):
+        return Calculator()
+
+    def test_add(self, calculator):
+        assert calculator.add(2, 3) == 5
+
+    def test_divide_by_zero(self, calculator):
+        with pytest.raises(ZeroDivisionError):
+            calculator.divide(10, 0)
+```
+
+## Configuración de pytest
+
+### pytest.ini
+
+```ini
+[pytest]
+testpaths = tests
+python_files = test_*.py
+python_classes = Test*
+python_functions = test_*
+addopts =
+    --strict-markers
+    --disable-warnings
+    --cov=mypackage
+    --cov-report=term-missing
+    --cov-report=html
+markers =
+    slow: marca los tests lentos
+    integration: marca los tests de integración
+    unit: marca los tests unitarios
+```
+
+### pyproject.toml
+
+```toml
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = [
+    "--strict-markers",
+    "--cov=mypackage",
+    "--cov-report=term-missing",
+    "--cov-report=html",
+]
+markers = [
+    "slow: marca los tests lentos",
+    "integration: marca los tests de integración",
+    "unit: marca los tests unitarios",
+]
+```
+
+## Ejecutar los tests
+
+```bash
+# Ejecutar todos los tests
+pytest
+
+# Ejecutar un archivo específico
+pytest tests/test_utils.py
+
+# Ejecutar un test específico
+pytest tests/test_utils.py::test_function
+
+# Ejecutar con salida detallada
+pytest -v
+
+# Ejecutar con cobertura
+pytest --cov=mypackage --cov-report=html
+
+# Ejecutar solo los tests rápidos
+pytest -m "not slow"
+
+# Ejecutar hasta el primer fallo
+pytest -x
+
+# Ejecutar y detenerse tras N fallos
+pytest --maxfail=3
+
+# Ejecutar los últimos tests fallidos
+pytest --lf
+
+# Ejecutar tests por patrón
+pytest -k "test_user"
+
+# Ejecutar con depurador al fallar
+pytest --pdb
+```
+
+## Referencia rápida
+
+| Patrón | Uso |
+|---------|-------|
+| `pytest.raises()` | Probar excepciones esperadas |
+| `@pytest.fixture()` | Crear fixtures de test reutilizables |
+| `@pytest.mark.parametrize()` | Ejecutar tests con múltiples entradas |
+| `@pytest.mark.slow` | Marcar tests lentos |
+| `pytest -m "not slow"` | Omitir tests lentos |
+| `@patch()` | Mockear funciones y clases |
+| Fixture `tmp_path` | Directorio temporal automático |
+| `pytest --cov` | Generar reporte de cobertura |
+| `assert` | Aserciones simples y legibles |
+
+**Recuerda**: los tests también son código. Mantenlos limpios, legibles y mantenibles. Los buenos tests atrapan bugs; los grandes tests los previenen.