Metadata-Version: 2.4
Name: devicefarm-caixa
Version: 1.0.0
Summary: Biblioteca Robot Framework para Device Farm
Author: Paulo Rogerio Moreira Rocha
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: robotframework
Requires-Dist: requests
Requires-Dist: python-dotenv
Requires-Dist: androguard
Requires-Dist: loguru


# 📱 DeviceFarm Robot Libraries

Biblioteca desenvolvida para simplificar a integração entre projetos Robot Framework e a plataforma DeviceFarm.

O objetivo da biblioteca é abstrair a comunicação com a API do DeviceFarm, permitindo que os testes automatizados realizem operações de gerenciamento de dispositivos e aplicativos sem que o usuário precise implementar chamadas REST, autenticação ou tratamento de erros manualmente.

## 🚀 O que a biblioteca faz

A biblioteca disponibiliza recursos para:

- 📱 Reservar dispositivos automaticamente para execução de testes.
- 🔄 Selecionar dispositivos disponíveis de forma inteligente.
- 🚫 Tratar conflitos de reserva de workspace.
- 📦 Realizar upload de aplicativos para o DeviceFarm.
- 📲 Instalar aplicações nos dispositivos reservados.
- 🔐 Gerenciar autenticação com a API do DeviceFarm através de variáveis de ambiente.
- 📋 Centralizar logs e informações de execução para troubleshooting.
- ⚙️ Facilitar a reutilização da integração entre múltiplos projetos Robot Framework.

## 🎯 Benefícios

Utilizando esta biblioteca, os times de automação podem:

- Reduzir a complexidade de integração com o DeviceFarm.
- Padronizar a utilização da plataforma entre diferentes projetos.
- Evitar duplicação de código de autenticação e chamadas de API.
- Aumentar a confiabilidade do processo de reserva e instalação de aplicativos.
- Centralizar a manutenção da integração em uma única biblioteca compartilhada

---

# 🚀 Funcionalidades

## ✅ DeviceFarmLibrary

- Seleção inteligente de dispositivos
- Reserva automática
- Fallback em caso de indisponibilidade
- Tratamento de conflito de workspace
- Logs estruturados

## ✅ UploadAppLibrary

- Upload de APK para o DeviceFarm
- Leitura automática de metadados
- Instalação do aplicativo em dispositivos reservados
- Controle de estado via install_state.json
- Tratamento de erros de upload

---

# 📥 Instalação

## 1. Clonar a biblioteca

Clone o projeto na pasta:

C:\Desenvolvimento\SIAFS-devicefarm-library


## 🏗️ Arquitetura

A biblioteca foi projetada para ser utilizada como dependência compartilhada entre projetos Robot Framework.

Cada projeto consumidor possui seu próprio arquivo `.env`, contendo as credenciais e configurações necessárias para acesso ao DeviceFarm, enquanto a lógica de integração permanece centralizada nesta biblioteca.


```
DeviceFarmLibrary/
│
├── DeviceFarmLibrary.py     # Reserva de dispositivos
├── UploadAppLibrary.py      # Upload e instalação de apps
├── apks/                    # Pasta de aplicativos
└── install_state.json       # Controle de estado de instalação
```

> Recomenda-se manter a biblioteca exatamente nesse local para padronizar a configuração entre os projetos.

---

## 2. Configurar o VS Code

Abra o projeto consumidor normalmente no VS Code.

### Localizando o arquivo settings.json

Pressione:

CTRL + P

Digite:

settings.json

E abra o arquivo de configurações do Workspace.

Caso sua equipe utilize Profiles do VS Code, as mesmas configurações também podem ser adicionadas ao Profile utilizado para automação Robot Framework.

---

## 3. Adicionar a biblioteca ao Python Path

No settings.json, adicione:

```json
{
    "robotcode.robot.pythonPath": [
        "C://PythonPath//venv//Scripts//python.exe",
        "C://PastaDesenvolvimento//devicefarm-library"
    ]
}
```

### Exemplo

```json
{
    "robotcode.robot.pythonPath": [
        "C://PythonPath//venv//Scripts//python.exe",
        "C://PastaDesenvolvimento//devicefarm-library"
    ]
}
```

## 4. Configurar o arquivo .env

Ainda no settings.json, adicione:

```json
{
    "robotcode.robot.env": {
        "ENV_FILE": "${workspaceFolder}/.env"
    }
}
```

Essa configuração informa à biblioteca onde está localizado o arquivo .env do projeto consumidor.

---

# ⚙️ Criando o arquivo .env

Crie um arquivo .env na raiz do projeto.

Exemplo:

```env
DEVICEFARM_BASE_URL=https://seu-devicefarm/rest
DEVICEFARM_TENANT_ID=999999999
DEVICEFARM_WORKSPACE_ID=workspace-id
DEVICEFARM_CLIENT_ID=client-id
DEVICEFARM_CLIENT_SECRET=client-secret
DEVICEFARM_APP_FOLDER=./resources/apks
DEVICEFARM_STATE_FILE=./resources/apks/install_state.json
```

---

# ✅ Variáveis obrigatórias

- DEVICEFARM_BASE_URL
- DEVICEFARM_TENANT_ID
- DEVICEFARM_WORKSPACE_ID
- DEVICEFARM_CLIENT_ID
- DEVICEFARM_CLIENT_SECRET

---

# 📦 Dependências

```bash
pip install requests
pip install loguru
pip install robotframework
pip install androguard
pip install python-dotenv
```

---

# 🤖 Utilização com Robot Framework

```robot
### 🔹 Exemplo de uso
*** Configurações ***
Library    DeviceFarmLibrary
Library    UploadAppLibrary

Suite Setup         Run Keywords   Reservar dispositivo
...                 AND            Instalar Aplicativo

*** Variáveis ***
${DEVICES}      ABCD     1234   ABCD1234
@{APP_VERSAO}   1.8.3    185    ANDROID

*** Keywords ***
Reservar dispositivo
    Log To Console    \nReservando dispositivo da lista ${DEVICES}
    ${UDID}     Seleciona Dispositivo Pronto Para Uso    ANDROID    ${DEVICES} 

Instalar Aplicativo
    Upload E Instalar Aplicativo    device_id=${UDID}    app_versao=${APP_VERSAO}    app_identifier=${PACKAGE}
   
```

---

## 🧾 Logs

- Logs padrão via `logging`
- Logs detalhados adicionais via `loguru`
- Logs incluem:
  - Reservas
  - Uploads
  - Erros
  - Conflitos

---

## ⚠️ Tratamento de Erros

### Tipos de exceções:

- `WorkspaceConflict`
- `UploadError`

---

## 🔄 Controle de Estado

O arquivo `install_state.json` armazena:

- Última versão instalada
- Evita reinstalação desnecessária
- Mantém consistência entre sessões

---

# 🛠️ Boas Práticas

✅ Utilizar um .env por projeto

✅ Não versionar credenciais

✅ Utilizar logs para troubleshooting

✅ Separar APKs por ambiente

---

# 👨‍💻 Autores

**Caio Torres Rocha**
https://linkedin.com/in/kcaioqa/

**Paulo Rogério Moreira Rocha**
https://linkedin.com/in/prmoreirarocha/

---

# 📅 Versão

**1.1 — Julho/2026**

# TODO
Melhorias que temos que implementar antes da integração.
- Caso o dispositivo tenha uma agendamento futuro ele apresenta erro na tentativa de agendamento.
DONE - Usar o install_state para facilitar o reuso de sessão
Melhorar arquitetura do projeto
Implementar logs para facilitar debug, como foi feito no projeto de automação de massas.
 
Passo a passo para execução.
 
PASSO 1 - Verificar o install_state. Dispositivo e Versão/build estão 
de acordo com a reserva feita e com a Versão/build informada no script?
	SIM: Segue a automação
	NÃO: Segue para PASSO 2
 
PASSO 2 - O Script menciona Versão/build especifica para ser testada?
	SIM: Segue para PASSO 3
	NÃO: Segue para PASSO 7
PASSO 3 - Versão/build aparece no cashe de apk enviado para o devicefarm?
	SIM: Segue para PASSO 4
	NÃO: Segue para PASSO 5
 
PASSO 4 - O apk esta instalado é o que esta descrito no Script?
	SIM: Segue a automação
	NÃO: Instala o apk no dispositivo e Segue a automação
 
PASSO 5 - O APK está na pasta local para upload?
	SIM: Realiza o upload e volta para a PASSO 4
	NÃO: Segue para PASSO 6
PASSO 6 - A Versão/build informada existe no firebase?
	SIM: Realiza o download e volta para a PASSO 5
	NÃO: Lançar exceção informando que Versão/build não existe e que seja corrigido o número
PASSO 7 - O dispositivo já possui alguma Versão/build instalada?
	SIM: Segue a automação
	NÃO: Segue para PASSO 8
PASSO 8 - O dispositivo não possui Versão/build instalada?
	SIM: Instala a ultima versão disponivel no devicefarm
	NÃO: Lança exceção solicitando instalação no dispositivo ou a Versão/build para o teste.
