Skip to main content
Proton v5

Template projects

The template projects are the starting point for a new automation project, QA or RPA, in Python or in Java. They are public, under the MIT license:

Both include the same example: they look up a postal code (CEP) in a public API (ViaCEP), make a purchase in the Swag Labs test store and add the same product to the cart of My Demo App, the Sauce Labs Android demo app. In Python, they also calculate the installment in the Windows Calculator, and there is the SAP GUI logon as a starting point.

The automation is yours, with or without Proton​

The same code runs in three ways: through the test framework (pytest or JUnit), as a robot without a test framework, and through Proton. The rules that make this possible:

  • The component doesn't know about Proton. It receives the parameters (in_...), returns the outputs (out_...) and throws an exception to fail.
  • A single entry point talks to Proton: tests/test_proton_script.py in Python and TestProtonScript in Java, the names the runner looks for. In it, the SDK's component executor runs the dataset steps.
  • The scenarios also run from files. The cenarios/ folder holds the scenarios in JSON, in the same format as a Proton dataset: the steps in order, with the component and the parameters.
  • No secrets in the repository. Passwords come from .env (kept out of git) in the scenarios and from an encrypted parameter in Proton. The project doesn't store the Proton token or address either: the runner provides both.

Delete the entry point and the SDK dependency, and the rest of the project keeps running the scenarios. In Java, the SDK is in the test scope: the compiler ensures that nothing in src/main depends on Proton.

Structure​

automacao/
  componentes/   one file per component: executar(parametros) -> dict | None
  web/           browser session and pages (page objects)
  api/           HTTP session and API clients
  mobile/        device session (Appium) and app screens
  sap/           SAP GUI session and transaction screens
  desktop/       Windows applications session and windows
  apoio/         configuration, sessions, evidence and scenario execution
cenarios/        scenarios in JSON
tests/
  test_cenarios.py       runs the scenarios, without Proton
  test_proton_script.py  Proton entry point

The component name is the same in Proton, in the scenarios and in the code: the FinalizarCompra component is the finalizar_compra.py file in Python and the FinalizarCompra class in Java.

Several platforms in the same project​

Each platform has a session: the browser, the HTTP client, the SAP connection, the open applications. The session opens the first time a step needs it and serves the following steps of the same scenario, even when they belong to another platform. At the end of the scenario, all of them close. An API-only scenario doesn't even open a browser.

In Proton, register one system for each platform (for example, the portal, the API and SAP) and link all of them to the same repository. The SDK executor runs the steps in order, in the same process, as long as the project has the component: the session opened in a SAP step is still valid in the next web step. A step whose component lives in another repository goes back to the runner, which calls that system's project.

For SAP GUI and Windows desktop, use the Python template: SAP GUI Scripting and desktop automation are native to Python (pywin32 and pywinauto). These scenarios need a Windows runner with the user session open, and the SAP one needs SAP GUI with scripting enabled.

Mobile​

Both templates automate Android through Appium, with the UiAutomator2 driver. The machine needs the Android SDK (adb), Appium with the driver and a device with USB debugging turned on. If Appium isn't running, the automation starts it and shuts it down at the end of the scenario. Mobile scenarios ask for "requer": ["android"] and are skipped when no device is connected.

In Proton, mark the automation as mobile and register the APK in Mobile Apps. When you trigger the run, choose the device (from the ones the runner finds) and the app. The templates' entry point reads the device and the app from the run, downloads the app and hands it to the mobile session, without changing the component code.

Run locally​

uv sync
cp .env.example .env
uv run pytest                                               # all scenarios
uv run pytest -k compra                                     # one scenario
uv run python -m automacao cenarios/compra-com-sucesso.json # as a robot, without pytest

Screenshots and API responses go to the evidencias/ folder. Scenarios that need something from the machine (Windows, SAP) say so in the JSON ("requer") and are skipped when the machine doesn't have it.

Run through Proton​

  1. Systems: one per platform, all linked to the project repository. The runner recognizes the project by the pytest.ini (Python) or the pom.xml (Java) at the root of the repository.
  2. Components: one for each component in the code, in its platform's system, with the same name and the in_ and out_ parameters.
  3. Automation and dataset: the steps are the components, in order, with the parameter values. The output of one step becomes the input of another through the output reference.
  4. Group and run: put the datasets in an automation group and trigger them on the runner.

The runner machine needs whatever the project uses (uv for Python; the JDK and Maven for Java). See Environment Setup.

The runner can handle several runs at the same time, in the same project folder. That's why the templates' entry point stores the evidence of each run in its own subfolder (evidencias/<run id>). Since 5.5.0, the SDK returns this folder (run_evidence_dir() in Python, ProtonComponentRunner.runEvidenceDir() in Java) and the executor already ignores the subfolders of other runs: see Evidence folder in Python and Java.

With AI​

Both templates include an AGENTS.md with the project rules for AI agents (Claude Code, Codex, Cursor and others). With the Proton MCP connector, the agent creates the component in the code and registers it in Proton with the same name and the same parameters. See also Project from scratch.