Plan de pruebas manuales
Escribe el plan para verificar esta rama en la aplicación en ejecución. El plan cubre lo que las pruebas automatizadas no pueden mostrar: cómo se ve y se comporta el cambio con datos reales, en flujos reales, a través de los estados que un usuario puede alcanzar.
Cada caso se asigna a quien pueda resolverlo: un agente que maneja un navegador, un agente que maneja un simulador de iOS o un humano. Dale al agente todo lo que un agente pueda resolver. Para los casos que solo un humano puede resolver, haz que un agente los intente primero como un ensayo, para que los problemas obvios se encuentren antes de que una persona dedique tiempo y la persona sepa dónde mirar.
Ejecutar un caso en la aplicación es costoso. Un agente manejando un navegador gasta muchas veces los tokens de una prueba de código para la misma verificación, y una persona gasta minutos. Por lo tanto, el plan es pequeño y dirigido: contiene los casos con mayor probabilidad de exponer un error que importe, y nada que una prueba en código pueda cubrir igual de bien. Un buen plan es lo suficientemente corto para ejecutarse en su totalidad.
Por la misma razón, escribe y ejecuta el plan tarde: después de las revisiones que leen el código, después de las correcciones y refactorizaciones a las que conducen, y después de que las pruebas de código estén en su lugar. Entonces el plan se ejecuta una vez, sobre el código que se fusionará, y las pasadas anteriores ya han realizado las verificaciones que son baratas. Si el código aún está cambiando, indícalo al principio del plan. Si cambia después de que se haya ejecutado el plan, nombra los casos que deben ejecutarse nuevamente: aquellos cuya línea "Atrapa" apunta al código cambiado.
Notas locales. Si un archivo llamado LOCAL.md se encuentra junto a este archivo, léelo antes de comenzar. Contiene los valores predeterminados del usuario para los proyectos en los que trabaja (comandos, hosts, cuentas, rutas) y no es parte del skill publicado. Donde cubra el proyecto en cuestión, cuenta como parte de las instrucciones del proyecto; donde no lo haga, ignóralo.
Reúne los cambios
La solicitud puede nombrar una rama base. Si no se proporciona ninguna, elígelo en este orden:
- La rama base de la solicitud de extracción de la rama, si tiene una:
gh pr view --json baseRefName --jq .baseRefName. - La rama predeterminada del repositorio:
git symbolic-ref --short refs/remotes/origin/HEAD. origin/main, luegomain.
Usa la referencia de seguimiento remota (origin/<branch>) en lugar de una rama local con el mismo nombre. Incluye el trabajo que aún no está confirmado:
base=$(git merge-base <base> HEAD)
git diff --stat "$base" # confirmado + preparado + sin preparar
git diff "$base"
git status --short # los archivos sin seguimiento no están en el diff; léelos
git log --oneline "$base"..HEAD
Lee las tres fuentes que el diff no contiene
El diff muestra lo que cambió. No muestra para qué es el cambio, qué han visto las personas que ya ha salido mal o qué se ha decidido en esta conversación. Lee las tres antes de elegir cualquier caso. Son entrada requerida, no antecedentes; el plan informa lo que se leyó y muestra dónde cada fuente lo moldeó.
1. La solicitud de extracción y sus comentarios
pr=$(gh pr view --json number --jq .number)
gh pr view --json title,body,baseRefName
for kind in "issues/$pr/comments" "pulls/$pr/reviews" "pulls/$pr/comments"; do
gh api "repos/{owner}/{repo}/$kind" --paginate --jq '.[]
| select(.user.type != "Bot" and (.body // "") != "")
| {id, reply_to: .in_reply_to_id, user: .user.login, path, line: (.line // .original_line), body}'
done
Las tres listas son los comentarios de la conversación, los resúmenes de revisión y los comentarios en línea sobre líneas del diff, con la salida de los bots omitida. Los bots siguen estando donde suele estar un enlace de implementación, así que búscalo por separado. El entorno implementado no es donde se ejecuta el plan (consulta "Probar una compilación local" más abajo); el enlace es para comparaciones y como respaldo:
gh api "repos/{owner}/{repo}/issues/$pr/comments" --paginate \
--jq '.[] | select(.user.type == "Bot") | .body' | grep -oE 'https?://[^ )|>"]+' | sort -u
Lee la descripción, cada comentario humano y las respuestas del autor. Un informe en la descripción cuenta igual que uno en un comentario. Toma de ellos:
- Cualquier cosa que una persona vio en la aplicación: un valor incorrecto, un estado que nunca termina, un flujo roto, una captura de pantalla. Cada uno se convierte en un caso que vuelve a probar ese informe exacto, independientemente de si el código ha cambiado desde entonces. Luego pregunta dónde más podría aparecer la misma falla (las pantallas hermanas, el mismo estado alcanzado de otra manera) y considera un caso allí.
- Dudas sobre el comportamiento planteadas en la revisión ("el orden puede discrepar de lo que se muestra"): cada una es un caso candidato, calificado como alto en probabilidad, porque un lector del código ya lo sospechaba.
- Notas de prueba en la descripción: lo que el autor dice que probó y lo que dice que no probó. Fecha las notas con respecto al registro de confirmaciones (
git log --format='%h %ad %s' --date=short "$base"..HEAD): lo que se probó antes de que confirmaciones posteriores tocaran el mismo código no se ha probado en su forma actual. Las confirmaciones que llegaron después de la última prueba manual son hacia donde debe apuntar primero el plan. - Enlaces a entornos implementados: la implementación de la propia rama y la de la base, para comparaciones lado a lado.
- Decisiones tomadas en el hilo sobre cómo debería comportarse algo. Estas establecen los resultados esperados.
2. El issue
Encuentra el identificador del issue en el nombre de la rama, los asuntos de las confirmaciones, el título o el cuerpo de la solicitud de extracción, o un comentario de un bot de seguimiento en la solicitud de extracción. Búscalo con el rastreador que nombran las instrucciones del proyecto, usando la herramienta disponible para ello. Lee la descripción, los criterios de aceptación, la discusión y cualquier captura de pantalla o pasos de reproducción adjuntos. Toma de él:
- El informe original. Si el issue describe un error, sus pasos de reproducción se convierten en el primer caso del plan: los pasos tal como se informaron, con el comportamiento corregido como resultado esperado. Si el issue es solo un título, o apunta a un hilo o archivo adjunto que no se puede leer, dilo, reconstruye el caso a partir del título y la descripción de la solicitud de extracción, y márcalo como reconstruido.
- Cada criterio de aceptación. Cada uno debe terminar en uno de tres lugares: un caso en el plan, una prueba nombrada en el código que lo cubra, o la lista de lo que se omitió, con la razón.
- Los usuarios, datos y plataformas afectados que el issue nombra, que indican qué forma de datos y qué dispositivo probar.
- Issues relacionados a los que enlaza, donde describen la misma área fallando de otra manera.
3. La conversación hasta ahora
Vuelve sobre esta conversación antes de escribir. Toma de ella:
- Hallazgos de revisión: verifica cada uno contra el árbol actual primero, ya que puede haberse corregido desde entonces. Un hallazgo que necesita la aplicación en ejecución para confirmarse obtiene un caso: uno que confirme la corrección, o uno que muestre la falla si quedó. Un hallazgo que una prueba en código puede precisar va a la lista de pruebas para escribir, no a los casos.
- Listas de "no verificado" y pasos de validación manual de pasadas de revisión anteriores. Estos fueron escritos para verificarse en la aplicación; son la entrada más directa que existe.
- Lo que el usuario dijo sobre el cambio: las partes que le preocupan, los estados que mencionó, lo que ya ha probado manualmente y lo que dijo que no se invierta tiempo. Una preocupación expresada aumenta la calificación de un caso; "ya lo he comprobado" lo elimina.
- Decisiones sobre el comportamiento tomadas en la conversación, que establecen los resultados esperados que el código solo deja abiertos.
- Lo que cambió en el código durante la conversación. El código escrito o reescrito en esta sesión ha tenido la menor cantidad de pruebas.
Si la conversación no contiene nada relevante, dilo en el plan; no finjas que lo hizo.
Cuando una fuente no se puede leer
Si gh falta o no ha iniciado sesión, la rama no tiene una solicitud de extracción, no hay ningún issue vinculado o no se puede acceder al rastreador, continúa con lo que hay. Nombra cada fuente que no se leyó al principio del plan y di que el plan puede omitir lo que contenía. No presentes un plan construido solo a partir del diff como uno completo.
Lee lo demás que influye en el plan
-
Cómo ejecutar la aplicación localmente: el comando documentado del proyecto para una compilación local, con qué backend se comunica y qué puertos usa. Lee las instrucciones del proyecto para entornos de prueba, cuentas de prueba y indicadores de características, y para qué plataformas se distribuye la aplicación (web, iOS, Android).
-
Lo que cubren las pruebas automatizadas: lee las pruebas en el diff, para que el plan no gaste tiempo de nadie en lo que una prueba ya precisa.
-
Qué herramientas tiene un agente aquí: un navegador que puede controlar y un simulador de dispositivo. En Orca, estos son el navegador integrado (el skill
orca-cli) y el simulador de iOS (el skillorca-emulator;orca-emulator-androidpara Android). También busca:- Un lector de pantalla que el agente pueda controlar, como el skill
voiceover, que ejecuta el VoiceOver real de macOS contra una página y devuelve lo que dice. - Un navegador con script (Playwright con un navegador instalado) para lo que el navegador integrado no puede hacer. Por ejemplo, es posible que el navegador integrado no coloque una copia en el portapapeles del sistema, por lo que verificar lo que se copia necesita un navegador cuyo portapapeles el agente pueda leer.
Nota cuáles están disponibles en esta sesión; el plan lo indica en su configuración.
- Un lector de pantalla que el agente pueda controlar, como el skill
Prueba una compilación local, no la rama implementada
Planifica cada caso contra una compilación local del árbol de trabajo. Un entorno de características o vista previa implementado solo tiene lo que se confirmó y envió: va detrás del código en el que se está trabajando, no puede mostrar cambios no confirmados, y una corrección realizada durante las pruebas necesitaría una confirmación y un envío antes de poder volver a probarse allí. Una compilación local muestra el código tal como es ahora, y una corrección se puede volver a probar de inmediato.
Por lo tanto, la configuración del plan dice:
- Cómo compilar e iniciar la aplicación localmente, con el comando exacto de los documentos del proyecto, el directorio para ejecutarlo y la URL en la que sirve. Si otras sesiones o árboles de trabajo pueden estar ejecutando la aplicación, indica cómo elegir puertos libres.
- Con qué backend se comunica la compilación local. Debe ser el backend de staging o prueba, nunca producción. Una compilación local apuntada a producción ejecuta todos los casos, incluidos los simulados y los pedidos, contra los sistemas de clientes reales. Los proyectos a menudo tienen un comando por entorno (por ejemplo, un script
stageyprod): nombra el de staging en el plan y di explícitamente que no se debe usar el de producción. Si los documentos del proyecto no aclaran qué comando apunta a qué backend, averígualo a partir de la configuración de compilación, y si aún no está claro, detente y pregúntale al usuario; no adivines. - Cómo verificar el backend antes del primer caso: mira a dónde envía sus solicitudes la aplicación en ejecución (el host de una llamada API en el registro de red, o la URL de API configurada) y confirma que sea el host de staging. El plan nombra el host que se espera. Si es el host de producción, detente: no inicies sesión y no ejecutes ningún caso.
- Cómo saber que la compilación es el código actual: iníciala desde el árbol de trabajo después del último cambio y recompila o recarga después de cualquier cambio adicional. Si la aplicación muestra una versión o confirmación, verifícala.
- Cómo detenerla cuando la ejecución haya terminado.
Usa un entorno implementado solo para:
- Comparar con la base: la implementación de la rama base, junto a la compilación local de la rama, para los casos lado a lado.
- Lo que una compilación local no puede mostrar: un caso sobre la implementación en sí, como activos compilados, almacenamiento en caché o una aplicación nativa que envuelve el sitio implementado. Antes de dicho caso, verifica que el árbol de trabajo esté limpio y enviado y que la implementación sirva esa confirmación, y dilo en el caso.
- Un respaldo cuando la aplicación no se puede compilar localmente. Di por qué al principio del plan y establece qué confirmación sirve la implementación y qué hay en el árbol de trabajo que le falta.
La misma regla se aplica a cualquier entorno implementado que use el plan: la implementación de staging, nunca la de producción. Cuando una rama tiene tanto una implementación de staging como una de producción, proporciona solo la URL de staging en el plan.
Determina qué probar
-
Enumera lo que un usuario puede ver o hacer de manera diferente. Traza cada cambio en el diff hacia afuera hasta las pantallas y flujos que lo muestran. Un cambio en el código compartido llega a todas las pantallas que lo usan; busca las llamadas y enuméralas todas, incluidas aquellas para las que la rama no estaba destinada.
-
Para cada uno, decide si necesita la aplicación en ejecución. Pregunta si una prueba en código podría resolverlo. Si ya lo hace, déjalo fuera. Si pudiera hacerlo fácilmente (una función pura, un decodificador, un orden de clasificación, una función de vista dado un estado, una transición de estado), déjalo fuera de los casos y ponlo en la lista de pruebas para escribir en su lugar; esa verificación se ejecuta entonces en cada cambio sin costo adicional, mientras que un caso en la aplicación se paga cada vez. Mantén solo lo que una prueba de código no puede alcanzar o no sería confiable para ello: cómo los datos reales del backend real llegan, qué se renderiza y se diseña en un navegador real, cómo se comportan las partes que se prueban por separado cuando se unen, el tiempo y el orden de las solicitudes reales, el estado en el que se encuentra la aplicación después de la navegación real, y lo que se proporciona a la tecnología de asistencia.
-
Encuentra los estados. Para cada pantalla, lee el código en busca de las ramas que puede tomar: cargado, cargando, vacío, error, datos faltantes o parciales, valores cero y negativos, valores muy largos, un elemento y muchos, cada configuración o modo que cambia la visualización, cada tipo de cuenta o usuario. Mantén los estados que toca el diff.
-
Determina cómo alcanzar cada estado. Nombra la ruta de navegación y describe los datos que necesita por su forma ("un instrumento mantenido en dos cuentas, una de ellas sin costo de compra"), no por una cuenta que no has confirmado que exista. Donde un estado sea difícil de alcanzar con datos reales, indica cómo se puede producir (un indicador de característica, una respuesta reescrita, una red limitada, una configuración) o márcalo como que necesita una cuenta de prueba específica.
Cuando un caso depende de una respuesta reescrita, el plan debe hacer que la reescritura sea repetible;
reference/mocks.mddice cómo.Dale a cada caso una forma de llegar que no dependa de la suerte con los datos de la cuenta. Si los datos reales pueden carecer del estado, nombra el control en la aplicación que lo activa (una configuración, una palanca, otra cuenta) o...