Esse artigo fornece um resumo detalhado de como executar a suíte gaia-ui-tests incluída no próprio Gaia, B2G Desktop e dispositivos reais com Firefox OS. O projeto Gaia usa Travis CI para realizar a integração contínua e testes de pull requests.
Nota: Você pode encontrar uma lista de mais de 32000 compilações (e crescendo) executada via Travis. Ao lado de testes unitários e testes do marionette js, Gaia também executa testes de scripts de compilação via Travis. Os detalhes da execução dos scripts são definidos em tests/travis_ci. Se você encontrar um erro no gaia_ui_tests pelo Travis e quiser reproduzí-lo localmente verifique tests/travis_ci/gaia_ui_tests/.
O testes do Gaia gaia-ui-tests foi desenvolvido com a capacidade de ser executado em dispositivos reais, emuladores e no cliente B2G Desktop. A propósito o método mais fácil de executar o teste é no B2G Desktop. Observe que você deve escolher o branch correto do Gaia para executar a versão do Firefox OS que estiver usando.
Testando no B2G Desktop
O cliente B2G desktop é exatamente o que diz: uma versão desktop do B2G que você pode usar para executar testes das aplicações web do Firefox OS no conforto do seu desktop. Se você não é familiar com ele, descubra mais sobre ele no artigo Usando o cliente B2G desktop. Essa seção irá mostrar como executar os testes gaia-ui-tests no B2G desktop.
Pré-requisitos
- Uma imsagem do B2G desktop. Você pode baixá-la e descompactá-la em um diretório do seu computador ou uma máquina virtual ou compilar uma você mesmo, adicionando
ENABLE_MARIONETTE=1
no seu. - Um repositório Gaia clonado do Github.
- Um arquivo testvars.json criado (como explicado na importante seção abaixo).
O cliente desktop B2G é ideal para testes de desenvolvimento quando um dispositivo real não está disponível e não há a necessidade de testes das funções do próprio telefone. É rápido e acessível, podendo ser executado no Linux, Mac ou Windows!
Executando os testes
Nós vamos instalar a versão que vem na própria árvore do repositório Gaia. Dessa forma nossas alterações serão usadas imediatamente. Na sua versão clonada do Gaia, navege o diretório gaia/tests/python/gaia-ui-tests
e execute o seguinte comando de configuração:
python setup.py develop
Via Marionette, o gaiatest pode chamar o B2G Desktop quando iniciarmos o teste. Para fazer isso, você precisa passar o caminho do arquivo binário B2G bem como do perfil. No exemplo abaixo, nós incluímos a variável $HOME
como o caminho tanto para o binário quanto para o perfil. Simplesmente é o local no qual você descompactou o B2G Desktop depois de ter baixado. O comando para executar todos os testes é:
gaiatest --binary=$HOME/b2g/b2g-bin --profile=$HOME/b2g/gaia/profile --testvars=testvars.json --restart --type=b2g ./gaiatest/tests/functional/manifest.ini
Testes que forem incompaíveis com o B2G Desktop — por exemplo, aqueles que fazem chamadas ou enviam SMS — são automaticamente ignorados pelo script de teste.
Você pode executar um teste diretamente chamando o arquivo na linha de comando:
gaiatest --binary=$HOME/b2g/b2g-bin --profile=$HOME/b2g/gaia/profile --testvars=testvars.json --restart ./gaiatest/tests/functional/clock/test_clock_set_alarm.py
Testando em um dispositivo Firefox OS
O teste em dispositivos reais Firefox OS é mais complicado, mas de longe fornece resultados mais precisos, pois acessa todos as características reais do dispositivo.
Pré-requisitos
- Android Debug Bridge instalado e o arquivo de udev rules configurado.
- Um dispositivo Firefox OS com uma compilação com o Marionette habilitado
- O branch do repositório Gaia no Github referente ao seu dispositivo Firefox OS clonado e atualizado.
- Um arquivo testvars.json file criado.
Executando os testes
O pacote gaiatest é necessário para a execução dos testes. Nós precisamos instalá-lo para o branch o qual queremos executar o testes. Navegue no diretório gaia/tests/python/gaia-ui-tests/
e instale o gatatest com o seguinte comando:
python setup.py develop
Nota: Antes de começar a executar o teste, leia este aviso a fim de certificar-se de que a execução dos testes gaia-ui-tests em um dispositivo pode apagar os dados do mesmo.
O Marionette que está rodando no dispositivo, aguarda comandos na porta 2828. Devido a isso, precisamos direcionar nossa porta local para a porta remota no dispositivo usando o adb. Execute o seguinte comando:
adb forward tcp:2828 tcp:2828
Você pode usar o seguinte comando para executar todos os testes gaia-ui-tests:
gaiatest --address=localhost:2828 --testvars=<TESTVARS_FILE> --restart --type=b2g gaiatest/tests/functional/manifest.ini
Ou use o comando a seguir se você quiser executar um teste simples (substituindo a última parte pelo teste real que você quer fazer):
gaiatest --address=localhost:2828 --testvars=<TESTVARS_FILE> --restart gaiatest/tests/functional/clock/test_clock_create_new_alarm.py
Após o teste, você verá todos os resultados e registro de rastreamento para cada arquivo.
Nota: Você pode receber um erro ao executar esses testes — ImportError: No module named bluetooth
. Se isso acontecer, substitutua a seguinte parte do comando --type=b2g
por --type=b2g-bluetooth
para excluir os testes de bluetooth. Alternativamente você pode instalar o pacote PyBluez python que possibilita executar o teste do dispositivo via bluetooth.
Executando os testes usando Travis para desenvolvedores Gecko and Gaia developers
Travis é uma plataforma de integração contínua utilizada para executar os testes gaia-ui-tests (e outras coisas). Nessa seção nós vamos explorar como você você se benefica se pretende executar um grande número de testes.
Executando os testes usando nossa configuração do Travis é bastante simples — o script de instlação baixará o Gecko e preparará um perfil Gaia para você. O script de instalação usa o mozilla-download que por sua vez usa nodejs e npm para baixar a última versão do Gecko.
Pré-requisitos
- O repositório Gaia no Github (para preparar o perfil Gaia e instalar o gaiatest e arquivos de teste).
- Um arquvo testvars.json criado (como explicado na importante seção abaixo).
- nodejs e npm instalados (são usado para baixar o Gecko.)
Instalando o Gecko e compilando o Gaia usando nosso script do Travis
Nota: Se você já tem um diretório b2g/ no Gaia então o script de instlação do Travis ignorará essa etapa. Se você precisa da última versão do Gecko, apague o diretório b2g/ antes de executar o script.
O script Travis deve ser executado a partir do diretório raiz do gaia/
. Execute o seguinte comando:
tests/travis_ci/gaia_ui_tests/install
O script criará um ambiente virutal do Python (package sandbox) bem como os pacotes necessários para executar o gaia-ui-tests, incluindo uma nova versão do B2G desktip e uma compilação desktop do Gaia. O ambiente virtual será instalado no diretóri travis_venv
.
Executando os testes
A execução dos testes fica a cargo do arquivo script
, que envolve a linha de comando padão:
tests/travis_ci/gaia_ui_tests/script
Esse comando executa:
$ export GAIATEST_ACKNOWLEDGED_RISKS=true
$ export GAIATEST_SKIP_WARNING=true
$ root=tests/python/gaia-ui-tests/gaiatest
$ b2g=`find b2g -follow -name "b2g-bin" | tail -n 1`
$ python $root/cli.py --app=b2gdesktop \
--binary=$b2g \
--profile=profile \
--type=b2g \
--timeout=10000 \
tests/python/gaia-ui-tests/gaiatest/tests/accessibility/lockscreen/test_a11y_un\
lock_to_homescreen.py
O arquivo script
pode ser editado para direcionar para arquivos ou diretórios de testes específicos e adicionar parâmetros de linha de comando — especifcamente a linha que executa cli.py.
Importante: Quando usar o B2G Desktop ou um Emulator, tente manter o cursor do mouse longe da janela do B2G para que eventos de ponteiro não atrapalhem a execução dos testes.
Nota: Você pode executar o comando deactivate
para voltar para o console normal quando o teste finalizar.
Encontrando o relatório HTML em um trabalho finalizado do Travis
A final dos testes do Travis é produzido um relatório HTML e feito um upload para um espaço público da web.
- Abra o trabalho gaia-ui-tests job para um pull request ou commit
- Role a tela para baixo até a seção "after_script" e expanda o texto
- Próximo do final do "after_script", a saída do console mostra a localização do relatório na Amazon AWS
Quando os testes são executados localmente você pode encontrar o relatório em gaia/artifacts/gaia_ui_tests_report.html
Nota: Até o momento isso só funciona para commits de merge, mas esperamos usar isso em pull requests no futuro.
Testando localmente com configuração TBPL para desenvolvedores Gecko e Gaia
Nesta seção, vamos nos concentrar em replicar um teste TBPL localmente. Antes disso você precisa estar ciente de que é construído um perfil Gaia separado. O perfil que vem empacotado com a compilação TBPL não é o mesmo perfil que o TBPL utiliza.
Pré-requisitos
- Uma compilação B2G desktop. Você pode baixá-la and descompactá-la em um diretório do seu computador ou em uma máquina virtual ou compilar uma você mesmo, incluindo
ENABLE_MARIONETTE=1
no seu mozconfig. - O reposiório Gaia do Github (para prepara o perfil Gaia e instalar o gaiatest e os arquivos de testes).
- Um arquivo testvars.json criado.
Compilando um perfil Gaia com as configurações TBPL's
Antes de compilar um perfil nós necessitamos verificar as variáveis de ambiente usadas para compilar o perfil. Procurando no "brief log" do teste Gu, encontre esse bloco de comando:
Using env: {'DEBUG': '0',
'DESKTOP': '0',
'DESKTOP_SHIMS': '1',
'NOFTU': '0'}
Essas configurações podem alterar drasticamente o comportamento do B2G. É muito importante fazer coincidir as configurações do TBPL.
O próximo passo é fazer o checkout do commit do git que coincide com o commit do hg que roda no TBPL. Você também pode encontrar o commit do hg no "brief log" do TBPL, mas você próprio vai precisar correlacionar com commit do git.
O reposiório de teste do gaia inclui um script make
para compilar um perfil Gaia. Navegue no reposiório do Gaia que você clonou localmente e compile o perfil usando as variáveis de ambiente que nós encontramos no TBPL:
DEBUG=0 DESKTOP=0 DESKTOP_SHIMS=1 NOFTU=0 make
Executando os testes
Use o mesmo commit do git que o TBPL usou para executar o teste, vá para o diretório gaia/tests/python/gaia-ui-tests
e instale o gaiatest usando o seguinte comando:
python setup.py develop
Agora que você tem o perfil Gaia, a única diferença significante para executar esses testes é que você deve direcionar o gaiatest para os locais do binário do B2G e do profile. Como o TBPL é executado em um ambiente isolado, ele usa o próprio conjunto de testes, configurado em tbpl-manifest.ini
.
Dentro do diretório gaia-ui-tests
directory, execute o comando a seguir, com as seguintes substituições:
$BINARY_PATH
: O caminho para o arquivob2g-bin
no diretório que você compilou ou descompactou o B2G.$PROFILE_PATH
: O caminho para o seu perfil Gaia compilado localmente. Se compilado a partir do repositório Gaia será~/gaia/profile
.
gaiatest --binary $BINARY_PATH/b2g/b2g-bin --profile $PROFILE_PATH/profile --restart --testvars testvars.json gaiatest/tests/tbpl-manifest.ini --type=b2g
Nota: Não há necessidade de direcionar a porta 2828 a menos que você tenha configurado o servidor do Marionette para usar uma porta padrão diferente.
Importante: Tente manter o cursor do seu mouse longe da janela do b2g uma vez que pode atrapalhar na execução dos testes.
Encontrando um relatório HTML do trabllho realizado pelo TBPL
Todos os trabalhos TBPL (os que passaram e os que falharam) possuí um relatório gerado e armazenado.
- Para o commit, clique Gu.
- Na barra de status, abaixo do TBPL procure a seção entitulada TinderboxPrint: Uploaded output.html.
- Copie o link para um navegador e veja o relatório.
Teste em um binário que já esteja sendo executado
Nessa seção nós vamos verificar como realizar testes em um Desktop B2G em execução com código fonte modificado.
Pré-requisitos
- Uma compilação B2G desktop com suas alterações no Gecko. Você pode baixá-la and descompactá-la em um diretório do seu computador ou em uma máquina virtual ou compilar uma você mesmo, incluindo
ENABLE_MARIONETTE=1
no seu mozconfig. - Um depurador a sua escolha conectado ao binário B2G
- O reposiório Gaia do Github (para prepara o perfil Gaia e instalar o gaiatest e os arquivos de testes).
- Um arquivo testvars.json criado.
Running the tests
Running tests against an existing b2g process is quite easy — you've already gone through the hard parts to build B2G!
If you have not already installed gaiatest then do so now by going to gaia/tests/python/gaia-ui-tests
and running the following:
python setup.py develop
Once you have started the b2g binary process and attached your debugger you need to direct gaiatest to the port using the --address
command. Do not use --binary
or --profile
, otherwise gaiatest will just send commands directly to the port without attempting to start or close the binary.
gaiatest --testvars testvars.json gaiatest/tests/functional/test_that_is_being_debugged.py
Note: We have omitted the --restart
command too. As gaiatest does not attempt to stop or start the binary some data from your test run may be left behind in Firefox OS databases or even in the DOM. It is your responsibility to reset B2G back to a basic state before trying to run the test for a second time.
Variáveis de teste (testvars.json)
O gaia-ui-tests vai limpar os banco de dados do seu aparelho para fornecer um perfil limpo para as rotinas de teste. Gaiatest tem uma proteção contra a execução e apagamento dos dados do seu dispositivo. Leia esse aviso antes de configurar seu arquivo de variáveis de teste.
Podemos usar a opção --testvars
para passar variáveis locais, particularmente aquelas que não podem ser verificadas no repositório. Por exemplo, no gaia-ui-tests existem variáveis que podem ser suas credenciais privadas, número de telefone ou detalhes da sua conexção WiFi.
Para usar isso, copie testvars_template.json
para um outro arquivo e não esqueça de adicioná-lo ao arquivo .gitignore
para que não seja enviado ao seu repositório remoto.
E quando for executar seus testes adicione o argumento: --testvars=(filename).json
Como configurar o WiFi usando o arquivo testvars.json (para dispositivos)
Para que as rotinas de teste consigam utilizar a sua conexão WiFi é necessário registar no arquivo testvars.json
.
Sem autenticação WiFi:
"wifi": { "ssid": "MyNetwork"}
autenticação WEP:
"wifi": { "ssid": "MyNetwork", "keyManagement": "WEP", "wep": "MyPassword" }
autenticação WPA-PSK:
"wifi": { "ssid": "MyNetwork", "keyManagement": "WPA-PSK", "psk": "MyPassword" }
Devido ao Bug 775499, conexões WiFi via WPA-EAP não são possíveis nesse momento.
Resolução de problemas
Essa seção detalha algumas mensagens comuns de erro e algumas dicas de como resolver os problemas.
Problemas comuns antes do início do teste
Mensagem de erro | Ações correspondentes |
---|---|
error: [Errno 111] Connection refused |
Execute novamente o comando "adb forward tcp:2828 tcp:2828" |
Element ... not visible before timeout |
Certifique-se de que o elemento deveria ser exibido no aplicativo que você está testando. |
TimeoutException: Condition timed out | Certifique-se de que a condição no aplicativo é a mesma que você espera. |
marionette.errors.MarionetteException: localhost:2828 is unavailable. | Algo está bloqueando a porta, normalmente o comando `adb forward`. `adb kill-server` pode resolver. Ou o aplicativo pode ter sido fechado mantendo a porta aberta. |
ImportError: No module named bluetooth |
Substitua no comando |
OSError: [Errno 2] No such file or directory: '~/moz/gaia/profile' | Não utilize ~ na linha de comando significando $HOME. Escreva o caminho completo |