Pular para o conteúdo principal
Proton v5

Projetos modelo

Os projetos modelo são o ponto de partida para um projeto de automação novo, de QA ou de RPA, em Python ou em Java. São públicos, com licença MIT:

Os dois trazem o mesmo exemplo: consultam um CEP numa API pública (ViaCEP), fazem uma compra na loja de testes Swag Labs e põem o mesmo produto no carrinho do My Demo App, o app Android de demonstração da Sauce Labs. No Python, calculam também a parcela na Calculadora do Windows, e há o logon no SAP GUI como ponto de partida.

A automação é sua, com ou sem o Proton​

O mesmo código roda de três jeitos: pelo framework de testes (pytest ou JUnit), como robô, sem framework de testes, e pelo Proton. As regras que garantem isso:

  • O componente não conhece o Proton. Recebe os parâmetros (in_...), devolve as saídas (out_...) e lança uma exceção para falhar.
  • Um único ponto de entrada fala com o Proton: o tests/test_proton_script.py no Python e o TestProtonScript no Java, os nomes que o runner procura. Nele, o executor de componentes da SDK roda os passos do dataset.
  • Os cenários também rodam por arquivo. A pasta cenarios/ tem os cenários em JSON, no mesmo formato de um dataset do Proton: os passos em ordem, com o componente e os parâmetros.
  • Nenhum segredo no repositório. Senhas vêm do .env (fora do git) nos cenários e de parâmetro criptografado no Proton. O projeto também não guarda token nem endereço do Proton: o runner entrega os dois.

Apague o ponto de entrada e a dependência da SDK, e o resto do projeto continua rodando os cenários. No Java, a SDK fica no escopo test: o compilador garante que nada em src/main dependa do Proton.

Estrutura​

automacao/
  componentes/   um arquivo por componente: executar(parametros) -> dict | None
  web/           sessão do navegador e páginas (page objects)
  api/           sessão HTTP e clientes das APIs
  mobile/        sessão do aparelho (Appium) e telas do app
  sap/           sessão do SAP GUI e telas das transações
  desktop/       sessão dos aplicativos do Windows e janelas
  apoio/         configuração, sessões, evidências e execução dos cenários
cenarios/        cenários em JSON
tests/
  test_cenarios.py       roda os cenários, sem o Proton
  test_proton_script.py  ponto de entrada do Proton

O nome do componente é o mesmo no Proton, nos cenários e no código: o componente FinalizarCompra é o arquivo finalizar_compra.py no Python e a classe FinalizarCompra no Java.

Várias plataformas no mesmo projeto​

Cada plataforma tem uma sessão: o navegador, o cliente HTTP, a conexão SAP, os aplicativos abertos. A sessão abre na primeira vez que um passo pede e serve aos passos seguintes do mesmo cenário, mesmo quando eles são de outra plataforma. No fim do cenário, todas fecham. Um cenário só de API nem abre navegador.

No Proton, cadastre um sistema para cada plataforma (por exemplo, o portal, a API e o SAP) e ligue todos ao mesmo repositório. O executor da SDK roda os passos em ordem, no mesmo processo, enquanto o projeto tiver o componente: a sessão aberta num passo de SAP continua valendo no passo de web seguinte. Um passo cujo componente fica em outro repositório volta para o runner, que chama o projeto daquele sistema.

Para SAP GUI e desktop Windows, use o modelo Python: o SAP GUI Scripting e a automação de desktop são nativos em Python (pywin32 e pywinauto). Esses cenários precisam de um runner Windows com a sessão do usuário aberta, e o de SAP precisa do SAP GUI com o scripting habilitado.

Mobile​

Os dois modelos automatizam Android pelo Appium, com o driver UiAutomator2. A máquina precisa do Android SDK (adb), do Appium com o driver e de um aparelho com a depuração USB ligada. Se o Appium não estiver no ar, a automação o inicia e o encerra no fim do cenário. Os cenários mobile pedem "requer": ["android"] e são pulados quando não há aparelho conectado.

No Proton, marque a automação como mobile e cadastre o APK em Aplicativos Mobile. Ao disparar, escolha o aparelho (os que o runner encontra) e o app. O ponto de entrada dos modelos lê da execução o aparelho e o app, baixa o app e o entrega à sessão mobile, sem mudar o código dos componentes.

Rodar localmente​

uv sync
cp .env.example .env
uv run pytest                                               # todos os cenários
uv run pytest -k compra                                     # um cenário
uv run python -m automacao cenarios/compra-com-sucesso.json # como robô, sem pytest

Os prints e as respostas de API ficam na pasta evidencias/. Os cenários que precisam de algo da máquina (Windows, SAP) dizem isso no JSON ("requer") e são pulados quando ela não tem.

Rodar pelo Proton​

  1. Sistemas: um por plataforma, todos ligados ao repositório do projeto. O runner reconhece o projeto pelo pytest.ini (Python) ou pelo pom.xml (Java) na raiz do repositório.
  2. Componentes: um para cada componente do código, no sistema da plataforma dele, com o mesmo nome e os parâmetros in_ e out_.
  3. Automação e dataset: os passos são os componentes, em ordem, com os valores dos parâmetros. A saída de um passo vira entrada de outro pela referência a saída.
  4. Grupo e execução: ponha os datasets num grupo de automação e dispare no runner.

A máquina do runner precisa do que o projeto usa (o uv no Python; o JDK e o Maven no Java). Ver Configuração de Ambiente.

O runner pode rodar várias execuções ao mesmo tempo, na mesma pasta do projeto. Por isso o ponto de entrada dos modelos grava as evidências de cada execução numa subpasta própria (evidencias/<id da execução>). Desde a 5.5.0, a SDK devolve essa pasta (run_evidence_dir() no Python, ProtonComponentRunner.runEvidenceDir() no Java) e o executor já ignora as subpastas das outras execuções: ver Pasta de evidências em Python e Java.

Com IA​

Os dois modelos trazem um AGENTS.md com as regras do projeto para agentes de IA (Claude Code, Codex, Cursor e outros). Com o conector MCP do Proton, o agente cria o componente no código e o cadastra no Proton com o mesmo nome e os mesmos parâmetros. Ver também o projeto do zero.