Exibir código-fonte para Testes automatizados funcionais - passo a passo

== '''INTRODUÇÃO''' ==

Este documento descreve uma sequência de passos padrão para a automatização de casos de teste do Pje utilizando o ''framework'' desenvolvido pelo CNJ. O objetivo é que os desenvolvedores consigam desenvolver casos de testes unicamente baseados nesta documentação.

O ''framework'' foi desenvolvido com objetivo de separar a lógica de execução dos casos de teste dos dados necessários para a execução. Para isso, foram criados três componentes básicos para a execução: 
* um arquivo XML com os dados necessários para a execução;
* uma classe de dados que encapsula valores dos elementos do arquivo XML em uma estrutura de fácil manipulação pelo desenvolvedor;
* uma classe (ou mais - [http://www.cnj.jus.br/wikipje/index.php/Framework_de_testes_automatizados#Classe_CenarioFragmentoSelenium ver sobre fragmentos de cenários]) responsável pela execução do caso de teste com base nos dados encapsulados pela classe de dados.

É importante observar que, independentemente da forma de implementação da classe de execução, obrigatoriamente devem ser criados os três artefatos descritos acima, visto que o ''framework'' está “esperando” pela existência dos três para a execução dos cenários.

A documentação completa pode ser obtida no [http://www.cnj.jus.br/wikipje/index.php/Framework_de_testes_automatizados seguinte link].

== '''PASSO A PASSO''' ==

Este capítulo descreve uma sequência de passos sugerida para o desenvolvimento de casos de teste com base no ''framework'' criado. Trata-se apenas de uma sugestão que, com base na experiência de uso do ''framework'', tem se mostrado eficiente para o desenvolvimento dos casos de teste do PJe.

=== Determinação da estrutura de dados ===

O primeiro passo consiste em determinar a estrutura de dados necessária para a execução do caso de teste. Numa visão similar à de um caso de uso, esta estrutura deve prever os dados necessárias para a execução de todos os cenários possíveis, tanto cenário principal, quanto cenários alternativos e de exceção. 

Para isso deve-se executar manualmente o caso de teste que se pretende automatizar, de acordo com o desenho do caso de teste. Esta execução manual deve produzir uma lista de dados necessários para a execução automatizada.

A figura abaixo exibe a tela de cadastro de etnias do PJe, que é usada neste documento como exemplo para criação de um caso de teste.

[[Arquivo:TelaCadastroEtnia.png]]

Para a execução deste caso de teste são necessárias duas informações: a descrição da etnia e a situação. Com estas informações é possível partir para o segundo passo, que é a construção do arquivo XML com os dados para execução.

=== Criação do arquivo xml ===

O passo seguinte consiste em criar o arquivo XML para o armazenamento dos dados de execução. Recomenda-se que este arquivo deve estar presente dentro do pacote das classes de dados e execução do cenário em construção. A Figura seguinte ilustra um arquivo XML para o cadastro de Etnias no Pje.

[[Arquivo:XmlCadastroEtnia.png|600px]]

O arquivo XML possui um nó raiz chamado '''TestCase''', com alguns atributos que são apresentados em [http://www.cnj.jus.br/wikipje/index.php/Framework_de_testes_automatizados#Arquivos_XML_indexadores seção específica]. Importante observar que o nome do nó raiz obrigatoriamente deve ser '''TestCase''', pois este nome é esperado pelo ''framework''. Para evitar problemas com relação à estrutura do arquivo criado, recomenda-se, quando for criado um arquivo XML para um caso de teste, que este seja duplicado a partir de um arquivo já existente, para aproveitar a estrutura já criada e testada.

O arquivo XML em questão descreve uma estrutura de um caso de teste que possui dois cenários do tipo '''CadastroEtnia'''. Importante observar que o nome do arquivo XML é '''CadastroEtnia.xml'''. Este nome deve corresponder semanticamente ao propósito do caso de teste, qual seja, o cadastro de etnias. Importante observar que os nós que descrevem cenários devem ter o mesmo nome do arquivo XML, sem a extensão '''.xml'''. Mais informações sobre a nomeclatura dos aquivos podem ser obtidas [http://www.cnj.jus.br/wikipje/index.php/Framework_de_testes_automatizados#Rela.C3.A7.C3.A3o_entre_os_nomes_das_classes_e_arquivos_XML neste documento].

Os dois cenários são declarados entre as linhas 5 e 13 (cenário 1) e entre as linhas 15 e 23 (cenário 2). O nó que descreve os cenários possui alguns atributos de interesse cuja documentação está disponível pode ser acessada [http://www.cnj.jus.br/wikipje/index.php/Framework_de_testes_automatizados#Arquivos_XML_de_cen.C3.A1rios por aqui].

Algumas observações sobre a relação entre o arquivo XML e a página cuja execução será automatizada:

* as linhas 8 e 9 do arquivo XML descrevem os valores necessários para o preenchimento dos campos da página. Os nomes destes nós são livres, contudo, recomenda-se que correspondam semanticamente aos nomes dos campos no PJe. 
* entre as linhas 10 e 12 são declarados os resultados produzidos pelo cenário, que poderão ser utilizados na execução dos cenários seguintes. Este nó é opcional. Contudo, caso exista, obrigatoriamente deve se chamar '''resultados'''. Dentro deste nó são declarados nós com o nome '''resultado''' (no singular). O valor declarado dentro de um nó resultado (ver exemplo na linha 11) deve corresponder exatamente ao nome de um atributo presente na classe de dados. Este atributo não precisa necessariamente estar presente no XML (apesar de frequentemente estar presente), mas, caso seja declarado em resultado, deve estar presente na classe de dados. Ainda, para ser utilizado pelos cenários subsequentes, os arquivos de dados destes cenários também devem declarar o atributo com o mesmo nome na classe de dados. Mais informações sobre o recurso de resultados de cenários podem ser acessadas [http://www.cnj.jus.br/wikipje/index.php/Framework_de_testes_automatizados#Resultados_de_cen.C3.A1rios aqui].

=== Criação da classe de dados ===

Após criado o arquivo XML deve-se criar a classe de dados para encapsulamento dos atributos declarados. Esta classe deve estar em um pacote definido de acordo com o padrão de estrutura da instituição. Entretanto, definido o pacote, este deve ser declarado no arquivo XML, no cabeçalho do caso de teste, conforme ilustrado na linha 3 do código fonte exibido na figura acima.

O nome do arquivo da classe de dados deve ser exatamente o nome do arquivo XML, precedido da palavra '''Dados'''. Com isso, para o arquivo '''CadastroEtnia.xml''', o arquivo da classe de dados deverá ter o nome '''DadosCadastroEtnia'''. A figura seguinte exibe o código fonte da classe de dados do caso de teste de cadastro de etnia.

[[Arquivo:DadosCadastroEtnia.png|600px]]

Algumas características da classe de dados são importantes para a execução correta do caso de teste:
* os atributos declarados nas linhas 8 e 9 deve ter exatamente os mesmos nomes dos nós declarados nas linhas 8 e 9 do arquivo XML ilustrado pela Figura acima.
* todos os atributos declarados devem possuir os métodos de acesso ('''get''' e '''set'''), pois estes serão utilizados pelo ''framework'' para a alimentação dos valores dos atributos. 
* classes de dados devem sempre herdar de uma das classes de dados presentes no ''framework''. A classe em questão herdou da classe '''DadosCadastro'''. Contudo, outras classes de dados podem herdar de qualquer classe abstrata presente na hierarquia da superclasse '''Dados'''.
* os atributos de valores atômicos declarados no arquivo XML, como é o caso daqueles dois apresentados nas linhas 8 e 9 do arquivo ilustrado pela Figura acima, são alimentados automaticamente pelo ''framework'' na classe de dados, através de reflexão. Ou seja, estes valores não precisam ser alimentados manualmente pelo desenvolvedor. 
* valores que não sejam atômicos (que sejam estruturados em nós e subnós) devem ser carregados programaticamente pelo desenvolvedor, dentro do método '''carregarDados'''. Na classe ilustrada pela figura acima não houve necessidade desta implementação, visto que todos os atributos são atômicos. O método '''carregarDados''' é invocado automaticamente pelo ''framework'' (desde de que a classe herde de alguma classe da hierarquia da superclasse '''Dados''') e receberá como parâmetro, no caso exemplificado, um nó com o nome '''CadastroEtnia''', como aquele descrito entre as linhas 5 e 13 da do arquivo XML acima. Cabe então ao desenvolvedor alimentar manualmente eventuais atributos compostos. Recomenda-se o estudo de alguns casos de teste que tenham atributos compostos como, por exemplo, '''CadastroProcesso'''.

=== Criação da classe de execução ===

O último passo sugerido é a criação da classe que irá efetivamente executar o caso de teste. Classes de execução são o único ponto da arquitetura em que há código Selenium. Esta classe deve ser criada no mesmo pacote em que foi criada a classe de dados, e deve ter o mesmo nome desta, sem o prefixo '''Dados'''. Para o cenário de cadastro de etnias, os arquivos terão os seguintes nomes:

* '''arquivo XML''': CadastroEtnia.xml
* '''classe de dados''': DadosCadastroEtnia
* '''classe de execução''': CadastroEtnia

Se não for respeitado este padrão de nomenclatura o ''framework'' não consegue instanciar dinamicamente as classes, e é lançada uma exceção do tipo '''ClassNofFoundException'''. A figura seguinte exibe o código da classe de execução do cadastro de etnia.

[[Arquivo:CadastroEtnia.java.png|700px]]

Algumas considerações sobre a implementação da classe são importantes. Todas as classes de execução devem herdar de alguma superclasse da hierarquia de '''CenarioPJe'''. Esta herança obrigará a implementação do método '''executarTeste()''', que é invocado internamente pelo ''framework''. Além da classe '''CenarioPJe''' é possível que a herança seja feita a partir de classe '''CenarioPJeDocorator''' e suas subclasses. Esta herança obrigará a implementação dos métodos '''preExecucaoTeste()''' e '''posExecucaoTeste()''', que também são invocadas internamente pelo ''framework''. A ordem de invocação destes três métodos, bem como de outros presentes no ''framework'' é apresentada no diagrama de sequência ilustrado pela figura abaixo.

[[Arquivo:Sequencia execução cenário.png|600px]]

O entendimento desta ordem de execução é importante para que a classe de execução seja programada corretamente. Por exemplo, o método '''executarTeste()''' deve conter apenas código referente a ações de preenchimento de campos. Por sua vez, o método '''preExecucaoTeste()''' deve conter código relativo a ações executadas antes do preenchimento dos campos como, por exemplo, código para aguardar a presença de algum componente da página que permita o início do preenchimento dos campos. Por fim, no método '''posExecucaoTeste()''' devem ser programadas ações a serem realizadas após o preenchimento dos campos como, por exemplo, um clique no botão de gravar o conteúdo da página.

Destaca-se no código apresentado na figura acima a instrução presente na linha 11. Este exemplo mostra como utilizar as informações presentes na classe de dados. Os valores presentes na classe de dados são povoados internamente pelo ''framework'', conforme apresentado [[#Criação da classe de dados|nesta seção]].

=== Demais configurações do arquivo XML ===

Outras configurações estão disponíveis no arquivo XML, cuja documentação pode ser encontrada em seção específica, tais como [http://www.cnj.jus.br/wikipje/index.php/Framework_de_testes_automatizados#Refer.C3.AAncia_a_outros_cen.C3.A1rios referência a outros cenários], [http://www.cnj.jus.br/wikipje/index.php/Framework_de_testes_automatizados#Resultados_de_cen.C3.A1rios resultados de cenários], [http://www.cnj.jus.br/wikipje/index.php/Framework_de_testes_automatizados#Resultados_esperados_e_resultados_encontrados_2 resultados esperados e resultados encontrados] e, por fim, [http://www.cnj.jus.br/wikipje/index.php/Framework_de_testes_automatizados#Cen.C3.A1rios_decorados_2 cenários decorados].

Além dos links acima, a seguir também são apresentados exemplos de uso destas funcionalidades.

==== Referência a outro cenário ====

Em algumas situações, dois ou mais cenários de um caso de teste diferem apenas em relação a poucos atributos de seus dados. Neste caso, é possível declarar os dados de um cenário e utilizar estes dados como referência para os dados de outros cenários. Esta declaração é feita por meio do atributo '''ref''' no nó do cenário, conforme exemplificado pela figura abaixo.

[[Arquivo:CadastroCalendario.png|700px]]

O atributo '''ref''' presente no cenário descrito entre as linhas 24 e 28 indica que todos os dados devem ser copiados do cenário cujo atributo '''id''' é igual a 1. O traço vermelho na figura indica a correspondência entre os cenários. Esta declaração instrui o ''framework'' a preencher o cenário 2 com todos os valores de atributos do cenário 1.  Importante observar que o cenário 2 declara o atributo '''situacao''', com valor ''false''. Desta forma o ''framework'' irá utilizar todos os dados do cenário 1 para a execução do cenário 2, exceto o atributo '''situacao''', que sobrescreverá o valor “herdado” do cenário 1.

==== Cenários decorados ====

Em algumas situações a execução de um determinado cenário é idêntica à execução de outro cenário, com algumas ações a mais. Este comportamento é compatível com o padrão de projeto '''Decorator'''. Este padrão permite adicionar dinamicamente funcionalidades a um objeto. O ''framework'' implementa internamente este padrão quando é declarado o atributo '''decorator''' no cenário do arquivo XML. A figura seguinte apresenta um exemplo do uso do atributo decorator.

[[Arquivo:AlteracaoEtnia.png|700px]]

O comportamento esperado do padrão '''Decorator''' ocorre frequentemente nos cenários de cadastro e de alteração. Uma alteração executa basicamente as mesmas ações de um cadastro, com algumas ações adicionais antes ou depois do que é executado no cadastro. A declaração do atributo '''decorator''' na linha 9 indica que o cenário '''AlteracaoEtnia''' irá decorar o cenário '''CadastroEtnia''', e utilizará os dados do cenário cujo '''id''' é igual a '''2''' (atributo '''refDecorator'''). Em outras palavras, internamente, quando o ''framework'' executar o método '''executarTeste()''' do cenário '''AlteracaoEtnia''', ele executará também o mesmo método do cenário '''CadastroEtnia'''. O atributo '''refDecorator''' pode ter dois comportamentos distintos:

* se estiver presente (como é o caso do exemplo da figura), instruirá o ''framework'' a executar o cenário decorado por meio do cenário decorador, com os dados do cenário decorado. Ou seja, o cenário  '''AlteracaoEtnia''' irá executar internamente o método '''executarTeste()''' do cenário '''CadastroEtnia''' com os dados presentes no arquivo '''CadastroEtnia.xml''' no nó cujo '''id''' é igual a '''2'''.
* se estiver ausente, instruirá o ''framework'' a executar o cenário decorado por meio do cenário decorador, com os dados do cenário decorador. Ou seja, o cenário  '''AlteracaoEtnia''' irá executar internamente o método '''executarTeste()''' do cenário '''CadastroEtnia''', porém, com os dados presentes no arquivo '''AlteracaoEtnia.xml'''.

==== Resultados esperados e resultados encontrados ====

Alguns casos de teste exigem a conferência dos resultados produzidos pela sua execução. Por exemplo, em uma pesquisa de processos, uma lista de processos é esperada após a execução do cenário. Esta lista de processos esperados pode ser declarada no nó '''resultadosEsperados'''. A figura abaixo apresenta um exemplo de uso do atributo.

[[Arquivo:ConsultaEtnia.png|600px]]

O nó '''resultadosEsperados''' sempre terá como filhos outros nós que representam classes implementadas pelo programador. No arquivo em questão, a declaração presente entre as linhas 9 e 15 indica que se espera que o resultado da execução do cenário seja um registro cujos valores serão encapsulados em uma classe chamada '''Etnia'''. Esta classe, por sua vez, terá os atributos '''etnia''', '''registroAtivo''' e '''situacao'''. Esta classe deverá declarar todos os métodos de acesso, alén de um construtor vazio e um construtor com todos os parâmetros. Além disso, todas as classes que estiverem declaradas no nó '''resultadosEsperados''' devem herdar da superclasse '''ResultadosBase'''. Esta superclasse contém uma implementação dos métodos '''equals()''', '''hashCode()''' e '''toString()''' necessários para a execução correta do ''framework''. A figura seguinte apresenta a implementação de uma classe de resultado esperado.

[[Arquivo:ConsultaEtnia.java.png|500px]]

Embora a definição de um construtor com parâmetros não seja obrigatória, ela facilitará a implementação das classes de execução de consultas.

Com esta definição no arquivo XML o ''framework'' montará uma lista com os objetos esperados após a execução do cenário. Este lista será utilizada posteriormente para comparação com os resultados listados na página de execução das consulta, conforme documentação disponível [http://www.cnj.jus.br/wikipje/index.php/Framework_de_testes_automatizados#Classe_GerenciadorResultadoSelenium nesta página].

==== Configurações do arquivo '''test.properties''' ====

Esta seção descreve as configurações disponíveis no arquivo '''test.properties''' para o completo funcionamento do ''framework''. Os parâmetros de execução devem ser configurados em pares de chave e valor.
A figura seguinte apresenta um exemplo de um arquivo com as configurações preenchidas. 

[[Arquivo:Testproperties.png|900px]]

As seguintes chaves estão disponíveis para configuração: 
*'''timeout.padrao''': intervalo de tempo, em segundos, que o '''framework''' aguarda até encontrar um elemento em uma página html. Se dentro deste intervalo de tempo o elemento não for encontrado é lançada uma exceção do tipo '''NoSuchElement'''. Se não for informado um valor para este parâmetro o ''framework'' considerará um ''timeout'' de 2 segundos.
*'''evidencias.sucesso''': o ''framework'' permite a geração de arquivos PDF com as evidências (imagens) das execuções dos testes. Este parâmetro indica se devem ser gerados arquivos PDF com as evidências de execuções bem sucedidas dos casos de teste.
*'''evidencias.erro''': indica se devem ser gerados arquivos PDF com as evidências de execuções mal sucedidas dos casos de teste.
*'''evidencias.classe.gerenciadora''': o ''framework'' exige que seja implementada uma classe gerenciadora das evidências de execução. Este parâmetro indica o nome da classe, que é instanciada automaticamente durante a execução dos testes. Se este parâmetro estiver ausente ou se a classe informada não existir não serão geradas as evidências.
*'''evidencias.nome.projeto''': nome do projeto que é adicionado no cabeçalho do arquivo de evidências. Se o parâmetro estiver ausente é gerado automaticamente o texto "não definido. Verifique o arquivo pom.xml".
*'''evidencias.nome.usuario.teste''': nome do usuário responsável pelos testes automatizados que é adicionado no rodapé do relatório de evidências.  Se o parâmetro estiver ausente é gerado automaticamente o texto "não definido. Verifique o arquivo pom.xml".
*'''evidencias.nome.arquivo.relatorio''': prefixo do nome do arquivo do relatório de evidências. O nome completo do arquivo incluir, além deste prefixo, a data e hora de geração. Se este parâmetro não for definido o nome do arquivo conterá apenas a data e hora de geração.
*'''evidencias.nome.pasta''': indica o diretório em que estão armazenados os arquivos de evidência de execução dos cenários. Pode ser informado um caminho absoluto ou um caminho relativo ao diretório de execução da aplicação que será testada. Se não for informado o ''framework'' considera que os arquivos estão no mesmo diretório de execução da aplicação. 
*'''api.testlink.integrar''': indica se há intergração dos testes automatizados com a ferramenta TestLink. Se o valor deste parâmetro for ''false'' nenhum dos demais parâmetros da integração com o TestLink é considerado. Se não for informado o ''framerwork'' considerará que não há integração. A documentação sobre a configuração da integração pode ser obtiva [http://www.cnj.jus.br/wikipje/index.php/Framework_de_testes_automatizados#Integra.C3.A7.C3.A3o_com_Testlink neste link]
*'''api.testlink.url''': indica a url da biblioteca de integração com o TestLink. Se este parâmetro estiver ausente a integração não ocorrerá.
*'''api.testlink.chave''': a integração com o TestLink é executada a partir de uma chave gerada pela própria ferramenta para o usuário. [http://sembugs.blogspot.com.br/2010/10/integracao-selenium-e-testlink.html Este link] contém maiores informações sobre a geração desta chave. Se este parâmetro estiver ausente a integração não ocorrerá.
*'''api.testlink.nome.projeto''': nome do projeto do TestLink em que serão gravados os dados de execução dos testes. Se este parâmetro estiver ausente a integração não ocorrerá.
*'''api.testlink.reportar.sucesso''': indica se devem ser gravados no TestLink informações de execuções bem sucedidas dos testes. Se este parâmetro estiver ausente o ''framework'' considerará que não devem ser gravados dados de execuções bem sucedidas.
*'''api.testlink.reportar.erro''': indica se devem ser gravados no TestLink informações de execuções com erros. Se este parâmetro estiver ausente o ''framework'' considerará que não devem ser gravados dados de execuções com erros.
*'''api.testlink.anexar.evidencias.sucesso''': este parâmetro somente faz sentido se o parâmetro '''APITestLinkReportarSucesso''' estiver marcado como ''true''. Indica se deve ser gravado no TestLink, juntamente com as informações das execuções bem sucedidas, o arquivo de evidências da execução.
*'''api.testlink.anexar.evidencias.erro''': este parâmetro somente faz sentido se o parâmetro '''APITestLinkReportarErro''' estiver marcado como ''true''. Indica se deve ser gravado no TestLink, juntamente com as informações das execuções mal sucedidas, o arquivo de evidências da execução. 
*'''log.falha''': o ''framework'' gera no console da IDE uma série de ''logs'' com informações sobre a execução. Este parâmetro indica se devem ser gerados no console os ''logs'' das falhas ocorridas na execução.
*'''log.erro''': indica se devem ser gerados no console os ''logs'' dos erros ocorridas na execução.
*'''log.warning''': indica se devem ser gerados no console os ''logs'' dos alertas ocorridas na execução.
*'''log.info''': indica se devem ser gerados no console os ''logs'' das informações ocorridas na execução.
*'''log.sucesso''': indica se devem ser gerados no console os ''logs'' informando sucesso das execuções.
*'''consultas.xpath.padrao''': xPath padrão da tabela de retorno dos resultados das páginas de consultas. Este atributo é equivalente ao '''xPathPadrao''' apresentado [http://www.cnj.jus.br/wikipje/index.php/Framework_de_testes_automatizados#Template_de_resultados nesta seção]. O ''framework'' procura primeiro pelo valor definido em '''xPathPadrao''' no arquivo xml do cenário. Se for encontrado este será o valor utilizado para encontrar a tabela com os resultados. Caso o parâmetro esteja ausente é considerado o valor presente o parâmetro '''xPathPadraoConsultas'''. Lembrando que este parâmetro é válido para todas as tabelas de resultados de consultas, enquanto aquele é válido apenas para o cenário de consulta em que foi definido.
*'''consultas.deslocamento.padrao''': tem a mesma funcão do atributo deslocamentoColuna definido [http://www.cnj.jus.br/wikipje/index.php/Framework_de_testes_automatizados#Template_de_resultados nesta seção]. O ''framework'' procura primeiro pelo valor definido em '''deslocamentoColuna''' no arquivo xml do cenário. Se for encontrado este será o valor utilizado para encontrar o valor na coluna da tabela. Caso o parâmetro esteja ausente é considerado o valor presente o parâmetro '''deslocamentoPadraoConsultas'''. Lembrando que este parâmetro é válido para todas as colunas de todas as tabelas de resultados de consultas, enquanto aquele é válido apenas para as colunas do cenário de consulta em que foram definidos.
*'''url.acesso.default''': url que é usada como padrão para execução dos casos de teste. O ''framework'' procura primeiro por uma url definida no cenário de teste, conforme apresentado [http://www.cnj.jus.br/wikipje/index.php/Framework_de_testes_automatizados#Arquivos_XML_de_cen.C3.A1rios nesta seção]. Caso não exista é procurada por uma url definida no arquivo indexador de cenários, conforme exemplificado [http://www.cnj.jus.br/wikipje/index.php/Framework_de_testes_automatizados#Arquivos_XML_indexadores nesta seção]. Se também não for encontrada a url o ''framework'' procura pela definição '''urlAcessoDefault''' no arquivo '''test.properties'''. Se nenhuma das três definições de url for encontrada o cenário de teste não é executado.
*'''acoes.fase.quantidade''': indica a quantidade de fases de execução existente em cada cenário. Caso sejam criadas novas fases ou suprimidas fases existentes, o valor deste atributo deve ser atualizado para corresponder à realidade.
*'''acoes.fase.padrao''': indica a fase padrão para execução das ações automáticas, caso não haja definição de fase na configuração da ação do arquivo xml do cenário.
*'''acoes.carregador''': indica a classe responsável por carregar as ações a partir de um arquivo xml. Na ausência deste parâmetro é utilizada a classe padrão fornecida pelo núcleo Selenium.
*'''acoes.customizadas.arquivo.configuracao''': indica a localização do arquivo descritor de ações customizadas.

=== Fases de execução do cenário ===
Conforme descrito [http://www.cnj.jus.br/wikipje/index.php/Testes_automatizados_funcionais_-_passo_a_passo#Cria.C3.A7.C3.A3o_da_classe_de_execu.C3.A7.C3.A3o nesta seção], o desenvolvedor cria código para execução apenas nos métodos '''executarTeste()''', '''preExecucaoTeste()''', '''posExecucaoTeste()''' da classe de execução. Apesar de o desenvolvedor de cenários ter contato apenas com estes três métodos, várias outras ações são executadas automaticamente pelo framework a partir das configuração dos arquivos xml de cenários e de casos de teste. Estes três métodos são executados nas fases 2, 4 e 5, respectivamente. Entretanto, há 10 fases no processo de execução de um cenário, cujos comportamentos são apresentados a seguir:

'''Fase 1''': ocorre na execução do método '''preTeste()''', descrito [http://www.cnj.jus.br/wikipje/index.php/Framework_de_testes_automatizados#Classe_CenarioSelenium nesta seção].

'''Fase 2''': ocorre na execução do método '''preExecucaoTeste()'''. Este é um método implementado pelo desenvolvedor do cenário de teste.

'''Fase 3''': ocorre na execução do método '''executarCenarioDecorator()''', descrito [http://www.cnj.jus.br/wikipje/index.php/Framework_de_testes_automatizados#Classe_CenarioSelenium nesta seção].

'''Fase 4''': ocorre na execução do método '''executarTeste()''', descrito [http://www.cnj.jus.br/wikipje/index.php/Framework_de_testes_automatizados#Classe_CenarioSelenium nesta seção]. Esta é a fase que, por padrão, as ações automáticas são executadas caso não seja informada uma fase diferente no arquivo xml do cenário. Este valor padrão é definido no arquivo [http://www.cnj.jus.br/wikipje/index.php/Testes_automatizados_funcionais_-_passo_a_passo#Configura.C3.A7.C3.B5es_do_arquivo_test.properties '''test.properties'''].

'''Fase 5''': ocorre na execução do método '''preExecucaoTeste()'''. Este é um método implementado pelo desenvolvedor do cenário de teste.

'''Fase 6''': ocorre na execução do método '''conferirResultados()''', descrito [http://www.cnj.jus.br/wikipje/index.php/Framework_de_testes_automatizados#Classe_CenarioSelenium nesta seção].

'''Fase 7''': ocorre na execução do método '''exibirMensagemPosExecucao()''', descrito [http://www.cnj.jus.br/wikipje/index.php/Framework_de_testes_automatizados#Classe_CenarioSelenium nesta seção].

'''Fase 8''': ocorre na execução do método '''carregarObjetoResultadosCenario()''', descrito [http://www.cnj.jus.br/wikipje/index.php/Framework_de_testes_automatizados#Classe_CenarioSelenium nesta seção].

'''Fase 9''': ocorre na execução do método '''posTeste()''', descrito [http://www.cnj.jus.br/wikipje/index.php/Framework_de_testes_automatizados#Classe_CenarioSelenium nesta seção].

'''Fase 10''': ocorre imediatamente após a execução do método '''posTeste()''', e encerra a execução do cenário. É uma fase teórica, em que nenhuma ação é executada, mas que permite que seja definida como fase para a execução de ações automáticas antes do encerramento do cenário.

== '''AÇÕES AUTOMÁTICAS''' ==
O ''framework'' disponibiliza algumas ações automáticas que podem ser declaradas pelo desenvolvedor de cenários. Por exemplo, o preenchimento de uma caixa de texto pode ser configurada como uma ação automática, assim como o click de um botão. A vantagem de declarar ações automáticas é que libera o desenvolvedor de programar código selenium para a execução destas ações. Atualmente são disponibilizadas as seguintes ações automáticas:
* preenchimento de campos
* clique em elementos (botões, opções de combobox)
* aguardar determinado período de tempo
* aguardar determinado elemento html

O comportamento das ações são apresentados nas seções seguintes.

=== Preenchimento de campos (fill) ===
O preenchimento de campos necessita das seguintes informações configuradas no arquivo XML:
* tipo da ação.
* tipo do elemento html que será preenchido.
* id do elemento html ou texto do label descritido do elemento que será preenchido.
* valor (conteúdo) que a ser preenchido no elemento

Tipicamente o preenchimento é executado em elementos ''input'' do tipo ''text'', mas também pode ser realizado em elementos ''textarea'', por exemplo. O código em xml abaixo apresenta uma exemplo de declaração de ação de preenchimento de campo.

[[Arquivo:AcaoPreencher.png]]

O exemplo acima apresenta duas ações automáticas declaradas para preenchimento de campos de usuário e senha. Importante notar que os atributos '''tipo''', '''element''' e '''valor''' são obrigatórios para que seja possível encontrar o elemento que se deseja preencher. O tipo de ação relativo a preenchimento de campos é o '''fill'''.

O atributo '''valor''' da ação '''fill''' é um campo de texto livre que é preenchido no elemento html. Entretanto, se o conteúdo do campo '''valor''' corresponder a um atributo declarado como [http://www.cnj.jus.br/wikipje/index.php/Framework_de_testes_automatizados#Resultados_de_cen.C3.A1rios resultado] de um cenário anterior, então o valor deste atributo será preenchido no elemento html. A figura seguinte ilustra um exemplo com este comportamento.

[[Arquivo:AcaoResultados.png]]

Nota-se que no cenário 18 os atributos '''usuario''' e '''senha''' são declarados como resultados da execução do cenário. Isso significa que, após a execução do cenário 18, ele proverá para os cenários seguintes uma lista de resultados com o conteúdo destes atributos: '''70824223187''' e '''admin123''', respectivamente. Observa-se, ainda, que o cenário 19 tem duas ações do tipo '''fill''', cujos valores são também '''usuario''' e '''senha'''. Com estas declarações, quando o cenário 19 for executado, as ações fill farão com que os campos sejam preenchidos os os valores '''70824223187''' e '''admin123''', provenientes dos resultados do cenário 18.

=== Clique em elementos (click) ===
A ação de clique é geralmente executada sobre botões e links. O exemplo abaixo apresenta a declaração de um clique sobre um botão.

[[Arquivo:AcaoClicar.png]]

A ação de clicar exige que sejam informados os atributos '''tipo''', '''element''' e '''htmlid'''. Alternativamente, em vez de informar o atributo '''htmlid''' (que define o id do elemento html) pode ser informado um texto (atributo '''htmltext''') a partir do qual é encontrado o elemento a ser clicado. Também pode ser informado o '''value''' do elemento html (atributo '''htmlvalue'''). Ou seja, um dos três atributos ('''htmlid''', '''htmltext''' ou '''htmlvalue''') devem obrigatoriamente ser informados para que seja possível encontrar o elemento a ser clicado.

=== Aguardar (wait) ===
A ação de aguardar permite que seja definida uma pausa antes que a próxima ação seja executada. O exemplo abaixo apresenta a declaração de uma pausa de de 1 segundo antes de proseguir com a execução de outras ações.

[[Arquivo:AcaoWait.png]]

A ação de pausa exige que sejam informados apenas os atributos '''tipo''' e '''valor''', este último correspondendo ao tempo que se deve aguardar antes de proseguir com a execução das demais ações declaradas.

=== Aguardar por algum elemento (waitFor) ===
Em muitos casos, antes de se proseguir com a execução de outras ações deve-se aguardar por algum elemento html na página. Na verdade, aguarda-se que ocorra alguma coisa com algum elemento na página. Os seguintes tipos de ocorrências podem ser aguardados:
* aguardar que determinado element esteja presente na página
* aguardar que determinado elemento deixe de estar presente na página
* aguardar que determinado elemento seja clicável
* aguardar que determinado elemento esteja visível na página
* aguardar que determinado elemento deixe de estar visível na página

O exemplo abaixo ilustra a configuração de uma ação de aguardar a presença de um elemento na página.

[[Arquivo:AcaoWaitFor.png]]

A ação de aguardar um elemento exige que sejam informados apenas os atributos '''tipo''', '''subtipo''', '''element''' e '''htmlid'''. Alternativamente, em vez de informar o atributo htmlid (que define o id do elemento html) pode ser informado um texto (atributo htmltext) do elemento que se deseja aguardar. Também pode ser informado o value do elemento html (atributo htmlvalue). Ou seja, um dos três atributos (htmlid, htmltext ou htmlvalue) devem obrigatoriamente ser informados para que seja possível encontrar o elemento a ser aguardado. 

A partir do atributo subtipo é que se define o que se deseja aguardar do elemento em questão. Os valores e comportamentos representados pelo atributo são os seguintes:

* '''presenca''': aguarda a presença (independentemente de estar visível ou não) de um determinado elemento na página.
* '''ausencia''': aguarda que um determinado elemento deixe de estar presente na página.
* '''visivel''': aguarda que um determinado elemento esteja visível na página.
* '''nao-visivel''': aguarda que um determinado elemento deixe de estar visível na página.
* '''clicavel''': aguarda que um determinado elemento seja clicável na página.

=== Outras configurações das ações ===
Dependendo do tipo de ação (atributo '''tipo''' da declaração xml) alguns atributos são obrigatórios e outros opcionais. Além dos atributos já apresentados, há outros atributos opcionais a serem conhecidos. São todos atributos opcionais que, quando configurados, alteram o comportamento das ações automáticas. A figura seguinte apresenta uma ação configurada com todos os atributos opcionais disponíveis.

[[Arquivo:AtributosOpcionais.png]]

==== Identificador das ações ====
Definido por meio do atributo id, identifica unicamente a ação dentro do cenário. Este identificador pode ser usado para recuperar a ação em tempo de programação, através da chamada do método do gerenciador de ações (que é acessado por meio da classe de dados). Isso permite a execução da ação também de forma manual. A figura seguinte ilustra um trecho de código que contém uma chamada de ação por meio de seu identificador.

[[Arquivo:ChamadaGetAcao.png]]

==== Execução manual de ações ====

Por padrão as ações configuradas no cenário são executadas automaticamente. Contudo, caso se deseje configurar a ação apenas para execução manual, pode-se utilizar o atributo '''auto''', setando seu valor como '''''false''''', para indicar que o framework não deve executar esta ação automaticamente. A figura exibida [http://www.cnj.jus.br/wikipje/index.php/Testes_automatizados_funcionais_-_passo_a_passo#Identificador_das_a.C3.A7.C3.B5es nesta seção] também apresenta um exemplo de uso do atributo '''auto'''. Importante observar na figura acima que para execução manual da ação deve ser invocado o método '''executarManualmente()''', pois o método '''executar()''' somente executará a ação se o atributo '''auto''' estiver definido como ''''''true''''''.

==== Fases de execução ====

Por padrão as ações são sempre executadas na '''fase 4''' (ver sobre as fases de execução [http://www.cnj.jus.br/wikipje/index.php/Framework_de_testes_automatizados#Classe_CenarioSelenium nesta seção] e [http://www.cnj.jus.br/wikipje/index.php/Testes_automatizados_funcionais_-_passo_a_passo#Fases_de_execu.C3.A7.C3.A3o_do_cen.C3.A1rio nesta seção]), ou em outra fase descrita no arquivo '''test.properties'''. Contudo, algumas ações eventualmente precisam ser realizadas em outras fases da execução do cenário. Para indicar em qual fase a ação deve ser executadas pode-se utilizar o atributo fase, também ilustrado na imagem descrita [http://www.cnj.jus.br/wikipje/index.php/Testes_automatizados_funcionais_-_passo_a_passo#Identificador_das_a.C3.A7.C3.B5es nesta seção]. Deste modo, sendo informada uma fase na definição da ação, esta será executada imediatamente antes do início da fase indicada. No exemplo ilustrado pela imagem, a ação do tipo '''click''' será executada imediatamente antes do início da '''fase 5''' de execução do cenário, ou seja, antes da execução do método '''posExecucaoTeste()'''.

=== Criação de ações customizadas ===
O ''framework'' disponibiliza 4 ações pré-desenvolvidas para execução dos cenários. Contudo, é possível a criação de ações customizadas para atender  necessidades específicas dos testes. Ações customizadas podem conter o comportamento que o desenvolvedor da ação julgar necessário, contudo, ela também deve ser declarada no arquivo xml do cenário. A figura seguinte apresenta um exemplo de declaração de uma ação customizada.

[[Arquivo:AcoesCustomizadas.png]]

O cenário ilustrado na figura acima mostra uma ação do tipo '''logoff'''. É importante notar que esta ação não é uma das [http://www.cnj.jus.br/wikipje/index.php/Testes_automatizados_funcionais_-_passo_a_passo#A.C3.87.C3.95ES_AUTOM.C3.81TICAS quatro ações] definidas pelo ''framework''. Por conta disso, a mera definição da ação no arquivo xml do cenário não gera qualquer efeito na execução dos testes. 

Algumas configurações são necessárias para indicar para o framework quais são as classes que implementam as ações customizadas. A primeira configuração é realizada no arquivo [http://www.cnj.jus.br/wikipje/index.php/Testes_automatizados_funcionais_-_passo_a_passo#Configura.C3.A7.C3.B5es_do_arquivo_test.properties '''test.properties''']. A variável '''acoes.customizadas.arquivo.configuracao''' indica para o ''framework'' onde encontrar o arquivo xml descritor das ações customizadas. A figura seguinte mostra um exemplo de um descritor de ações customizadas.

[[Arquivo:DescritorAcoesCustomizadas.png]]

O arquivo descritor contém uma lista de ações customizadas criadas pelo desenvolvedor. Cada ação customizada descrita neste arquivo possuir três informações obrigatórias, declaradas nos atributos:
* '''tipo''': indica o tipo da ação. Este tipo corresponde ao tipo da ação declarado no arquivo xml do cenário.
* '''classeExecucao''': classe que implementa a lógica de execução da ação.
* '''classeDados''': classe de dados que contém os dados necessários para a execução da ação.

A figura abaixo ilustra a implementação da classe '''AcaoLogoff''' declarada no arquivo descritor de ações customizadas.

[[Arquivo:ClasseAcaoLogoff.png]]

Alguns detalhes da implementação da classe '''AcaoLogoff''' devem ser conhecidos:
* na linha 1 há a declaração do pacote da classe. Deve ser o mesmo pacote declarado no arquivo xml descritor da ação.
* na linha 9 há a declaração da própyia classe. Deve ser o mesmo nome declarado no arquivo xml descritor da ação.
* entre as linhas 11 e 13 há a declaração do construtor vazio. É obrigatória esta declaração para o objeto ser instanciado dinamicamente.
* entre as linhas 15 e 19 há a declaração do método '''executar()''', obrigatório nas classes que implementam a interface '''IAcaoBase'''. É neste método que deve ser implementada a lógica de execução da ação.
* entre as linhas 22 e 24 há a declaração do método '''validarDados()''', que deve ser sobrescrito pelas classes que herdam de '''AcaoSeleniumBase'''. Cabe destacar que ações customizadas não precisam obrigatoriamente herdar da classe '''AcaoSeleniumBase'''. Optou-se por esta herança pois esta classe já implementa alguma lógica para execução no Selenium WebDriver. Caso o desenvolvedor opte por não seguir esta hierarquia, a classe criada deve implementar explicitamente a interface '''IAcaoBase'''.

Sobre a classe de dados declarada no arquivo descritor de ações customizadas, '''br.jus.cnj.tf.selenium.acoes.DadosAcaoSelenium''', é uma classe concreta disponibilizada pelo ''framework'' para manter os dados de execução. Neste caso, como a classe já existe, não foi necessário implementar outra. Contudo, o desenvolvedor pode optar por criar sua própria classe de dados. Se o fizer, basta declarar o nome e o pacote no nó classeDados do arquivo descritor. Neste caso, a classe de dados deve herdar de '''DadosAcaoBase''', e sobrescrever o métodos necessários.

=== Considerações sobre ações automáticas ===

O uso de ações automáticas visa eliminar as seguintes definições:
* declaração de atributo de dados no arquivo xml (ver [http://www.cnj.jus.br/wikipje/index.php/Testes_automatizados_funcionais_-_passo_a_passo#Cria.C3.A7.C3.A3o_do_arquivo_xml esta seção]);
* declaração de respectivo atributo na classe de dados (ver [http://www.cnj.jus.br/wikipje/index.php/Testes_automatizados_funcionais_-_passo_a_passo#Cria.C3.A7.C3.A3o_da_classe_de_dados esta seção]);
* implementação do método executarTeste() da classe de execução (ver [http://www.cnj.jus.br/wikipje/index.php/Testes_automatizados_funcionais_-_passo_a_passo#Cria.C3.A7.C3.A3o_da_classe_de_execu.C3.A7.C3.A3o esta seção]);.

Com isso, as declarações da ação '''fill''' exibidas na imagem [http://www.cnj.jus.br/wikipje/index.php/Testes_automatizados_funcionais_-_passo_a_passo#Preenchimento_de_campos_.28fill.29 nesta seção] evitam que sejam necessárias a declaração de dois atributos de dados no arquivo xml, de dois atributos na classe de dados e também evita a necessidade de implementar os métodos específicos para preenchimento dos campos na página. A figura seguinte destaca em vermelho o código que se torna desnecessário com as declarações de ações destacadas em azul.

[[Arquivo:UsoAcoesAutomaticas.png]]

Conforme destacado na imagem, a chamada da classe de dados também se torna desnecessária, visto que as próprias ações definem os valores que são usados no preenchimento dos campos. Importante destacar também a manutenção do '''click''' do botão declarada no método '''executarTeste()'''. Ele pode ser mantido porque é padrão em todos os cenários de '''Login'''. Com isso, declarar uma ação automática de '''click''' nos cenários xml seria muito repetitivo, pois a ação é sempre a mesma. Desta forma programa-se apenas uma vez no próprio cenário da classe de execução.