# Appium
  
Módulo para automatizar dispositivos móveis  

*Read this in other languages: [English](Manual_Appium.md), [Português](Manual_Appium.pr.md), [Español](Manual_Appium.es.md)*
  
![banner](imgs/Banner_Appium.jpg)
## Como instalar este módulo
  
Para instalar o módulo no Rocketbot Studio, pode ser feito de duas formas:
1. Manual: __Baixe__ o arquivo .zip e descompacte-o na pasta módulos. O nome da pasta deve ser o mesmo do módulo e dentro dela devem ter os seguintes arquivos e pastas: \__init__.py, package.json, docs, example e libs. Se você tiver o aplicativo aberto, atualize seu navegador para poder usar o novo módulo.
2. Automático: Ao entrar no Rocketbot Studio na margem direita você encontrará a seção **Addons**, selecione **Install Mods**, procure o módulo desejado e aperte instalar.  



# Instruções de pré-configuração para usar o módulo Appium


## Instalações anteriores
Para poder usar o módulo, é necessário instalar dependências como npm, nodejs, java e Android Studio, também é necessário configurar certas variáveis ​​de ambiente no sistema. Para poder configurar tudo corretamente, você pode executar o comando Configure Appium do módulo para detectar automaticamente o que precisa ser instalado ou configurado. Você também pode seguir as etapas abaixo.


### Instalação manual do Appium e uiautomator2
Para poder instalar e configurar o Appium e o uiautomator2, é necessário instalar o npm e o nodejs. Para fazer isso, você pode seguir o seguinte [link](https://nodejs.org/en/download/). Depois de instalado o npm, você pode seguir o seguinte [link](http://appium.io/docs/en/2.1/quickstart/install/) para baixar e instalar o Appium e o seguinte [link](http://appium.io/docs/en/2.1/quickstart/uiauto2-driver/) para baixar e instalar o driver.


### Download e instalação do 
Android Studio e SDK Tools
O módulo usa ferramentas do kit de software do Android Studio (SDK Tools), portanto, é necessário instalá-lo. Para fazer isso, você pode baixá-lo no seguinte [link](https://developer.android.com/studio). Depois de baixado, você deve executar o instalador e seguir as etapas indicadas. É recomendável instalar no local padrão para evitar erros na execução. Para baixar as SDK Tools, você deve acessar o Android Studio. No menu superior, você deve ir para a opção Tools > SDK Manager. Na janela que se abre, você deve selecionar a guia SDK Tools. Na lista de ferramentas, você deve selecionar `Android SDK Build-Tools`, `Android Emulator`, `Android SDK Platform-Tools` e clicar em Apply. Depois de tudo baixado, você deve adicionar ao path do sistema os caminhos para as pastas usadas pelas ferramentas `emulator` e `platform-tools`. Um exemplo de caminho é `C:\Users\user\AppData\Local\Android\Sdk\emulator` (substitua o usuário pelo nome de usuário do computador). 
Verifique a seção correspondente para ver como adicionar variáveis ​​de ambiente.


### Download e instalação do Java
Para instalar o Java, você pode seguir o seguinte [link](https://www.java.com/en/download/). Depois de baixado, você deve executar o instalador e seguir as etapas indicadas. Após a instalação, reinicie a máquina. É recomendável instalar no local padrão para evitar erros na execução. Para verificar se tudo foi feito corretamente, após a reinicialização, você pode abrir um prompt de comando e digitar java -version. Se tudo estiver bem, a versão do Java instalada deve aparecer.


## Adicionar variáveis ​​de ambiente
Para executar os comandos do módulo, você precisa ter certos caminhos adicionados ao PATH do sistema para que tudo funcione corretamente. Para fazer isso, siga estas etapas:
1. Na barra de pesquisa do Windows, digite Variáveis ​​de ambiente e selecione a opção Editar variáveis ​​de ambiente do sistema.
2. Na janela que se abre, selecione Variáveis ​​de 
ambiente.
3. Na nova janela, você deve criar uma nova variável do sistema. Como nome, escreva ANDROID_HOME e como valor o caminho absoluto para a pasta onde as Android SDK Tools estão instaladas. Por padrão, é: `C:\Users\user\AppData\Local\Android\Sdk` (substitua o usuário pelo nome de usuário do computador).
4. Em seguida, na janela Variáveis ​​de ambiente, selecione a variável do usuário Path e clique em Editar.
5. Na nova janela, clique em Novo e adicione o mesmo caminho usado na etapa anterior adicionando a pasta `platform-tools` no final. Por exemplo, `C:\Users\user\AppData\Local\Android\Sdk\platform-tools` (substitua o usuário pelo nome de usuário do computador). Você também deve fazer o mesmo, mas com a pasta `emulator`. Por exemplo `C:\Users\user\AppData\Local\Android\Sdk\emulator` (substitua o usuário pelo nome de usuário do computador).
6. Por fim, clique em OK em todas as janelas e reinicie o computador.
7. Para verificar se tudo foi feito corretamente, abra um prompt de 
comando e digite adb. Se tudo estiver bem, uma lista de comandos disponíveis deve aparecer.
8. Após concluir estas etapas, você pode prosseguir para executar os comandos do módulo. Como recomendação, você pode executar o comando Configure Appium para verificar se nada ficou pendente.


## Configuração do dispositivo Android
### Essas etapas são necessárias apenas se você quiser se conectar a um dispositivo Android físico. Se você quiser se conectar a um dispositivo emulado, deverá seguir a seção Criar um dispositivo emulado.
Para conectar o dispositivo corretamente, é necessário configurar o dispositivo Android para aceitar a conexão, seja por USB ou por WiFi. Para fazer isso, siga estas etapas:
1. Ative as opções do desenvolvedor: No dispositivo, vá para Configurações > Sobre o telefone > Número da compilação. Toque no número da compilação 7 vezes. Uma mensagem aparecerá dizendo que você agora é um desenvolvedor.
2. Ative a depuração USB: No dispositivo, vá para Configurações > 
Sistema > Opções do desenvolvedor e ative a depuração USB.
3. Ative a depuração sem fio: No dispositivo, vá para Configurações > Sistema > Opções do desenvolvedor e ative a depuração sem fio.
4. Se você deseja usar a conexão sem fio (WIFI), deve parear o dispositivo para que ele possa se conectar. Para fazer isso, você deve usar o comando Link device uma vez.
5. Se você deseja usar a conexão USB, deve conectar o dispositivo ao computador usando o cabo USB. Em seguida, você deve executar o comando Connect device.
6. Se tudo foi configurado corretamente, o comando Connect Android deve retornar True.


## Inspetor Appium
A ferramenta Appium possui um inspetor para poder visualizar os elementos da tela do dispositivo. Para baixá-lo, você pode seguir o seguinte [link](https://github.com/appium/appium-inspector/releases)


### Use o inspetor Appium
Ao descompactar a ferramenta, você pode executar o Appium Inspector.exe, que abrirá a janela da ferramenta. Para conectar o dispositivo Android 
que foi conectado usando o módulo no Rocketbot, você deve ir para a guia `Attach to Session ...` e depois no botão de recarregar ao lado da entrada para inserir o ID. Se tudo foi configurado corretamente, uma string deve aparecer na entrada onde o ID da conexão, o dispositivo, seu ip e porta e o driver uiautomator2 são indicados. Em seguida, você deve clicar no botão Attach to Session. Isso abrirá uma nova janela do inspetor mostrando as informações do dispositivo.

### Criar um dispositivo emulado
Para poder criar um dispositivo emulado, você deve abrir o Android Studio e criar um novo projeto. Na janela que se abre, do lado direito você terá o Device Manager (Se não estiver aberto, na barra lateral direita você pode abri-lo). Você deve clicar em Create Device. Em seguida, você deve selecionar o dispositivo que deseja emular e clicar em Avançar. Na próxima janela, você deve selecionar a versão do Android que deseja emular e clicar em Avançar. Na última janela, você deve verificar a 
configuração do dispositivo e clicar em Concluir. Feito isso, você deve executar o comando Connect emulated device para poder usá-lo.



## Descrição do comando

### Configurar Appium
  
Este comando verifica se você instalou as dependências necessárias para executar o Appium. Ele tentará instalar alguns, mas não todos. Para aqueles em que o Rocketbot não puder, ele gerará um erro indicando as etapas a seguir para instalá-los manualmente. É recomendável executar este comando apenas para validar se você possui as dependências necessárias e não incluí-lo na versão do bot que é implantada em produção.
|Parâmetros|Descrição|exemplo|
| --- | --- | --- |
|Atribuir resultado a variável|Atribuir resultado da configuração a uma variável|result|

### Emparelhar dispositivo
  
Este comando permite emparelhar um dispositivo Android com a máquina que você deseja conectar. Esta etapa é necessária para realizar apenas uma vez por dispositivo se você deseja se conectar via WIFI.
|Parâmetros|Descrição|exemplo|
| --- | --- | --- |
|IP e porta do dispositivo|IP e porta do dispositivo Android que você deseja conectar|ip:port|
|Código de emparelhamento WIFI|Código de emparelhamento WIFI do dispositivo Android que você deseja emparelhar|876543|
|Atribuir resultado a variável|Atribuir resultado da conexão a uma variável|result|

### Conectar Android
  
Este comando permite conectar um dispositivo Android e configurar o servidor utilizando Android Debug Bridge (ADB). As opções do desenvolvedor devem estar ativadas no dispositivo e a depuração sem fio ou USB conforme apropriado.
|Parâmetros|Descrição|exemplo|
| --- | --- | --- |
|IP e porta do dispositivo|IP e porta do dispositivo Android que você deseja conectar|ip:port|
|Tipo de conexão|Tipo de conexão a ser usada|USB|
|Tipo de desbloqueio|Tipo de desbloqueio a ser usado|PIN|
|Código de desbloqueio|Código de desbloqueio do dispositivo Android que você deseja conectar|1234|
|Permitir shell|Permite executar comandos usando o terminal no dispositivo Android. É um recurso inseguro. Para mais informações, consulte https//appium.io/docs/en/2.0/guides/security/|True|
|Atribuir resultado a variável|Atribuir resultado da conexão a uma variável|result|

### Listar dispositivos emulados
  
Este comando permite listar os dispositivos emulados disponíveis.
|Parâmetros|Descrição|exemplo|
| --- | --- | --- |
|Atribuir resultado a variável|Atribuir resultado da operação a uma variável|result|

### Conectar Dispositivo Emulado
  
Este comando permite conectar um dispositivo emulado e configurar o servidor. Se esta for a primeira vez que você executa o emulador, pode levar alguns minutos para iniciar.
|Parâmetros|Descrição|exemplo|
| --- | --- | --- |
|Nome do emulador|Nome do emulador que você deseja conectar|Pixel_7_Pro_API_34|
|Permitir shell|Permite executar comandos usando o terminal no dispositivo Android. É um recurso inseguro. Para mais informações, consulte https//appium.io/docs/en/2.0/guides/security/|True|
|Tipo de desbloqueio|Tipo de desbloqueio a ser usado|PIN|
|Código de desbloqueio|Código de desbloqueio do dispositivo Android que você deseja conectar|1234|
|Atribuir resultado a variável|Atribuir resultado da conexão a uma variável|result|

### Bloquear dispositivo
  
Este comando permite bloquear um dispositivo Android.
|Parâmetros|Descrição|exemplo|
| --- | --- | --- |
| --- | --- | --- |

### Desbloquear Dispositivo
  
Este comando permite desbloquear um dispositivo Android. Disponível apenas se o tipo e o código de desbloqueio tiverem sido definidos no comando de conexão.
|Parâmetros|Descrição|exemplo|
| --- | --- | --- |
| --- | --- | --- |

### Obter informações do aplicativo atual
  
Este comando permite obter o nome do pacote e o nome da atividade do aplicativo que está sendo executado atualmente no dispositivo Android.
|Parâmetros|Descrição|exemplo|
| --- | --- | --- |
|Atribuir resultado à variável|Nome da variável na qual o resultado será atribuído.|variável|

### Iniciar aplicação
  
Este comando permite iniciar um aplicativo no dispositivo Android. Para obter o nome do pacote e o nome da atividade, você pode usar o comando Obter informações do aplicativo atual
|Parâmetros|Descrição|exemplo|
| --- | --- | --- |
|Nome do pacote|Nome do pacote do aplicativo que você deseja iniciar.|com.android.Settings|
|Nome da atividade|Nome da atividade do aplicativo que você deseja iniciar.|.Settings|
|Atribuir resultado à variável|Nome da variável na qual o resultado será atribuído.|variável|

### Swipe simples
  
Esse comando permite que você faça um simples swipe na tela do dispositivo Android.
|Parâmetros|Descrição|exemplo|
| --- | --- | --- |
|Direção do swipe|Direção que o swipe terá na tela do dispositivo.|Right|

### Toque nas coordenadas
  
Este comando permite tocar em uma coordenada específica na tela.
|Parâmetros|Descrição|exemplo|
| --- | --- | --- |
|Coordenada X|Coordenada X onde o toque será realizado|100|
|Coordenada Y|Coordenada Y onde o toque será realizado|100|

### Toque no elemento
  
Este comando permite tocar em um elemento específico na tela.
|Parâmetros|Descrição|exemplo|
| --- | --- | --- |
|Tipo de dado|Tipo de dado do seletor no qual o toque será realizado.|id|
|Seletor|Seletor no qual o toque será realizado.|com.whatsapp:id/entry|
|Atribuir resultado à variável|Nome da variável na qual o resultado será atribuído.|variável|

### Enviar teclas
  
Esse comando permite enviar teclas para um seletor específico no dispositivo Android.
|Parâmetros|Descrição|exemplo|
| --- | --- | --- |
|Tipo de dado|Tipo de dado do seletor no qual as teclas serão enviadas.|id|
|Seletor|Seletor no qual as teclas serão enviadas.|com.whatsapp:id/entry|
|Teclas|Teclas a serem enviadas para o seletor.|Olá mundo!|

### Extrair texto
  
Este comando permite obter o texto de um seletor específico do dispositivo Android.
|Parâmetros|Descrição|exemplo|
| --- | --- | --- |
|Tipo de dado|Tipo de dado do seletor no qual as teclas serão enviadas.|id|
|Seletor|Seletor no qual as teclas serão enviadas.|com.whatsapp:id/entry|
|Atribuir resultado à variável|Nome da variável na qual o resultado será atribuído.|variável|

### Extrair texto por coordenadas
  
Este comando permite obter o texto de um elemento localizado em uma posição específica do dispositivo Android.
|Parâmetros|Descrição|exemplo|
| --- | --- | --- |
|Coordenadas x,y|Coordenadas x,y do elemento para obter o texto.|450,2000|
|Atribuir resultado à variável|Nome da variável na qual o resultado será atribuído.|variável|

### Zoom em coordenadas
  
Este comando permite dar zoom in ou zoom out nas coordenadas especificadas no dispositivo Android.
|Parâmetros|Descrição|exemplo|
| --- | --- | --- |
|Tipo de zoom|Tipo de zoom a realizar.|Zoom in|
|Coordenadas x,y|Coordenadas x,y onde o zoom será realizado.|450,2000|
|Pixels a deslocar|Pixels a deslocar no zoom.|500|
|Velocidade de zoom|Velocidade de zoom a realizar.|Normal|

### Zoom em objeto
  
Este comando permite dar zoom in ou zoom out em um objeto no dispositivo Android.
|Parâmetros|Descrição|exemplo|
| --- | --- | --- |
|Tipo de zoom|Tipo de zoom a realizar.|Zoom in|
|Tipo de dado|Tipo de dado do seletor no qual o zoom será realizado.|id|
|Seletor|Seletor no qual realizará o zoom|com.whatsapp:id/entry|
|Pixels a deslocar|Pixels a deslocar no zoom.|500|
|Velocidade de zoom|Velocidade de zoom a realizar.|Normal|

### Captura de tela
  
Este comando permite capturar a tela do dispositivo Android e armazenar a imagem no caminho especificado.
|Parâmetros|Descrição|exemplo|
| --- | --- | --- |
|Caminho da imagem|Caminho no qual a imagem será armazenada.|C:/Users/User/Desktop/imagen.png|

### Executar comando no dispositivo
  
Este comando permite executar um comando no terminal do dispositivo Android. Para executar este comando corretamente, a caixa de seleção Permitir shell no comando de conexão deve estar marcada.
|Parâmetros|Descrição|exemplo|
| --- | --- | --- |
|Comando|Comando a ser executado no terminal do dispositivo.|pm list packages|
|Atribuir resultado à variável|Nome da variável na qual o resultado será atribuído.|variável|

### Aguardar por objeto
  
Este comando permite aguardar por um objeto no dispositivo Android. O comando será executado até que o objeto seja encontrado ou até que o tempo máximo de espera seja atingido.
|Parâmetros|Descrição|exemplo|
| --- | --- | --- |
|Tipo de dado|Tipo de dado do seletor a ser pesquisado.|id|
|Seletor|Seletor do objeto a ser pesquisado.|com.whatsapp:id/toolbar|
|Tempo máximo de espera|Nome da variável na qual o resultado da pesquisa será atribuído.|10|
|Atribuir resultado à variável|Nome da variável na qual o resultado da pesquisa será atribuído.|variável|

### Desconectar dispositivo
  
Este comando permite desconectar o dispositivo Android ou emulado que está sendo automatizado.
|Parâmetros|Descrição|exemplo|
| --- | --- | --- |
| --- | --- | --- |
