How josedev155/python-builder-pattern-and-pytest-example works
Identificación del tipo de proyecto y su propósito
• Este repositorio es un pequeño proyecto de ejemplo en Python que demuestra cómo aplicar el patrón creacional Builder dentro de tests con pytest. No es una aplicación cliente-servidor ni un sistema distribuido, sino un conjunto de scripts de prueba centrados en simplificar la creación de objetos de dominio (Invoice) y mantener los tests escalables y fáciles de mantener.
Análisis de la estructura de archivos
• Nivel raíz:
• README.md → Documentación y casos de uso.
• testWithoutBuilder.py → Test original que instancia directamente Invoice.
• testWithBuilder.py → Test mejorado que utiliza InvoiceBuilder.
• No hay carpetas adicionales (no hay frontend, backend o configuraciones de despliegue). Todo gira en torno a dos scripts de prueba y la definición de la entidad Invoice junto con su builder.
Puntos clave extraídos del README
• Dominio: la clase Invoice es un dataclass con múltiples atributos (id, product, quantity, price, city, etc.).
• Problema inicial: cada vez que se añade o elimina un campo en Invoice, hay que modificar todos los tests que crean instancias manualmente.
• Solución: introducir InvoiceBuilder con un estado base y métodos encadenables (with_price(), with_quantity(), etc.) para construir instancias de Invoice centradas únicamente en los valores que importan al test.
Componentes principales para el diagrama
A. Entidad de dominio
• Invoice (dataclass)
B. Componente Builder
• InvoiceBuilder
• constructor (__init__) crea un Invoice base con valores por defecto
• métodos with_*() que ajustan atributos específicos
• método build() que devuelve la instancia configurada
C. Módulos de prueba
• testWithoutBuilder.py
• testWithBuilder.py
D. Dependencias externas
• pytest (librería de test)
Relaciones e interacciones
• En testWithoutBuilder.py:
Test → instancia directa de Invoice → cálculo de suma → assert.
• En testWithBuilder.py:
Test → llama a InvoiceBuilder() → aplica with_*() (opcional) → build() → obtiene Invoice → cálculo de suma → assert.
• Ambos tests dependen de la definición de Invoice. El segundo test añade una capa intermedia (InvoiceBuilder) encargada de manejar la mutabilidad de la estructura de Invoice.
Patrón y principios de diseño
• Patrón Builder: separa la construcción compleja (o cambiante) de objetos (Invoice) de su representación, encapsulando valores por defecto y permitiendo personalizaciones vía métodos encadenables.
• Principio de una única responsabilidad: InvoiceBuilder sólo construye, los tests sólo verifican lógica de agregación.
Cómo dibujar el diagrama de arquitectura
• Usa rectángulos o cajas para cada componente:
[Invoice]
[InvoiceBuilder]
[testWithoutBuilder.py]
[testWithBuilder.py]
[pytest]
• Con flechas direccionales:
• Indica el flujo “construcción → cálculo → assert”.
• Azul para la entidad de dominio (Invoice).
• Verde para el builder.
• Naranja para los módulos de prueba.
• Gris o punteado para la librería externa (pytest).
• Etiqueta cada flecha con la acción principal:
• “new Invoice(…)”
• “build()”
• “with_price()/with_quantity()”
• “sum(…) & assert”
Guía rápida para el diagrama final
1. A la izquierda, ubica la entidad de dominio y el builder en un “módulo de modelo”:
[Invoice] ← [InvoiceBuilder]
2. A la derecha, coloca los dos scripts de test:
[testWithoutBuilder.py]
[testWithBuilder.py]
3. Encima o debajo, coloca la dependencia externa:
[pytest]
4. Flechas desde cada test a los módulos que usan:
testWithoutBuilder.py → Invoice
testWithBuilder.py → InvoiceBuilder → Invoice
Ambos tests → pytest
5. Usa colores:
• Entidad: celeste
• Builder: verde
• Tests: amarillo
• External: gris
6. Añade notas cortas:
• “Instancia manual”
• “Uso de patrón Builder”
Con este diagrama, cualquier ingeniero podrá ver de un vistazo: la estructura de pruebas original, la introducción del patrón Builder, la entidad central y su flujo de construcción y validación con pytest. Asegúrate de mostrar claramente los límites—qué parte corresponde al dominio (modelo), qué parte al builder y qué parte a la suite de pruebas—para que la arquitectura quede perfectamente documentada.