theus-cli 0.2.83 → 0.2.85

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

@@ -1,815 +0,0 @@
----
-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.