Framework de automação de testes end-to-end para aplicativos Android, construído com Appium, WebdriverIO e TypeScript, seguindo os padrões BDD (Behavior Driven Development, com Cucumber) e Page Object Model.
Este é um projeto de portfólio, desenvolvido para demonstrar, na prática, conhecimentos de automação de testes mobile: definição de cenários em linguagem de negócio, organização de código sustentável, execução em emulador Android e integração contínua.
Gravação real do cenário de checkout (npm test) rodando contra o emulador Android: login, adição ao carrinho, preenchimento de endereço e pagamento, até a confirmação do pedido.
- Sobre o projeto
- Tecnologias e ferramentas
- Estrutura do projeto
- Aplicativo sob teste
- Pré-requisitos
- Configuração do ambiente
- Instalação
- Executando os testes
- Relatório de testes (Allure)
- Solução de problemas
- Padrões de qualidade de código
- Integração contínua
- Cenários de teste implementados
- Bugs encontrados
- Reportando problemas
- Changelog
- Licença
- Autor
O objetivo deste repositório é simular, da forma mais próxima possível da realidade, um projeto de automação de testes mobile mantido por uma equipe de qualidade (QA). Para isso, os testes são escritos em formato Gherkin (dado/quando/então), organizados por Page Objects reutilizáveis, e executados automaticamente a cada alteração de código através de um pipeline de integração contínua no GitHub Actions.
O aplicativo utilizado como alvo dos testes é o My Demo App, um aplicativo Android de e-commerce fictício mantido pela Sauce Labs especificamente para fins de treinamento e demonstração de automação de testes.
| Categoria | Ferramenta |
|---|---|
| Linguagem | TypeScript |
| Framework de automação | WebdriverIO |
| Driver de automação mobile | Appium (driver UiAutomator2) |
| Estilo de escrita dos testes | BDD com Cucumber (cenários em português) |
| Padrão de organização | Page Object Model |
| Relatório de execução | Allure Report |
| Qualidade de código | ESLint e Prettier |
| Integração contínua | GitHub Actions |
| Plataforma testada | Android (emulador via Android Studio) |
.
├── .github/workflows/ # Pipeline de integração contínua
├── apps/ # Local onde o APK do app sob teste deve ser colocado
├── docs/ # Imagens/GIFs usados neste README
├── test/
│ ├── features/ # Cenários de teste em Gherkin (.feature)
│ ├── pageobjects/ # Page Objects (classe base + telas do app)
│ └── step-definitions/ # Ligação entre os passos Gherkin e os Page Objects
├── wdio.conf.ts # Configuração do WebdriverIO/Appium
├── tsconfig.json # Configuração do TypeScript
├── eslint.config.mjs # Configuração do ESLint
└── .env.example # Modelo de variáveis de ambiente
Os testes rodam contra o My Demo App Android, da Sauce Labs: um aplicativo de e-commerce fictício com login, catálogo de produtos, carrinho de compras e diversas outras funcionalidades de demonstração (QR Code, geolocalização, biometria, entre outras).
- Repositório oficial: saucelabs/my-demo-app-android
- Pacote Android:
com.saucelabs.mydemoapp.android - Credencial de demonstração utilizada nos testes: usuário
bod@example.com, senha10203040
O arquivo .apk não é versionado neste repositório (ver seção Instalação para instruções de download).
Antes de rodar os testes localmente, é necessário ter instalado:
- Node.js 18.20 ou superior
- JDK (Java Development Kit) 17 ou superior
- Android Studio, com:
- Android SDK (Platform-Tools, Build-Tools, Platform e Emulator)
- Um dispositivo virtual (AVD) já criado e funcional
As variáveis de ambiente a seguir também precisam estar configuradas no sistema operacional:
| Variável | Descrição |
|---|---|
JAVA_HOME |
Caminho de instalação do JDK |
ANDROID_HOME (ou ANDROID_SDK_ROOT) |
Caminho de instalação do Android SDK |
O PATH do sistema deve incluir as pastas platform-tools e emulator do Android SDK, para que os comandos adb e emulator funcionem diretamente no terminal.
-
Copie o arquivo de variáveis de ambiente de exemplo:
cp .env.example .env
-
Ajuste, se necessário, os valores em
.env:Variável Padrão Descrição ANDROID_APP_PATH./apps/android-demo-app.apkCaminho do APK do aplicativo sob teste ANDROID_DEVICE_NAMEmedium_phoneNome do dispositivo usado pelo Appium ANDROID_AVD_NAMEmedium_phoneNome do dispositivo virtual (AVD) a ser iniciado O nome do AVD deve corresponder a um dispositivo virtual já criado no seu Android Studio (Device Manager). Caso utilize um nome diferente de
medium_phone, atualize essas variáveis de acordo.
-
Clone o repositório:
git clone git@github.com:ThomasTDS/appium-automation-framework.git cd appium-automation-framework -
Instale as dependências:
npm install
-
Baixe o APK do aplicativo sob teste e coloque-o na pasta
apps/:curl -L -o ./apps/android-demo-app.apk \ https://github.com/saucelabs/my-demo-app-android/releases/download/2.2.0/mda-2.2.0-25.apk
O comando acima aponta para a versão
2.2.0(a mais recente no momento em que este projeto foi escrito). Caso uma versão mais nova já tenha sido publicada, verifique o nome exato do arquivo.apkem releases do my-demo-app-android e ajuste a URL do comando de acordo. -
Inicie o emulador Android configurado no Android Studio (ou deixe o Appium iniciá-lo automaticamente na primeira execução dos testes, através da variável
ANDROID_AVD_NAME).
Com o ambiente configurado, basta rodar:
npm testEsse comando inicia o servidor do Appium automaticamente (via @wdio/appium-service), conecta ao emulador Android e executa todos os cenários definidos em test/features/.
A cada execução, os resultados são registrados na pasta allure-results/. Para visualizá-los como um relatório HTML navegável:
# Gera o relatório HTML a partir dos resultados da última execução
npm run report:generate
# Abre o relatório gerado no navegador
npm run report:openO relatório inclui os passos de cada cenário, tempo de execução e capturas de tela em caso de falha.
O relatório da execução mais recente na branch main também fica publicado automaticamente, sem precisar gerar nada localmente: ver relatório Allure ao vivo.
A janela do emulador abre, mas fica preta/travada, mesmo com os testes passando normalmente.
Isso costuma ser um problema de renderização por GPU do host (comum em notebooks com placa de vídeo híbrida, ex.: NVIDIA + Intel integrada), não um problema no aplicativo ou nos testes — como o Appium interage com o app pela árvore de acessibilidade do Android, e não pelos pixels da tela, a suíte continua funcionando normalmente mesmo com a tela preta. Para forçar o emulador a renderizar por software (mais lento, porém mais compatível) e confirmar o diagnóstico, inicie-o manualmente com:
emulator -avd medium_phone -gpu swiftshader_indirectSe a tela passar a exibir o Android normalmente, o problema é o driver/configuração de GPU do host. Vale tentar atualizar o driver da placa de vídeo dedicada e/ou desativar "Hardware-accelerated GPU scheduling" nas configurações gráficas do Windows antes de recorrer à renderização por software permanentemente.
# Verifica problemas de lint
npm run lint
# Corrige automaticamente o que for possível
npm run lint:fix
# Verifica a formatação do código
npm run format:check
# Formata o código automaticamente
npm run format
# Verifica erros de tipo do TypeScript
npm run typecheckEssas três verificações (lint, formatação e tipos) rodam automaticamente em um job dedicado do CI a cada push ou pull request, de forma independente e em paralelo à execução dos testes end-to-end.
Lint, formatação (só nos arquivos alterados, via lint-staged) e checagem de tipos também rodam localmente antes de cada commit, através de um hook de pre-commit configurado com Husky. O hook é instalado automaticamente ao rodar npm install.
A cada push ou pull request para a branch main, o workflow definido em .github/workflows/ci.yml executa automaticamente toda a suíte de testes em um emulador Android hospedado no GitHub Actions, e publica o relatório Allure como artefato do workflow, disponível para download na aba Actions do repositório. Além disso, a cada push direto na main, o relatório é publicado automaticamente no GitHub Pages: thomastds.github.io/appium-automation-framework.
| Funcionalidade | Cenário | Arquivo |
|---|---|---|
| Login | Login com credenciais válidas | test/features/login.feature |
| Login | Login com usuário bloqueado | test/features/login.feature |
| Login | Login com campos obrigatórios não preenchidos (3 exemplos) | test/features/login.feature |
| Carrinho | Adicionar produto ao carrinho | test/features/carrinho.feature |
| Carrinho | Finalizar compra sem estar logado | test/features/carrinho.feature |
| Carrinho | Remover produto do carrinho | test/features/carrinho.feature |
| Carrinho | Ajustar a quantidade antes de adicionar ao carrinho | test/features/carrinho.feature |
| Carrinho | Adicionar o mesmo produto duas vezes soma a quantidade | test/features/carrinho.feature |
| Checkout | Finalizar compra com sucesso | test/features/checkout.feature |
| QR Code | Abrir o leitor de QR Code | test/features/qrcode.feature |
| Desenho | Desenhar no quadro e salvar | test/features/drawing.feature |
| Geolocalização | Definir localização reflete na tela | test/features/geolocation.feature |
| Biometria | Tela indica indisponibilidade no dispositivo | test/features/fingerprint.feature |
Esta lista é atualizada conforme novos cenários são adicionados ao projeto.
Defeitos reais da aplicação sob teste, descobertos durante o desenvolvimento dos cenários e registrados como Issues do GitHub com passos de reprodução, evidência e análise de causa.
| Issue | Resumo | Severidade |
|---|---|---|
| #22 | Login aceita qualquer usuário/senha, exceto e-mails na lista de bloqueio — a senha não é validada | Critical |
Bugs encontrados na aplicação sob teste, no pipeline de CI ou na própria automação são registrados como Issues do GitHub, usando um template padronizado que cobre ambiente, severidade, prioridade, passos de reprodução e causa raiz.
O histórico de mudanças notáveis deste projeto é mantido em CHANGELOG.md.
Este projeto está licenciado sob os termos da licença MIT. Consulte o arquivo LICENSE para mais detalhes.
Desenvolvido por Thomas Teixeira como projeto de estudo e portfólio em automação de testes mobile.