Épica F — Ambientes de prueba

Estado: Borrador · Última actualización: 2026-08-24 · Índice: README

Cubre el registro y la preparación de un ambiente de prueba, con dos invariantes: las credenciales viven solo como referencia a un vault —nunca su valor— y el ambiente no se versiona, su historial son los snapshots inmutables que capturan los ciclos. Reglas de negocio del bloque: RN-012 y RN-026 a RN-030.

HU-014 — Registrar y preparar un ambiente de prueba

Épica: F · Ambientes de prueba · Deriva de: CU-011 · Cubre: RF-057–RF-067 · Reglas: RN-012, RN-026, RN-027, RN-028, RN-029, RN-030 · Decisiones: DEC-026, DEC-046 · Estado: Borrador

Historia

Como QA, quiero registrar un ambiente con todo lo necesario para ejecutar el plan y reproducir la ejecución después, para que cualquiera pueda probar sobre una configuración conocida y ningún fallo quede sin poder atribuirse a cómo estaba el ambiente.

Objetivo / valor. Dejar por escrito accesos, conexiones, configuración, datos y dependencias, sin guardar jamás el valor de un secreto, y con un checklist de readiness que advierte pero no frena. El registro no se versiona: su rastro histórico son los snapshots que toman los ciclos.

Alcance

• Dentro: registro y edición del ambiente, tipificación, datos de acceso, credenciales

como referencia al vault, detección de secretos en texto plano, conexiones y dependencias externas, configuración de ejecución, datos de prueba, dependencias previas, checklist de readiness, clonado, actualización de la versión bajo prueba, y la advertencia de readiness y la captura del snapshot al abrir un ciclo.

• Fuera: la apertura del ciclo en sí (HU-015), la ejecución (HU-016) y el diseño del

contrato con el vault (documentado, no diseñado — depende de PA-008).

Actores y permisos

La resolución del valor de un secreto la hace el usuario contra el vault con sus propias credenciales (▲³ de roles y permisos, RN-026); la plataforma solo muestra la referencia.

Precondiciones

• El usuario tiene rol en el proyecto.
• Existe un vault de secretos donde viven los valores de las credenciales (PA-008).

Comportamiento funcional

• Principal. El usuario registra un ambiente y elige su tipo —Local, Desarrollo, QA,

Staging, Producción controlada o Servidor externo—; registra URLs, endpoints y servidores; declara las credenciales necesarias como referencias al vault (identificador del secreto, ubicación y responsable de entregarlo); registra conexiones (base de datos, APIs internas y externas, autenticación, storage, colas y terceros); la configuración de ejecución (variables, feature flags, parámetros por cliente, versiones de servicios y la referencia de código bajo prueba: branch, commit, tag o release candidate); documenta los datos de prueba (usuarios, roles, permisos, registros base, fixtures y seeds) y las dependencias previas (migraciones, jobs, integraciones, servicios levantados y accesos validados); recorre el checklist de readiness y marca cada verificación.

• Alternativo A1 — clonar un ambiente. El usuario duplica un ambiente existente del mismo

proyecto y ajusta lo que cambia.

• Alternativo A2 — actualizar la versión bajo prueba. Entre un ciclo y otro se actualiza el

commit o release candidate; los ciclos ya abiertos conservan su snapshot (RN-029).

• Error E1 — secreto en texto plano. El sistema detecta un valor que aparenta ser una

credencial en un campo de texto libre y rechaza el guardado, explicando que solo se admiten referencias (RN-027).

• Error E2 — checklist incompleto al abrir un ciclo. El sistema advierte, no bloquea, y deja

constancia del estado del checklist en el ciclo (RN-028).

Datos y campos (funcional, no esquema)

• Identificación: nombre y tipo (Local, Desarrollo, QA, Staging,

Producción controlada, Servidor externo).

• Acceso: URLs, endpoints y servidores.
• Credenciales (solo referencia): identificador del secreto en el vault, ubicación y

responsable de entregarlo. Nunca el valor.

• Conexiones: base de datos, APIs internas y externas, autenticación, storage, colas,

terceros.

• Configuración de ejecución: variables, feature flags, parámetros por cliente, versiones de

servicios y referencia de código bajo prueba (branch, commit, tag o release candidate).

• Datos de prueba: usuarios, roles, permisos, registros base, fixtures y seeds.
• Dependencias previas: migraciones aplicadas, jobs ejecutados, integraciones habilitadas,

servicios levantados y accesos validados.

• Checklist de readiness: login funcional, servicios disponibles, conectividad, datos

mínimos presentes, permisos correctos e integraciones sincronizando.

Reglas de negocio aplicables

• RN-012 / RN-026 — Argos QA no almacena el valor de ningún secreto; las credenciales se

registran exclusivamente como referencia al vault (identificador, ubicación, responsable).

• RN-027 — el sistema rechaza los valores que aparenten ser credenciales en campos de

texto libre; ante la duda, rechaza.

• RN-028 — un checklist de readiness incompleto no impide abrir un ciclo, pero la

advertencia y el estado del checklist quedan registrados en el ciclo.

• RN-029 / DEC-046 — el ambiente no se versiona; al abrir un ciclo se captura un snapshot

inmutable de su configuración, y los cambios posteriores no alteran el snapshot de un ciclo ya abierto. El historial del ambiente son esos snapshots.

• RN-030 — un ambiente pertenece a un único proyecto; no se comparten entre proyectos

aunque apunten a la misma infraestructura.

Estados y transiciones. El ambiente no tiene máquina de estados: es un registro editable y no versionado (RF-057, DEC-046). Lo que se congela es el snapshot que toma cada ciclo, no el ambiente.

Integraciones (documentado, el dev implementa)

• Vault de secretos — el ambiente guarda solo la referencia (identificador, ubicación,

responsable); el valor se resuelve fuera de Argos QA, contra el vault, con las credenciales del propio usuario. El contrato fino (qué vault, cómo se referencia y se resuelve) se cierra con PA-008; el comportamiento local —guardar referencias y rechazar valores en claro— no depende de esa respuesta.

Eventos que emite. Ninguno en el MVP para el registro del ambiente. El snapshot se emite como parte de la apertura del ciclo (HU-015, RF-067).

Criterios de aceptación

• CA-170

> Dado un usuario con rol en el proyecto > Cuando registra un ambiente con su tipo, URLs y endpoints, conexiones, configuración de ejecución, datos de prueba y dependencias previas > Entonces el ambiente queda guardado y editable, asociado a un único proyecto.

• CA-171

> Dado que el ambiente requiere una credencial > Cuando el usuario la declara como identificador del secreto, ubicación y responsable de entregarlo > Entonces el sistema guarda solo la referencia al vault y en ningún momento almacena el valor del secreto.

• CA-172

> Dado un campo de texto libre del ambiente con un valor que aparenta ser una credencial > Cuando el usuario intenta guardar > Entonces el sistema rechaza el guardado y explica que solo se admiten referencias al vault.

• CA-173

> Dado un ambiente con el checklist de readiness incompleto > Cuando se abre un ciclo sobre él > Entonces el sistema advierte de forma explícita, no lo impide, y deja constancia del estado del checklist en el ciclo.

• CA-174

> Dado un ciclo abierto que capturó el snapshot de un ambiente > Cuando el ambiente se edita después > Entonces el snapshot del ciclo ya abierto no cambia, porque el ambiente no se versiona y su historial son los snapshots de los ciclos.

• CA-175

> Dado un ambiente existente del mismo proyecto > Cuando el usuario lo clona > Entonces el sistema crea un ambiente nuevo con la misma configuración, que el usuario ajusta en lo que cambia.

• CA-176

> Dado un ambiente cuya referencia de código bajo prueba se actualiza entre un ciclo y otro > Cuando se cambia el commit o release candidate > Entonces los ciclos ya abiertos conservan su snapshot y solo los ciclos nuevos toman la versión actualizada.

Dependencias y bloqueos

• PA-008 (vault de secretos) — condiciona el contrato de referencia y resolución de

secretos; el comportamiento local no depende de él.

• HU-015 (abrir un ciclo) captura el snapshot del ambiente (RF-067) y dispara la

advertencia de readiness.

Casos borde / notas. El tipo de ejecución del ambiente no restringe el tipo de escenario; son ejes independientes. Un checklist incompleto nunca bloquea: la decisión de arrancar igual, y su costo, quedan visibles en el ciclo para poder atribuir un fallo posterior a un ambiente mal preparado (RN-028).