🏗️ Guia de Arquitetura

📋 Índice

• Visão Geral
• Estrutura de Pastas
• Padrões de Design
• Fluxo de Execução
• Decisões Técnicas

Visão Geral

O Etec.WebfopagAutomation segue uma arquitetura modular e escalável baseada em:

• 🎯 Page Object Model (POM) - Separação entre testes e elementos de página
• 🔧 Keywords Customizadas - Reutilização de código
• 📦 Bibliotecas Python - Lógica complexa em Python quando necessário
• 🚀 CI/CD Ready - Integração com Azure DevOps

Estrutura de Pastas

Etec.WebfopagAutomation/
│
├── 📁 azure/                    # Integração Azure DevOps
│   ├── main.py                  # Orquestrador principal
│   ├── crud_steps.py            # Operações CRUD nos Work Items
│   └── api/                     # APIs de comunicação
│       ├── azure_devops.py      # Cliente Azure DevOps
│       ├── config.py            # Configurações
│       ├── results_parser.py    # Parser de resultados
│       └── image_utils.py       # Processamento de imagens
│
├── 📁 resources/                # Recursos de Automação
│   ├── common/                  # Keywords e Variáveis Globais
│   │   ├── all_common.robot            # Importa tudo
│   │   ├── common_variables.robot      # Variáveis globais
│   │   ├── interaction_keywords.robot  # Interações UI
│   │   ├── modal_keywords.robot        # Modais e diálogos
│   │   ├── utils_keywords.robot        # Utilitários
│   │   ├── waits_keywords.robot        # Esperas e timeouts
│   │   └── webfopag_api_keywords.robot # APIs do WebFopag
│   │
│   ├── libs/                    # Bibliotecas Python Customizadas
│   │   ├── custom_selenium.py           # Extensões Selenium
│   │   ├── fake_generator_doc.py        # Gerador de CPF/CNPJ
│   │   ├── criptografia_*.py            # Criptografia
│   │   └── lock_wrapper.py              # Controle de concorrência
│   │
│   └── pages/                   # Page Objects (POM)
│       ├── login/
│       │   ├── login_pages.robot        # Keywords da página
│       │   └── login_variables.robot    # Locators e variáveis
│       └── mais_opcoes/
│           ├── administracao_do_sistema/
│           ├── pessoa_fisica/
│           └── relatorios/
│
├── 📁 tests/                    # Testes Automatizados
│   ├── login/
│   │   └── login_tests.robot
│   └── mais_opcoes/
│       ├── administracao_do_sistema/
│       ├── pessoa_fisica/
│       ├── lancamentos/
│       ├── registro_de_emprego/
│       └── relatorios/
│
├── 📁 scripts/                  # Scripts de Qualidade
│   ├── format.ps1               # Formatação automática
│   ├── lint.ps1                 # Linting com Robocop
│   └── quality-check.ps1        # Check completo
│
├── 📁 docs/                     # Documentação (você está aqui!)
│   ├── guides/
│   ├── api/
│   └── examples/
│
├── 📁 utilities/                # Recursos estáticos
│   ├── image/                   # Imagens para referência
│   └── readme/
│
├── azure-pipelines.yml          # Pipeline CI/CD
├── requirements.txt             # Dependências Python
└── README.md                    # Documentação principal

Padrões de Design

1. Page Object Model (POM)

Cada página da aplicação tem dois arquivos:

pages.robot - Keywords de Ações

*** Settings ***
Resource    login_variables.robot

*** Keywords ***
Fazer Login Com Usuário
    [Arguments]    ${usuario}    ${senha}
    Preencher Campo Usuario    ${usuario}
    Preencher Campo Senha    ${senha}
    Clicar Botao Entrar

variables.robot - Locators e Constantes

*** Variables ***
# Locators
${INPUT_USUARIO}        id=username
${INPUT_SENHA}          id=password
${BTN_ENTRAR}           css=button[type="submit"]

# Constantes
${TITULO_PAGINA}        Autenticação WebFopag
${MSG_ERRO_LOGIN}       Credenciais inválidas

Vantagens:

• ✅ Manutenção centralizada de locators
• ✅ Testes independentes de implementação UI
• ✅ Reutilização de código

2. Hierarquia de Keywords

📊 Camadas de Abstração

┌─────────────────────────────────────────┐
│  TESTES (tests/)                         │  ← Lógica de negócio
│  Test Case 72844: Login Correto          │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│  PAGE KEYWORDS (resources/pages/)        │  ← Ações da página
│  Fazer Login Com Usuario                 │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│  COMMON KEYWORDS (resources/common/)     │  ← Ações genéricas
│  Preencher Campo    Clicar Botão         │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│  SELENIUM LIBRARY                        │  ← Interação com browser
│  Input Text    Click Element             │
└─────────────────────────────────────────┘

Princípio: Cada camada só conhece a camada imediatamente abaixo.

3. Padrão de Nomenclatura

Testes

Test Case [ID]: [Descrição Clara]
    [Tags]    testcase=[ID]    [categoria]

Keywords

# Ações = Verbos no Infinitivo
Fazer Login
Cadastrar Usuario
Validar Mensagem

# Validações = Deve/Devem
Deve Exibir Mensagem De Sucesso
Devem Ser Exibidos Os Dados Corretos

Variáveis

# Globais = MAIÚSCULAS
${BASE_URL}
${TIMEOUT_DEFAULT}

# Locais = minúsculas com underscore
${usuario_logado}
${total_registros}

# Locators = prefixo com tipo
${BTN_SALVAR}        # Button
${INPUT_NOME}        # Input
${LBL_TITULO}        # Label
${DDL_ESTADO}        # Dropdown List

4. Gerenciamento de Esperas

❌ Nunca Use Sleep Fixo

# RUIM - tempo fixo e imprevisível
Sleep    5s
Click Element    ${BTN_SALVAR}

✅ Use Esperas Inteligentes

# BOM - espera até condição ser atendida
Wait Until Element Is Visible    ${BTN_SALVAR}    timeout=10s
Click Element    ${BTN_SALVAR}

Keywords de Espera Disponíveis:

# Em resources/common/waits_keywords.robot
Aguardar Elemento Visivel
Aguardar Elemento Clicavel
Aguardar Texto Aparecer
Aguardar Pagina Carregar

5. Tratamento de Modais

Modais e pop-ups têm keywords específicas:

# Em resources/common/modal_keywords.robot
Aceitar Modal De Confirmacao
Rejeitar Modal De Confirmacao
Validar Mensagem Modal    ${mensagem_esperada}
Fechar Modal

Fluxo de Execução

1. Inicialização

┌──────────────────────────────────────┐
│ 1. Robot Framework Inicia            │
└──────────────────────────────────────┘
              ↓
┌──────────────────────────────────────┐
│ 2. Carrega Settings                  │
│    - Bibliotecas                     │
│    - Resources                       │
│    - Variáveis                       │
└──────────────────────────────────────┘
              ↓
┌──────────────────────────────────────┐
│ 3. Executa Suite Setup (se houver)  │
└──────────────────────────────────────┘

2. Execução de Teste

┌──────────────────────────────────────┐
│ 1. Test Setup                        │
│    → Abrir Navegador                 │
└──────────────────────────────────────┘
              ↓
┌──────────────────────────────────────┐
│ 2. Executa Passos do Teste           │
│    - Dado que...                     │
│    - Quando...                       │
│    - Então...                        │
└──────────────────────────────────────┘
              ↓
┌──────────────────────────────────────┐
│ 3. Test Teardown                     │
│    → Fechar Navegador                │
│    (mesmo se teste falhar)           │
└──────────────────────────────────────┘

3. Finalização

┌──────────────────────────────────────┐
│ 1. Suite Teardown (se houver)       │
└──────────────────────────────────────┘
              ↓
┌──────────────────────────────────────┐
│ 2. Gera Relatórios                   │
│    - output.xml                      │
│    - log.html                        │
│    - report.html                     │
└──────────────────────────────────────┘
              ↓
┌──────────────────────────────────────┐
│ 3. (CI/CD) Atualiza Azure DevOps    │
│    → azure/main.py                   │
└──────────────────────────────────────┘

Decisões Técnicas

Por que Robot Framework?

✅ Sintaxe legível - Testes podem ser lidos por não-programadores ✅ Keyword-driven - Reutilização máxima de código ✅ Ecossistema rico - Bibliotecas para tudo (Selenium, API, DB) ✅ Relatórios nativos - HTML reports prontos para uso ✅ Paralelização - Pabot para execução paralela

Por que Selenium?

✅ Padrão de mercado - Suporte e comunidade enormes ✅ Multi-browser - Chrome, Firefox, Edge, Safari ✅ Maturidade - Estável e confiável ✅ Integração - Funciona perfeitamente com Robot Framework

Por que Python?

✅ Bibliotecas customizadas - Lógica complexa em Python ✅ Integração Azure - SDK oficial Python ✅ Produtividade - Sintaxe clara e concisa ✅ Ecossistema - Pacotes para qualquer necessidade

Bibliotecas Customizadas

1. custom_selenium.py

Estende SeleniumLibrary com funções específicas:

class CustomSelenium(SeleniumLibrary):
    def click_when_ready(self, locator, timeout=10):
        """Clica em elemento apenas quando estiver pronto"""
        self.wait_until_element_is_visible(locator, timeout)
        self.wait_until_element_is_enabled(locator, timeout)
        self.click_element(locator)

Uso:

Click When Ready    ${BTN_SALVAR}    timeout=15s

2. fake_generator_doc.py

Gera dados fake válidos para testes:

def gerar_cpf_valido():
    """Gera CPF válido com dígitos verificadores corretos"""
    # Implementação...
    return cpf

Uso:

${cpf}    Gerar CPF Valido
Preencher Campo CPF    ${cpf}

3. lock_wrapper.py

Previne condições de corrida em testes paralelos:

@with_lock('usuario_admin')
def criar_usuario_admin():
    """Apenas um teste por vez pode criar admin"""
    # Implementação...

Integração Azure DevOps

Fluxo de CI/CD

┌─────────────────────────────────────────────┐
│ 1. Push/PR no GitHub                        │
└─────────────────────────────────────────────┘
                ↓
┌─────────────────────────────────────────────┐
│ 2. Azure Pipeline Triggered                 │
│    (azure-pipelines.yml)                    │
└─────────────────────────────────────────────┘
                ↓
┌─────────────────────────────────────────────┐
│ 3. Setup Ambiente                           │
│    - Install Python                         │
│    - Install Dependencies                   │
│    - Setup Chrome/ChromeDriver              │
└─────────────────────────────────────────────┘
                ↓
┌─────────────────────────────────────────────┐
│ 4. Executa Testes                           │
│    robot -d results tests/                  │
└─────────────────────────────────────────────┘
                ↓
┌─────────────────────────────────────────────┐
│ 5. Processa Resultados                      │
│    python azure/main.py                     │
│    - Parse output.xml                       │
│    - Captura screenshots                    │
└─────────────────────────────────────────────┘
                ↓
┌─────────────────────────────────────────────┐
│ 6. Atualiza Work Items                      │
│    - Test Case [ID] → Status                │
│    - Anexa screenshots                      │
│    - Adiciona comentários                   │
└─────────────────────────────────────────────┘
                ↓
┌─────────────────────────────────────────────┐
│ 7. Publica Artefatos                        │
│    - report.html                            │
│    - log.html                               │
│    - screenshots/                           │
└─────────────────────────────────────────────┘

Sincronização de Resultados

# azure/main.py
def processar_resultados():
    # 1. Parse XML
    resultados = parser.parse_output_xml('results/output.xml')
    
    # 2. Para cada Test Case
    for teste in resultados:
        test_case_id = extrair_id_da_tag(teste.tags)
        
        # 3. Atualiza Work Item
        azure_client.atualizar_test_case(
            id=test_case_id,
            status=teste.status,
            comentario=teste.message,
            screenshots=teste.screenshots
        )

Padrões de Qualidade

1. Formatação Automática

# scripts/format.ps1
robotidy --overwrite tests/
robotidy --overwrite resources/

2. Linting

# scripts/lint.ps1
robocop --reports all tests/
robocop --reports all resources/

3. Quality Check Completo

# scripts/quality-check.ps1
# 1. Formata código
# 2. Executa linting
# 3. Roda testes
# 4. Valida cobertura

Escalabilidade

Execução Paralela

# Executa com 8 processos simultâneos
pabot --processes 8 --outputdir results tests/

# Por pasta
pabot --testlevelsplit --outputdir results tests/

Performance:

• 🐌 Serial: ~30 minutos
• 🚀 Paralelo (8 cores): ~5 minutos

Boas Práticas para Paralelização

✅ Testes independentes - Não compartilham estado ✅ Dados isolados - Cada teste cria seus próprios dados ✅ Locks quando necessário - Use lock_wrapper.py ❌ Evite globals - Podem causar race conditions

Próximos Passos

• 📚 Keywords Reference - Documentação de todas as keywords
• 🔧 Development Guide - Como criar novos testes
• 🐛 Troubleshooting - Resolver problemas comuns

Última atualização: Outubro 2025