Saltar al contenido principal
Proton v5

Proyectos modelo

Los proyectos modelo son el punto de partida para un proyecto de automatización nuevo, de QA o de RPA, en Python o en Java. Son públicos, con licencia MIT:

Los dos traen el mismo ejemplo: consultan un código postal (CEP) en una API pública (ViaCEP), hacen una compra en la tienda de pruebas Swag Labs y agregan el mismo producto al carrito de My Demo App, la app Android de demostración de Sauce Labs. En Python, también calculan la cuota en la Calculadora de Windows, y está el inicio de sesión en SAP GUI como punto de partida.

La automatización es tuya, con o sin Proton​

El mismo código se ejecuta de tres formas: con el framework de pruebas (pytest o JUnit), como robot, sin framework de pruebas, y desde Proton. Las reglas que lo garantizan:

  • El componente no conoce a Proton. Recibe los parámetros (in_...), devuelve las salidas (out_...) y lanza una excepción para fallar.
  • Un único punto de entrada habla con Proton: tests/test_proton_script.py en Python y TestProtonScript en Java, los nombres que busca el runner. En él, el ejecutor de componentes de la SDK ejecuta los pasos del dataset.
  • Los escenarios también se ejecutan desde archivos. La carpeta cenarios/ tiene los escenarios en JSON, en el mismo formato que un dataset de Proton: los pasos en orden, con el componente y los parámetros.
  • Ningún secreto en el repositorio. Las contraseñas vienen del .env (fuera de git) en los escenarios y de un parámetro cifrado en Proton. El proyecto tampoco guarda el token ni la dirección de Proton: el runner entrega los dos.

Borra el punto de entrada y la dependencia de la SDK, y el resto del proyecto sigue ejecutando los escenarios. En Java, la SDK queda en el scope test: el compilador garantiza que nada en src/main dependa de Proton.

Estructura​

automacao/
  componentes/   un archivo por componente: executar(parametros) -> dict | None
  web/           sesión del navegador y páginas (page objects)
  api/           sesión HTTP y clientes de las APIs
  mobile/        sesión del dispositivo (Appium) y pantallas de la app
  sap/           sesión de SAP GUI y pantallas de las transacciones
  desktop/       sesión de las aplicaciones de Windows y ventanas
  apoio/         configuración, sesiones, evidencias y ejecución de los escenarios
cenarios/        escenarios en JSON
tests/
  test_cenarios.py       ejecuta los escenarios, sin Proton
  test_proton_script.py  punto de entrada de Proton

El nombre del componente es el mismo en Proton, en los escenarios y en el código: el componente FinalizarCompra es el archivo finalizar_compra.py en Python y la clase FinalizarCompra en Java.

Varias plataformas en el mismo proyecto​

Cada plataforma tiene una sesión: el navegador, el cliente HTTP, la conexión SAP, las aplicaciones abiertas. La sesión se abre la primera vez que un paso la pide y sirve a los pasos siguientes del mismo escenario, incluso cuando son de otra plataforma. Al final del escenario, todas se cierran. Un escenario solo de API ni siquiera abre el navegador.

En Proton, registra un sistema para cada plataforma (por ejemplo, el portal, la API y SAP) y vincúlalos todos al mismo repositorio. El ejecutor de la SDK ejecuta los pasos en orden, en el mismo proceso, mientras el proyecto tenga el componente: la sesión abierta en un paso de SAP sigue valiendo en el paso de web siguiente. Un paso cuyo componente está en otro repositorio vuelve al runner, que llama al proyecto de ese sistema.

Para SAP GUI y desktop Windows, usa el modelo Python: SAP GUI Scripting y la automatización de desktop son nativos en Python (pywin32 y pywinauto). Estos escenarios necesitan un runner Windows con la sesión del usuario abierta, y el de SAP necesita SAP GUI con el scripting habilitado.

Mobile​

Los dos modelos automatizan Android con Appium, con el driver UiAutomator2. La máquina necesita el Android SDK (adb), Appium con el driver y un dispositivo con la depuración USB activada. Si Appium no está en marcha, la automatización lo inicia y lo detiene al final del escenario. Los escenarios mobile piden "requer": ["android"] y se omiten cuando no hay ningún dispositivo conectado.

En Proton, marca la automatización como mobile y registra el APK en Aplicaciones Móviles. Al disparar la ejecución, elige el dispositivo (entre los que encuentra el runner) y la app. El punto de entrada de los modelos lee de la ejecución el dispositivo y la app, descarga la app y se la entrega a la sesión mobile, sin cambiar el código de los componentes.

Ejecutar en local​

uv sync
cp .env.example .env
uv run pytest                                               # todos los escenarios
uv run pytest -k compra                                     # un escenario
uv run python -m automacao cenarios/compra-com-sucesso.json # como robot, sin pytest

Las capturas de pantalla y las respuestas de API quedan en la carpeta evidencias/. Los escenarios que necesitan algo de la máquina (Windows, SAP) lo indican en el JSON ("requer") y se omiten cuando la máquina no lo tiene.

Ejecutar desde Proton​

  1. Sistemas: uno por plataforma, todos vinculados al repositorio del proyecto. El runner reconoce el proyecto por el pytest.ini (Python) o por el pom.xml (Java) en la raíz del repositorio.
  2. Componentes: uno para cada componente del código, en el sistema de su plataforma, con el mismo nombre y los parámetros in_ y out_.
  3. Automatización y dataset: los pasos son los componentes, en orden, con los valores de los parámetros. La salida de un paso se convierte en la entrada de otro mediante la referencia a la salida.
  4. Grupo y ejecución: pon los datasets en un grupo de automatización y dispáralos en el runner.

La máquina del runner necesita lo que usa el proyecto (uv en Python; el JDK y Maven en Java). Consulta Configuración del Ambiente.

El runner puede procesar varias ejecuciones al mismo tiempo, en la misma carpeta del proyecto. Por eso el punto de entrada de los modelos guarda las evidencias de cada ejecución en una subcarpeta propia (evidencias/<id de la ejecución>). Desde la 5.5.0, la SDK devuelve esa carpeta (run_evidence_dir() en Python, ProtonComponentRunner.runEvidenceDir() en Java) y el ejecutor ya ignora las subcarpetas de las otras ejecuciones: consulta Carpeta de evidencias en Python y Java.

Con IA​

Los dos modelos traen un AGENTS.md con las reglas del proyecto para agentes de IA (Claude Code, Codex, Cursor y otros). Con el conector MCP de Proton, el agente crea el componente en el código y lo registra en Proton con el mismo nombre y los mismos parámetros. Consulta también el proyecto desde cero.