Proton Cloud SDK

The Proton Cloud SDK is the dependency an automation's code uses to talk to Proton during the run. With it, the automation:

• finds out which component is running now and opens and closes each step;
• reads the dataset parameters and the variables of the run environment;
• records the output parameters, the log, the error and the evidence;
• sets the result of the run.

The SDK makes the Execution API calls for you. Use the API reference to understand what happens under the hood or to integrate a language that doesn't have an SDK yet.

Languages

Language	Package	Version	Where
Python 3.10+	protoncloud-sdk	5.5.0	PyPI
Java 21+	br.com.protoncloud:protoncloud-sdk	5.5.0	Public Maven repository https://maven.protoncloud.com.br

Both follow the same version numbering. Version 5.x talks to Proton 5.

Python

pip install protoncloud-sdk

Java

<repositories>
    <repository>
        <id>protoncloud</id>
        <url>https://maven.protoncloud.com.br</url>
    </repository>
</repositories>

<dependency>
    <groupId>br.com.protoncloud</groupId>
    <artifactId>protoncloud-sdk</artifactId>
    <version>5.5.0</version>
</dependency>

The details for each language are in Python and Java.

Component executor

Starting with 5.3, the SDK includes the loop that runs the dataset steps, which each project used to copy into its own entry point. The project tells it, by component name, which code to run, and the executor takes care of the rest:

• records Running when the first step is about to run;
• for each step, opens the step, calls the component with only its own parameters, records the outputs it returns, uploads the new evidence from the evidencias/ folder and closes the step;
• at the end, records Passed; when a step fails, it records the stack trace in the error panel and Failed with the failure reason (business, technical or environment), and the step stays Failed.

Since 5.5.0, the executor also closes the session after the last step (close_at_end in Python, closeAtEnd in Java), so that the video of a run that passed reaches Proton, and a failure that happens before the first step reaches Proton through record_failure (Python) or recordFailure (Java). See the examples in Python and Java.

The business code doesn't import the SDK and runs the same way outside Proton. One project can cover several platforms (SAP, web, API, desktop), each one a system in Proton linked to the same repository: the executor keeps going in the same process as long as the project has the component for the next step.

The template projects show the complete structure, in Python and in Java.

How the SDK finds Proton

The Proton Runner downloads the code from the repository and starts the automation with the API address (PROTON_HOST) and the run id. The SDK reads both on its own: the same project reports to the server the run came from, without editing any file.

Run token

The updated runner asks Proton for a run token for each run and hands it to the automation in PROTON_TOKEN. This token:

• is valid only for that run: opening and closing the steps, reading the parameters and the environment, recording the outputs, the log and the evidence, and reading the run's own dataset and group;
• is valid only while the run is in progress, and for 24 hours at most;
• is never stored in the project or on the runner's disk.

Starting with 5.2.0, the SDK uses the run token even if the project has a different one in its configuration file. With it, the project doesn't need to store any token at all.

With an older runner, the SDK reads the token from the PROTON_TOKEN variable on the runner machine or from the project's configuration file (proton.ini in Python, config.properties in Java), as before. The token is created in My Profile, in Proton, or by the administrator for a robot user. Never commit the token to the repository.

Outside a Proton run, without the run id, the SDK doesn't call the server: the same test runs on the developer's machine.

Coming from Proton Lib

The Proton Cloud SDK is the former Proton Lib under a new name. The code stays the same:

• Python: the protoncloud-sdk package keeps the proton import (from proton.proton_automation import ...). If the project carried a copy of the proton/ folder, delete the folder after installing the package: the local copy takes precedence over the installed package.
• Java: the br.com.atomicsolutions.proton:proton-lib dependency becomes br.com.protoncloud:protoncloud-sdk. The Java packages are still br.com.atomicsolutions.*, so no import changes.

What changed in behavior in Proton 5 is in Versions.