Apredendo a utilizar a ferramenta RPAPY com exemplo

Introdução

Existem inúmeras formas de se apreender uma nova tecnologia, biblioteca ou ferramenta, mas na minha opinião, a forma mais fácil e direta é o aprendizado por meio de exemplos. Então neste tutorial vou ensinar como usar a ferramenta rpapy, para implementação de automações desktop com python, em ambiente windows, e adivinhem como? isso mesmo que você pensou... por meio de uma implementação de exemplo, existente na própria ferramenta.

Preparando o Ambiente

A primeira coisa que você precisa fazer é, escolher o IDE ou o editor de texto de sua preferência que será utilizado para o desenvolvimento dos scripts de automação, porém para este tutorial utilizarei o VsCode com alguns plugins (Python, Robot Framework Intellisense, Hyper Term Theme , Pylance e Material Icon Theme), entretanto, a instalação do IDE e dos plugins estão fora do escopo deste tutorial, contudo a instalação é bem fácil, bastando acessar o site oficial do VsCode e seguir as orientações do guia do usuário.
Após concluída a instalação, crie um diretório (exemplo: rpa-project-exemplo/) para o projeto e abra-o com o IDE.

Antes de começar a desenvolver automações ou qualquer outro tipo de projeto em python, será necessário criar um ambiente virtual, para instalação da ferramenta rpapy e suas dependências, pois desta forma será possível isolar as dependências de cada projeto, bem como evitar o conflito entre versões das mesmas bibliotecas. Acesse o README.md do repositório github ou assista este vídeo no canal codigo100cera, onde é explicado o processo de instalação da ferramenta, desde a criação do ambiente virtual até a sua ativação.

Implantando a Automação de Exemplo

A ferramenta rpapy vem com um script de automação desktop de exemplo, o qual desenha e pinta na janela do programa mspaint da Microsoft. Essa automação é construída com scripts python e robotframework, com isso, quero mostrar o quanto pode ser flexível e poderoso utilizá-los em conjunto, e para que a RPA funcione, será preciso realizar alguns passos.

1) Primeiro você Precisa executar a ferramenta, então, se tudo ocorreu bem na preparação do ambiente, após a execução do comando rpapy no terminal, será exibido um menu de teclas de atalho como apresentado a seguir:

(rpa-project-exemplo-env)C:\rpa-project-exemplo>rpapy

***TURN ON AGENTPY***
        **************TECLAS DE ATALHO**************
        <CTRL>+<ALT>+P: CAPTURAR IMAGEM OU OCR
        <CTRL>+<ALT>+R: ALTERAR NOME DO ARQUIVO
        <CTRL>+<ALT>+B: ALTERNAR ENTRE OS BACKENDS
        <CTRL>+I:       INSPECIONAR ELEMENTO DE UI
        <CTRL>+<CMD>+C: EXIBIR CONFIGURAÇÃO ATUAL
        <CTRL>+<CMD>+E: UPLOAD IMPLEMENTAÇÃO EXEMPLO
        <CTRL>+<CMD>+X: DESLIGAR O AGENTE
        ********************************************
X:  407 Y:  360

Uma caixa de diálogo também será exibida solicitando a inserção do nome do arquivo de script onde será implementado o código de automação. Nela serão aceitas apenas nome de arquivos com as extensões .py ou .robot, por padrão ele vem com o nome main.robot, para este tutorial deixe o nome e extensão sugeridos pela ferramenta.

Se ocorreu tudo bem neste ponto a ferramenta já criou uma estrutura básica como a seguir:

-rpa-project-exemplo/
├── .env
├── resources/
│   ├── images/
│   └── keywords.robot
├── rpa-project-exemplo-env/
└── tasks/
    └── main.robot

Agora vamos carregar a implementação de exemplo pressionando a combinação de teclas <CTRL+CMD+E>.

<CTRL>+<CMD>+E: UPLOAD IMPLEMENTAÇÃO EXEMPLO

Após o acionamento da funcionalidade será exibido uma sequência de caixas de mensagens com avisos e decisões sobre substituições de arquivos que poderão ocorrer.

Leia com atenção todos os avisos e clique na opção OK para avançar ou CANCEL.

Muita atenção quando for solicitado a substituição de algum arquivo, se não desejar que o arquivo seja substituído, renomeie o arquivo que está no projeto antes de confirmar a substituição e depois continue.

A funcionalidade para carregar a implementação de exemplo sempre solicita a autorização para substituir os arquivos marcados com asterisco abaixo, quando estes já existirem:

-rpa-project-exemplo/
├── resources
│   ├── custom_keywords.py*
│   ├── desenhos
│   │   ├── borboleta.txt*
│   │   └── robotframework.txt*
│   └── keywords.robot*
└── tasks
    └── main.robot*

Quando concluído, o carregamento da implementação de exemplo, todos os scripts estão prontos para a execução, mas ainda será necessário efetuar a captura das imagens dos elementos de interface, em que serão aplicados às ações de teclado e mouse pela automação, desta forma será necessário realizar mais alguns passos.

2) Altere e salve o arquivo .env após tirar o # que está na frente das variáveis de ambiente MAX_WAIT_MANUTENCAO e VERIFICAR_MODO.

###VARIAVEIS DE AMBIENTE PYTHON-DOTENV

#RESOURCES_DIR_NAME=resources
#RESOURCES_KEYWORDS_FILE_NAME=keywords.robot
#IMAGES_DIR_NAME=images
#IMAGES_ERROR_DIR_NAME=images_error
#TASKS_DIR_NAME=tasks
MAX_WAIT_MANUTENCAO=5
VERIFICAR_MODO=True
#ARQUIVO_TEMPORARIO_ATIVO=False
#NOME_ARQUIVO_TEMPORARIO=temp.txt

A variável de ambiente VERIFICAR_MODO, ativa a verificação da escolha do modo manutenção toda vez que o script é iniciado, e a variável MAX_WAIT_MANUTENCAO, quando ativado o modo manutenção, tenta encontrar o elemento na tela em que irá aplicar alguma ação de teclado ou mouse, com a espera máxima em segundos que foi atribuida, se não for possível encontrar a imagem, ele solicitara que a existente seja substituída no projeto de forma iterativa, desta forma basta seguir os avisos que são emitidos com atenção.

3) Abra um novo terminal na raiz do projeto, ative o ambiente virtual e execute o seguinte comando:

(rpa-project-exemplo-env)C:\rpa-project-exemplo>robot -d log tasks

Em seguida será apresentado uma caixa de mensagem perguntando se pretende rodar a automação no modo manutenção, clique em sim, para ativar a funcionalidade e com isso atualizar o diretório images e concluir a instalação da automação de exemplo, incluindo todas as imagens necessárias. Essa é uma funcionalidade muito importante, porque facilita a implantação e atualização da automação em outros computadores de forma interativa sem a necessidade de manipulação do código implementado.

Assim que ativado o modo manutenção, no terminal será apresentado a saída abaixo.

(rpa-project-exemplo-env)C:\rpa-project-exemplo>robot -d log tasks
==================================================================
Tasks
==================================================================
Tasks.Main :: Documentação da Suite de Tasks Robot Framework
==================================================================
Tarefa principal                                  Hello Everybody!

4) A primeira ação da automação é abrir e maximizar o software de desenho mspaint, em seguida ele verificará se o ícone da barra de título do software foi encontrado, como ainda não existe nenhuma imagem no diretório, ele apresentará uma caixa de mensagem, informando o nome da imagem a ser alterada, e mostrará a visualização de uma imagem provisória com o aviso de imagem não encontrada, para continuar é preciso confirmar com um clique no botão OK da caixa de diálogo.

5) O processo de alteração da imagem é simples, pois basta ler as mensagens com atenção e efetuar as ações necessárias.
A próxima mensagem irá solicitar qual das seguintes opções deseja executar: IMG|IMG_OCR|OCR|CANCEL, para essa implantação será necessário apenas acionar a opção IMG.

6) Antes de selecionar o retângulo, para realizar a captura da imagem do elemento de interface, será apresentado uma caixa de mensagem com a opção de tempo de espera de 5s ou 10s antes de ser congelada a tela para a seleção.

7) Durante esse período de espera, você pode acionar algum menu ou qualquer elemento da interface para que no momento do congelamento da tela tudo esteja no ponto para a seleção do retângulo, assim que congelado, o ícone do mouse será alterado para um sinal de +, a partir desse momento é só pressionar o botão esquerdo do mouse no elemento da tela e arrastar para formar um retângulo sobre o elemento que será capturado uma imagem dele.

8) Agora será necessário indicar a região na tela, onde o elemento selecionado no passo anterior, deverá ser procurado pela automação. Então clique em OK e selecione retângulo da área que determinará região, observando que o tamanho da região deve ser maior que o tamanho da seleção do elemento de interface capturado. Isso serve para otimizar a procura da imagem pela automação, além de permitir uma maior flexibilidade com relação às coordenadas em que o elemento poderá surgir na tela sem causar erros.

Neste ponto selecione a região, que neste caso será área do retângulo pontilhado como na imagem a seguir.

O tamanho da região pode ser até o tamanho total da tela primária do computador.

9) Após a seleção será apresentado outra caixa de mensagem de confirmação, até este ponto será possível cancelar a alteração da imagem, mas depois de confirmado, não mais, então será apresentada a quantidade de imagens que serão substituídas.

10) A seguir Confirme em "SIM" para eliminar todas as imagens com o mesmo nome e "NAO" para manter todas.

11) Por fim será verificado se deseja visualizar a imagem que acabou de ser capturada, se optar em OK abrirá uma janela de visualização que fechará automaticamente após 5 segundos.

Após cada captura completada a ação programada é executada no elemento, esse é o ciclo completo para adição de imagens da automação no modo manutenção, agora basta repetir esses passos até completar todas as imagens necessárias para a instalação da implementação de exemplo.

Existem algumas particularidades quanto a captura de imagens de alguns componentes neste exemplo que irei descrever.

Os elementos campo de texto devem ser capturadas as imagens dos retângulos apenas dos rótulos e não do campo todo, como exibido na imagem a seguir, e no passo seguinte não esquecer de sempre selecionar uma região maior do que o tamanho do elemento capturado.

Um outro ponto que geralmente as pessoas travam, é exatamente no momento da captura do item do menu arquivo quando no modo manutenção, porque é necessário efetuar o clique no menu, para que ele expanda e seja possível que a automação identifique e efetue a ação. Como o clique, no menu arquivo, é realizado pela automação no passo anterior, se você não efetuar um clique manualmente, a automação não será capaz de encontrar a imagem na tela, porque o menu estará contraído. Desta forma, logo após a captura do item de menu propriedades, você deverá clicar rapidamente, mais precisamente antes de 5 segundos, pois é o tempo padrão configurado no arquivo .env para o tempo máximo de tentativas de busca da imagem na tela, quando no modo manutenção, desta forma se precisar de mais tempo basta mudar o valor da variável de ambiente MAX_WAIT_MANUTENCAO e reiniciar o script.

Quando completado todas as capturas de imagens, provavelmente o desenho no mspaint estará pronto e a implantação concluída.

Altere o arquivo .env comentando com #, como a seguir:

###VARIAVEIS DE AMBIENTE PYTHON-DOTENV

#RESOURCES_DIR_NAME=resources
#RESOURCES_KEYWORDS_FILE_NAME=keywords.robot
#IMAGES_DIR_NAME=images
#IMAGES_ERROR_DIR_NAME=images_error
#TASKS_DIR_NAME=tasks
#MAX_WAIT_MANUTENCAO=5
#VERIFICAR_MODO=True
#ARQUIVO_TEMPORARIO_ATIVO=False
#NOME_ARQUIVO_TEMPORARIO=temp.txt

Agora feche todas as janelas abertas do mspaint e execute novamente a implementação digitando o seguinte comando no terminal.

(rpa-project-exemplo-env)C:\rpa-project-exemplo>robot -d log tasks

Se tudo der certo, após a conclusão da automação a imagem estará desenhada na janela do mspaint e será apresentado no terminal o seguinte resultado.

Além do desenho dos logos, existe o desenho geométrico de uma borboleta, para que seja trocado a imagem que será desenhada, basta alterar a atribuição do valor robotframework para borboleta na variável ${NOME_IMAGEM} no arquivo tasks/main.robot

${NOME_IMAGEM}      robotframework

E execute novamente a automação.

(rpa-project-exemplo-env)C:\rpa-project-exemplo>robot -d log tasks

A automação deverá se comportar semelhantemente a execução apresentada neste gif animado, contido no README.me do projeto no github.

Conclusão

Neste tutorial não foram abordados todos os detalhes da sintax do robotframework, que poderá ser encontrado no guia do usuário do robotframework, e nem todas as funcionalidades da ferramenta rpapy, contudo assim que possível, criarei alguns vídeos no canal do youtube para explicar mais sobre essas elas.

Agradeço por você ter chegado até o fim deste tutorial, mas não deixe de seguir os seguintes passos: estude o código gerado, faça alterações e teste as alterações, porque se aprende, ainda muito mais, fazendo.

Então se você gostou deste tutorial entre no grupo do telegram, me siga nas redes sociais, entre no canal, inscreva-se e toque o sininho, para ser notificado quando for postados novos conteúdos.