Apredendo a utilizar a ferramenta RPAPY com exemplo
Published: 2021-02-03 23:21:13

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/egyr0pa313pqxn7ji31a.png)
 
### 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](https://pypi.org/project/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](https://code.visualstudio.com/#alt-downloads) 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](https://code.visualstudio.com/#alt-downloads) 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](https://github.com/codigo100cera/rpapy/blob/master/README.md) do repositório github ou [assista este vídeo](https://youtu.be/IcRl7WUL7rk) no canal [codigo100cera](https://www.youtube.com/channel/UCbrw7-reRWpQD1JBubCl4QQ?view_as=subscriber), 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](https://robotframework.org/)**, 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.
 
![](https://dev-to-uploads.s3.amazonaws.com/i/i9gyw9th6p1mgo005l4n.png)
 
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.
 
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/7bnw252b31o0s1gktzqf.png)
 
Leia com atenção todos os avisos e clique na opção OK para avançar ou CANCEL.
 
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/wuu0oc19zlx2okoor4f6.png)
 
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.
 
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/5tyr7sxybe0ck5jgii9k.png)
 
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.
 
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/vi43bae8qga8rbumj56f.png)
 
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.
 
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/iqx0c1rgnqcx8hlks8k3.png)
 
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.
 
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/hbrb5wxbgzv9he735wbs.png)
 
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.
 
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/tfct6jiibqx9iswzpjd5.png)
 
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.
 
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/r1dqg4q8jcds2dj94xm4.png)
 
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.
 
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/wmvu0g5147rg58zsnq2n.png)
 
Neste ponto selecione a região, que neste caso será área do retângulo pontilhado como na imagem a seguir.
 
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/jbmhdzr30ku8jyvxu5mw.png)
 
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.
 
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/dai4comj1pfsugkkgefc.png)
 
10) A seguir Confirme em "SIM" para eliminar todas as imagens com o mesmo nome e "NAO" para manter todas.
 
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/s7uowpqb4143r814ipgr.png)
 
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.
 
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/lfkbjnumb0y6fcf3b5q2.png)
 
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.
 
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/iou0karsgankxxhqr58j.png)
 
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. 
 
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/hvodoux5znr8115m6kfa.png)
 
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.
 
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/4vzv21n9m97zazej0tfz.png)
 
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](https://github.com/codigo100cera/rpapy/blob/master/README.md), contido no README.me do projeto no github.
 
 
 
### Conclusão
Neste tutorial não foram abordados todos os detalhes da sintax do [robotframework](https://robotframework.org/), que poderá ser encontrado no **[guia do usuário do robotframework] (https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html)**, e nem todas as funcionalidades da ferramenta [rpapy](https://github.com/codigo100cera/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](https://t.me/joinchat/VahJp4lsIBSN8zff), me siga nas redes sociais, entre no [canal](https://www.youtube.com/channel/UCbrw7-reRWpQD1JBubCl4QQ?view_as=subscriber), inscreva-se e toque o sininho, para ser notificado quando for postados novos conteúdos.