Proton Cloud SDK para Java

Artefato br.com.protoncloud:protoncloud-sdk, para Java 21 ou superior e Maven 3.9 ou superior. Os pacotes Java são br.com.atomicsolutions.proton e br.com.atomicsolutions.http.

Instalação

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

Maven Central em breve

A publicação no Maven Central está em preparação. Até lá, a SDK Java vem do GitHub Packages da Atomic, que pede credencial na máquina que faz o build. Com a SDK no Maven Central, basta a dependência acima.

Enquanto vier do GitHub Packages, declare o repositório no pom.xml:

<repositories>
    <repository>
        <id>proton-lib</id>
        <url>https://maven.pkg.github.com/atomicsolutions/proton-lib</url>
    </repository>
</repositories>

E a credencial na pasta .m2 da máquina: copie para ela o settings.xml da Atomic (em Links Utilitários, no rodapé desta página), que já traz o servidor proton-lib.

Vindo da proton-lib

Até as versões 5.0.0-beta, a SDK se chamava br.com.atomicsolutions.proton:proton-lib. Troque só o groupId e o artifactId da dependência: os pacotes Java não mudaram, então nenhum import muda.

Configuração

Endereço e token são resolvidos nesta ordem, da maior para a menor prioridade:

1. System property: -Dproton.host=... e -Dproton.token=....
2. Variável de ambiente: PROTON_HOST e PROTON_TOKEN.
3. config.properties no classpath.

Pelo runner, o PROTON_HOST chega pronto e o id da execução vem em -DidDatasetRun. O token vem da variável PROTON_TOKEN da máquina do runner ou do config.properties:

hostname=https://app.protoncloud.com.br/api
token=<token>

O token pode vir com ou sem o prefixo Bearer . Deixe o arquivo com o token fora do controle de versão.

Para apontar o projeto a outro servidor e ignorar o que o runner injeta, declare proton.config.precedence = file no config.properties. Sem isso, quando o valor injetado difere do arquivo, a SDK registra uma linha dizendo qual venceu (o token nunca é impresso).

O ciclo de uma execução

O runner chama mvn -B test -DidDatasetRun=<id>, com -Dtest=TestProtonScript quando o projeto tem essa classe. O teste percorre os passos do dataset: pergunta qual componente vem agora, abre o passo, executa o código do componente e fecha o passo. Um exemplo simplificado:

import br.com.atomicsolutions.proton.ProtonAutomation;
import br.com.atomicsolutions.proton.ProtonLogs;
import br.com.atomicsolutions.proton.RunStatus;
import org.junit.jupiter.api.Test;

class TestProtonScript {

    @Test
    void runProtonExecution() {
        ProtonAutomation.updateRunStatus(RunStatus.RUNNING);

        try {
            String nome;

            while ((nome = ProtonAutomation.getCurrentComponentName()) != null && !nome.isEmpty()) {
                ProtonAutomation.startComponent();   // abre o passo e lê o ambiente da execução
                Componentes.executar(nome);          // o código do componente
                ProtonAutomation.endComponent();     // fecha o passo como Passed
            }

            ProtonAutomation.updateRunStatus(RunStatus.PASSED);
        } catch (RuntimeException e) {
            ProtonLogs.setLog(e);
            ProtonLogs.setErrorLog(e.getMessage());
            ProtonAutomation.updateRunStatus(RunStatus.FAILED);
            throw e;
        }
    }
}

Dentro de um componente

import br.com.atomicsolutions.proton.ProtonEnvironment;
import br.com.atomicsolutions.proton.ProtonFilesAndResources;
import br.com.atomicsolutions.proton.ProtonParameter;
import java.nio.file.Path;
import static br.com.atomicsolutions.proton.ProtonLogs.setLog;

public static void criarPedido() {
    String cliente = ProtonParameter.getProtonValue("CLIENTE");     // parâmetro do dataset
    String url = ProtonEnvironment.get("SISTEMA_URL");              // variável do ambiente da execução

    setLog("Criando pedido para " + cliente);
    // ... automação ...
    ProtonFilesAndResources.uploadImage(Path.of("evidencias/pedido.png"));  // evidência do passo
    ProtonParameter.setProtonValue("NUMERO_PEDIDO", "4500012345");          // parâmetro de saída
}

Referência

Classe	Método	O que faz
ProtonAutomation	startComponent()	Abre o passo corrente e lê o ambiente da execução
	endComponent()	Fecha o passo corrente
	getCurrentComponentName()	Nome do componente da vez; vazio quando não há mais passos
	getCurrentComponentSystem()	Sistema do componente da vez
	updateRunStatus(status)	Marca a execução com um RunStatus
	getDatasetRunInfo()	Dados da execução
ProtonParameter	getProtonValue(nome)	Valor de um parâmetro do dataset no passo aberto
	getProtonAllComponentParameters()	Todos os parâmetros do passo aberto
	setProtonValue(nome, valor)	Grava um parâmetro de saída
	getProtonOutputParameterList(nome)	Saídas gravadas na execução com esse nome
ProtonLogs	setLog(texto) e setLog(texto, true)	Escreve no log da execução; com true, aceita Markdown sem data e hora
	setLog(exceção)	Escreve o stack trace no log
	setErrorLog(texto)	Registra o erro da execução
ProtonFilesAndResources	uploadImage(Path)	Envia uma imagem como evidência
	uploadVideo(Path) e uploadFileResource(Path)	Envia um vídeo ou um arquivo como evidência
ProtonEnvironment	get(nome) e outros	Ambiente da execução: ver Ambiente da execução
ProtonEnv	getHost(), getToken() e getIDDatasetRun()	Configuração do processo

Status da execução

O Proton 5 aceita RunStatus.RUNNING, PASSED e FAILED. As constantes do Proton 4 (FAILED_DATA, FAILED_ENVIRONMENT e IN_PROCESS) estão obsoletas: a SDK envia FAILED no lugar das duas primeiras e RUNNING no lugar da última, com um aviso na saída da execução. Para separar falha de dados de falha de ambiente, registre o motivo no log.

Erros de comunicação

Um erro do servidor não interrompe a automação: a leitura volta vazia (getProtonValue devolve "" também quando o parâmetro não existe), e a gravação de saída registra a falha na saída da execução. Quando um valor vier vazio sem motivo, comece pelo log.

A exceção é o ambiente da execução: ler uma variável que não existe lança ProtonEnvironmentException, porque seguir com um valor vazio esconderia o problema.