Demostración de la Fase 2: reglas sobre datos, suite repetible y evidencia¶
Todo esto se hace en un Oracle local desechable (Docker en su PC). No use la VM de Azure ni una base real: el escenario carga y modifica datos de demostración.
1. Qué cambia respecto a un SELECT aislado¶
Una persona puede definir reglas sobre sus datos, agruparlas en una suite y repetirla con un clic. Cada ejecución guarda la evidencia (qué se esperaba, qué se obtuvo, estado, fecha) en el historial.
Hay tres formas de comprobar el resultado de una consulta; no son lo mismo:
| Validación | Qué compara | Ejemplo | Resultado |
|---|---|---|---|
ROW_COUNT (cantidad de filas) |
Cuántas filas devuelve la consulta | SELECT ID FROM T WHERE ACTIVE = 1 esperando 4 |
PASS si devuelve 4 filas |
SCALAR_VALUE (valor que devuelve la consulta) |
El valor de la primera columna de la única fila | SELECT COUNT(*) FROM T WHERE NAME IS NULL esperando 0 |
PASS si el número calculado es 0 |
EXISTS (existencia) |
Si devuelve al menos una fila (true) o ninguna (false) |
SELECT ID FROM T WHERE ID = 3 esperando true |
PASS si existe |
La confusión que se corrigió: un COUNT(*) siempre devuelve 1 fila. Con ROW_COUNT = 1 esa consulta pasa siempre, aunque el número que calcula sea 3 o 0. Para comparar el número hay que usar SCALAR_VALUE. La pantalla «Inicio» avisa cuando detecta COUNT(...) con «cantidad de filas» y ofrece cambiar a «valor», y las explicaciones de los resultados lo aclaran.
SCALAR_VALUE exige exactamente una fila (0 filas o varias dan FAIL, con explicación), compara números como números (0, 0.0 y 00 son iguales) y el texto de forma exacta; NULL representa el valor nulo. No está disponible en ambientes PRODUCTION, porque allí las filas se ocultan: se rechaza antes de ejecutar y se explica por qué.
2. Datos y reglas de demostración¶
La tabla ya existía: FRAMEWORK_TEST_ITEMS (ID NUMBER PK, NAME VARCHAR2(100) NOT NULL, ACTIVE NUMBER(1) DEFAULT 1 NOT NULL), creada por infra/oracle/init/001_test_schema.sh vacía. Los datos de ejemplo los carga infra/oracle/demo/seed_demo_data.sql (5 productos: Cuaderno, Lapicero, Regla, Borrador inactivo, Tijera).
Suite «Demo: reglas de calidad de FRAMEWORK_TEST_ITEMS» (todas deben pasar con esos datos):
| Regla | Validación | Esperado |
|---|---|---|
Hay 5 productos registrados (COUNT(*)) |
valor | 5 |
No hay productos sin nombre (WHERE TRIM(NAME) IS NULL) |
valor | 0 |
ACTIVE solo vale 0 o 1 (WHERE ACTIVE NOT IN (0, 1)) |
valor | 0 |
| Hay 4 productos activos | valor | 4 |
| Existe el producto con ID 3 | existencia | true |
Suite «Demo: ejemplos de FAIL y ERROR (intencionales)»: se esperan 6 productos (hay 5 → FAIL) y una consulta sobre una tabla inexistente (ORA-00942 → ERROR).
3. Reproducirlo en su PC (Windows, PowerShell)¶
Todos los comandos se ejecutan desde framework-pruebas-sql/. No se tocan sus otros contenedores ni volúmenes.
3.1 Oracle desechable¶
Copy-Item .env.oracle.example .env.oracle # y cambie las dos contraseñas por valores propios
cd infra\oracle
docker compose up -d
docker compose ps # espere "healthy" (1 a 3 minutos)
cd ..\..
.sh deben tener finales de línea LF para ejecutarse dentro del contenedor; el repositorio lo fuerza con .gitattributes. Si su copia es anterior, vuelva a clonar o convierta infra\oracle\init\001_test_schema.sh a LF.
3.2 Cargar los datos de demostración¶
Get-Content infra\oracle\demo\seed_demo_data.sql | docker exec -i framework_oracle_db bash -c 'sqlplus -s FRAMEWORK_TEST/"$FRAMEWORK_TEST_PASSWORD"@//localhost:1521/FREEPDB1'
Datos de demostracion cargados: 5 productos, 4 activos. El script es idempotente: sirve también para restaurar los datos. (En bash: docker exec -i framework_oracle_db bash -c '…' < infra/oracle/demo/seed_demo_data.sql.)
La contraseña no se escribe en la línea de comandos: se lee de la variable de entorno del propio contenedor.
3.3 Aplicación¶
python -m venv venv ; .\venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --port 8001
http://127.0.0.1:8001/ui/.
3.4 Recorrido en la interfaz¶
- En Inicio → Conectar: «Nueva conexión» con host
localhost, puerto1521, servicioFREEPDB1, usuarioFRAMEWORK_TEST, ambienteTEST; escriba la contraseña (la que puso en.env.oracle). - Una comprobación suelta: elija «Contar los registros de la tabla de demostración» (valor 5) → Ejecutar → PASS. Cambie el esperado a 4 → FAIL («esperabas 4 y devolvió 5»). Escriba
SELECT * FROM TABLA_QUE_NO_EXISTE→ ERROR (ORA-00942). - La confusión de COUNT: elija «Cantidad de filas…» con
SELECT COUNT(*) FROM FRAMEWORK_TEST_ITEMSy esperado 1: aparece el aviso azul y, tras ejecutar, la nota explica que se contó una fila, no el número. - Suite repetible: «Cargar las suites de demostración» → «Ejecutar la suite de reglas» → 5 PASS, con regla, esperado, obtenido y motivo. «Ejecutar de nuevo» repite sin reconstruir nada. «Ver un ejemplo de FAIL y ERROR» muestra los otros dos estados.
- Provocar un FAIL real y repararlo:
Vuelva a ejecutar la suite: «ACTIVE solo vale 0 o 1» da FAIL (obtuvo 1). Restaure con el script del paso 3.2 y ejecútela otra vez: 5 PASS. En Historial quedan todas las ejecuciones.
"UPDATE FRAMEWORK_TEST_ITEMS SET ACTIVE = 7 WHERE ID = 4;`nCOMMIT;`nEXIT" | docker exec -i framework_oracle_db bash -c 'sqlplus -s FRAMEWORK_TEST/"$FRAMEWORK_TEST_PASSWORD"@//localhost:1521/FREEPDB1'
4. Verificación automática contra Oracle (SELECT, INSERT con rollback, DROP rechazado)¶
Se prueba contra el Oracle desechable, consultando desde una conexión independiente. Defina las variables solo en esa sesión de PowerShell:
$env:RUN_ORACLE_TESTS = "1"; $env:ORACLE_HOST = "127.0.0.1"; $env:ORACLE_PORT = "1521"; $env:ORACLE_SERVICE = "FREEPDB1"
$env:FRAMEWORK_TEST_PASSWORD = "<la de .env.oracle>"
$env:ORACLE_PWD = "<contraseña de SYS del Oracle desechable>" # solo para crear las cuentas de privilegios mínimos
python -m pytest -m oracle_integration -v -s
localhost o loopback) o de CI. Con otro ORACLE_HOST se omiten sin conectar y explican por qué. Si de verdad es un Oracle desechable remoto, defina $env:ORACLE_TESTS_CONFIRM_DESTRUCTIVE_HOST = "<nombre exacto del host>" (no existe un comodín). El script scripts/db/liquibase_demo.sh aplica la misma regla cuando se pide el contexto demo (que borra y recarga la tabla); con LB_CONTEXTS=esquema no hace falta confirmación. -s muestra las líneas [EVIDENCIA …]. Sin ORACLE_PWD las pruebas de privilegios mínimos se omiten (no cuentan como aprobadas).
Qué comprueban:
- INSERT en TEST con ROLLBACK: cuenta FW_TEST_MIN (solo CREATE SESSION + SELECT, INSERT sobre FW_OWNER.CANARY). Filas antes = 3 → la aplicación ejecuta el INSERT (rowcount 1, rollback_applied = True) → filas después = 3 y 0 filas con el ID insertado, medido con otra conexión. Un control negativo (un INSERT + COMMIT fuera de la aplicación) demuestra que la medición sí detecta una fila que permanece.
- DROP rechazado: DROP TABLE, TRUNCATE, ALTER y «dos sentencias en una» terminan en ERROR («Rechazado…») con 0 conexiones abiertas a Oracle; la tabla sigue existiendo con sus 3 filas. La cuenta no tiene DROP/DELETE/UPDATE/ALTER ni roles (se comprueba en el diccionario de datos). No se ejecuta ningún DROP real.
- Suite: 5 PASS → dato roto → 4 PASS + 1 FAIL → dato corregido → 5 PASS; 15 registros en el historial.
Pruebas sin Oracle (Oracle simulado): python -m pytest -m "not oracle_integration". Son pruebas de lógica y de interfaz; no sustituyen a las de Oracle real.
5. Limitaciones (importante)¶
- El rollback no es una garantía universal. Funciona aquí porque la sentencia es un
INSERT/UPDATE/DELETEsimple, sinCOMMITimplícito. No revierte, por ejemplo: el avance de una secuencia (NEXTVAL), lo que haga un trigger o función con transacción autónoma, llamadas a paquetes que escriban fuera de la transacción (UTL_*,DBMS_*, enlaces a otras bases) ni, por supuesto, DDL (que Oracle confirma solo; por eso se bloquea). El análisis de la sentencia es léxico (sqlparse): para entornos reales hay que usar cuentas Oracle de privilegios mínimos. - Las pruebas de privilegios mínimos demuestran el comportamiento con esas cuentas en Oracle Free 23ai en Docker; no certifican otras versiones ni configuraciones.
- Los datos de demostración y las suites son de ejemplo. Las reglas esperan exactamente los datos de
seed_demo_data.sql; las pruebasoracle_integrationexistentes (test_oracle_integration.py) vacían y recarganFRAMEWORK_TEST_ITEMS; vuelva a ejecutar el paso 3.2 después de correrlas. SCALAR_VALUEno existe en PRODUCTION (filas ocultas).- Las capturas y resultados de esta demostración provienen de un Oracle local desechable, no de la VM de Azure.
6. Qué guardar como evidencia¶
- Captura de «Inicio» con una comprobación de valor (PASS) y otra FAIL con la explicación.
- Captura del aviso de
COUNT(...)con «cantidad de filas» y de la nota posterior. - Captura de la suite de reglas: 5 PASS con regla / esperado / obtenido.
- Captura de la suite tras provocar el dato inválido (1 FAIL) y tras repararlo (5 PASS), y del historial.
- Salida de
pytest -m oracle_integration -v -scon las líneas[EVIDENCIA INSERT],[EVIDENCIA DDL]y[EVIDENCIA SUITE].