Introdução ao Maestro

This page is not available in the language you requested. You have been redirected to the English version of the page.
Link to this page copied to clipboard

Identifique rapidamente problemas de acessibilidade em conjunto com os fluxos de teste do Maestro.

Not for use with personal data

Axe DevTools Mobile para Maestro traz verificação de acessibilidade integrada para Maestro, impulsionado pelos SDKs do Axe DevTools para Mobile. Ao executar seus fluxos de teste de interface com ele, você pode facilmente invocar verificações automatizadas de acessibilidade diretamente no seu YAML com dois comandos: axeStartScanSession e axeScan.

Requisitos

  • macOS ou Linux — o instalador requer um shell Unix.
    • macOS: suporta tanto o emulador Android quanto o simulador iOS
    • Linux: suporta apenas o emulador Android (simuladores iOS são exclusivos do macOS)
  • Java 17+ — verifique com java -version
  • curl e unzip — pré-instalados no macOS e na maioria das distribuições Linux
  • Emulador Android ou simulador iOS com o seu aplicativo instalado
  • Chave de API do Axe DevTools Mobile
  • ID do Projeto no Axe Developer Hub

(Nota: Suporte para Windows em breve.)

Instalação

  1. Se você instalou anteriormente o Maestro público via Homebrew, desinstale-o primeiro para evitar conflitos de PATH:

    brew uninstall maestro

  2. Você precisará de um token de identidade do repositório privado da Deque. Se você não tiver um, siga os passos em Introdução ao Repositório Privado da Deque.

    Certifique-se de que DQ_AGORA_IDENTITY_TOKEN esteja configurado no seu ambiente, e então execute o seguinte comando no macOS ou Linux:

    curl -fsSL -H "Authorization: Bearer $DQ_AGORA_IDENTITY_TOKEN" \
"https://agora.dequecloud.com/artifactory/axe-devtools-mobile-maestro/install.sh" | bash

    Para instalar uma versão específica, inclua isto no comando bash:

    curl -fsSL -H "Authorization: Bearer $DQ_AGORA_IDENTITY_TOKEN" \
"https://agora.dequecloud.com/artifactory/axe-devtools-mobile-maestro/install.sh" | MAESTRO_VERSION=1.0.0 bash

  3. Abra um novo terminal e verifique se maestro --version mostra a versão do Axe DevTools.

    maestro --version

Começo Rápido

  1. Crie um arquivo de fluxo.

    Crie um arquivo chamado accessibility-check.yaml e adicione o trecho de código abaixo:

    appId: com.example.myapp
---
- launchApp
- axeStartScanSession:
    apiKey: "YOUR_API_KEY"
    projectId: "YOUR_PROJECT_ID"
- axeScan

    Substitua com.example.myapp pelo nome do pacote do seu aplicativo (Android) ou pelo ID do pacote (iOS), e preencha sua chave de API do Axe DevTools Mobile e o ID do Projeto do Axe Developer Hub.

  2. Execute o fluxo.

    Para iOS:

    maestro test --device <DEVICE_ID> accessibility-check.yaml

    Para Android:

    maestro test --device <DEVICE_ID> accessibility-check.yaml

    Referindo-se ao arquivo de fluxo que você acabou de criar, o Maestro lançará seu aplicativo, iniciará uma sessão de verificação do Axe DevTools e realizará uma verificação de acessibilidade na tela atual. Os resultados são carregados automaticamente no Axe Developer Hub.

    note

    O 'DEVICE_ID' é um identificador único que o Maestro usa para as máquinas em que você executa seus testes. Visite a documentação do Maestro para aprender como encontrar o ID do dispositivo.

Use Variáveis de Ambiente para Credenciais

Não é recomendado codificar chaves de API em arquivos YAML. Use a interpolação de variáveis do Maestro com variáveis de ambiente.

Nota: O Maestro só injeta automaticamente variáveis de ambiente de shell que começam com MAESTRO_. Use o prefixo MAESTRO_ para quaisquer variáveis que você queira disponíveis nos seus fluxos YAML.

Adicione o seguinte ao seu perfil de shell (por exemplo, ~/.zshrc ou ~/.bashrc):

export MAESTRO_AXE_API_KEY="YOUR_API_KEY"
export MAESTRO_AXE_PROJECT_ID="YOUR_PROJECT_ID"

Então referencie estas no seu YAML:

appId: com.example.myapp
---
- launchApp
- axeStartScanSession:
    apiKey: ${MAESTRO_AXE_API_KEY}
    projectId: ${MAESTRO_AXE_PROJECT_ID}
- axeScan

Alternativamente, passe essas variáveis de ambiente inline ao executar:

Para iOS:

MAESTRO_AXE_API_KEY=your-key MAESTRO_AXE_PROJECT_ID=your-project maestro test --device <DEVICE_ID> accessibility-check.yaml

Para Android:

MAESTRO_AXE_API_KEY=your-key MAESTRO_AXE_PROJECT_ID=your-project maestro test --device <DEVICE_ID> accessibility-check.yaml

Referência de Comandos

axeStartScanSession

Inicie uma sessão de verificação do Axe DevTools, fornecendo as credenciais necessárias para axeStartScanSession. Chame isso uma vez, antes do primeiro axeScan no seu fluxo.

- axeStartScanSession:
    apiKey: ${MAESTRO_AXE_API_KEY}
    projectId: ${MAESTRO_AXE_PROJECT_ID}
    axeAccountUrl: "https://..."
Parâmetro Requerido Padrão Descrição
apiKey Sim — Sua chave API do Axe DevTools. Suporta interpolação de variáveis ${}
projectId Sim — Seu ID de projeto do Axe DevTools. Suporta interpolação de variáveis ${}
axeAccountUrl Não null URL personalizada da conta Axe para implantações em nuvem privada ou no local

axeScan

Use axeScan para executar uma verificação de acessibilidade na tela atual. Se axeStartScanSession foi chamado anteriormente no fluxo, os resultados são enviados para o Axe Developer Hub.

# Simple form (all defaults):
- axeScan

Exemplos

Verificar uma única tela

appId: com.example.myapp
---
- launchApp
- axeStartScanSession:
    apiKey: ${MAESTRO_AXE_API_KEY}
    projectId: ${MAESTRO_AXE_PROJECT_ID}
- axeScan

Verificar várias telas em um fluxo

appId: com.example.myapp
---
- launchApp
- axeStartScanSession:
    apiKey: ${MAESTRO_AXE_API_KEY}
    projectId: ${MAESTRO_AXE_PROJECT_ID}

# Scan the home screen
- axeScan

# Navigate and scan the settings screen
- tapOn: "Settings"
- axeScan

# Navigate and scan the profile screen
- tapOn: "Profile"
- axeScan

Verificar com uma URL personalizada da conta Axe

Para implantações do Axe DevTools em nuvem privada ou no local, é necessário um axeAccountURL:

appId: com.example.myapp
---
- launchApp
- axeStartScanSession:
    apiKey: ${MAESTRO_AXE_API_KEY}
    projectId: ${MAESTRO_AXE_PROJECT_ID}
    axeAccountUrl: "https://axe.YOUR_COMPANY.com"
- axeScan

Verificação de acessibilidade não bloqueante

Use optional: true com axeScan para executar a verificação sem falhar o fluxo geral caso ocorra um erro:

appId: com.example.myapp
---
- launchApp
- axeStartScanSession:
    apiKey: ${MAESTRO_AXE_API_KEY}
    projectId: ${MAESTRO_AXE_PROJECT_ID}
    optional: true
- axeScan:
    optional: true

# The flow continues regardless of scan results
- tapOn: "Continue"

Combinar verificações de acessibilidade com testes de interface

appId: com.example.myapp
---
- launchApp
- axeStartScanSession:
    apiKey: ${MAESTRO_AXE_API_KEY}
    projectId: ${MAESTRO_AXE_PROJECT_ID}

# Test login flow and scan each screen
- assertVisible: "Welcome"
- axeScan:
    label: "Login screen"

- tapOn: "Email"
- inputText: "user@example.com"
- tapOn: "Password"
- inputText: "password123"
- tapOn: "Sign In"

- assertVisible: "Dashboard"
- axeScan:
    label: "Dashboard after login"

Visualizando Resultados

Após a conclusão de uma verificação, os resultados estão disponíveis no Axe Developer Hub - um local central onde toda a sua equipe pode visualizar e gerenciar os problemas de acessibilidade encontrados em seu aplicativo. Os problemas no Developer Hub são categorizados por severidade e diretrizes WCAG, para que sua equipe possa priorizar a correção dos mesmos.

Resolução de Problemas

Se você encontrar problemas, tente o seguinte.

  • “Comando não encontrado: maestro”

    Abra um novo terminal após a instalação, ou execute:

    export PATH="$HOME/.maestro/bin:$PATH"

  • Erros de versão do Java

    O Axe DevTools Mobile Maestro requer Java 17 ou superior. Verifique sua versão do Java:

    java -version

    Se a sua versão for inferior a 17, instale um JDK mais recente (por exemplo, via Adoptium).

Is this page helpful?

Help us improve this page

Still need help?