Manual para criação e uso de identificadores de elementos HTML

INTRODUÇÃO

Este documento é destinado a desenvolvedores de aplicações e também a desenvolvedores de testes funcionais automatizados com Selenium. O objetivo é definir um padrão para definição de identificadores (elemento id) dos elementos HTML das páginas WEB dos sistemas desenvolvidos pelo CNJ. Conhecendo o padrão de criação de identificadores, os desenvolvedores de testes automatizados poderão utilizar melhor este recurso no desenvolvimento dos scripts de testes com Selenium.

RECOMENDAÇÕES

O documento está organizado em uma série de recomendações que devem ser seguidas para que os scrips de testes automatizados permaneçam em funcionamento ao longo do tempo. Além disso, as recomendações permitem uma padronização de identificação, o que contribuirá para o reuso dos scripts de testes automatizados.

Recomendações gerais

Esta seção apresenta recomendações que devem ser seguidas na construção de qualquer página HTML que deva ser alvo de testes automatizados com Selenium.

Recomendação 1.1 - campo oculto em todas as páginas

É considerada uma boa prática colocar os Javascrips ao final das páginas HTML para trazer uma sensação de carregamento mais rápido das páginas. Contudo, isso pode ser perturbador para os criadores de scritps de testes automatizados com Selenium. Isso porque frequentemente é necessário esperar o carregamento de algum componente HTML antes de se iniciar a execução do script Selenium na página. Ocorre que, renderizado o elemento esperado, o script Selenium por vezes inicia sua execução sem que todo o Javascript tenha sido carregado. Pode ocorrer, por exemplo, que um botão seja acionado pelo Selenium sem que a ação em Javascript deste botão esteja presente na página. Isso gera anomalias na execução dos testes e, por conseguinte, resultados inesperados na página.

Para resolver este problema, recomenda-se a inserção de um campo oculto como último elemento de todas as páginas HTML do sistema. Este elemento deve ter um identificador que será usado por todos os scripts Selenium como ponto de espera, e pode ser inserido uma única vez na página de template do sistema. Sugere-se que o identificador deste elemento seja elementoEsperaSelenium.

Recomendação 1.2 - identificador para elementos estáticos

Todos os elementos estáticos das páginas HTML devem ter um identificador único. Isso é essencial para que os desenvolvedores de testes automatizados possam referenciar este identificador na página em vez de tentar localizar um elemento pela sua posição. Além disso, os identificadores devem corresponder semanticamente à função do elemento na página. A figura abaixo apresenta dois exemplos de identificadores que poderiam usados nos elementos HTML da página.

Salienta-se que, para fins de automação de testes com Selenium, o identificador precisa apenas conter um texto semanticamente significativo. No exemplo da figura acima, o identificador do componente da descrição da etnia deve conter o texto descricaoEtnia, não sendo necessário que o identificador seja igual a descricaoEtnia.

Recomendação 1.3 - identificador para páginas de template

Em páginas de template os identificadores de elementos estáticos devem possuir algum prefixo ou sufixo que os diferencie de outros nas páginas filhas. Por exemplo, se houver a definição de uma div de menu principal em uma página template, o identificador desta div deve ser algo semelhante a menuPrincipalTemplate. Caso haja templates dentro de templates esta regra deve ser mantida, com identificadores do tipo menuPrincipalTemplateGeral e menuPrincipalTemplateConteudo

Recomendação 1.4 - elementos dinâmicos

Elementos que são gerados dinamicamente pelos frameworks de camada de visão devem sempre estar dentro de algum container com identificador definido. Por exemplo, em páginas de consulta é comum que as linhas e colunas tenham seus identificadores gerados dinamicamente. Para facilitar a construção dos testes automatizados a tabela deve ter um identificador definido e deve possuir as seções thead, tbody e tfoot com identificadores definidos. Além disso, a tabela deve estar dentro de um div também com identificador definido.

Recomendações para páginas de CRUD

Esta seção apresenta recomendações que devem ser seguidas na construção de qualquer página HTML de CRUDs (Create, Read, Update e Delete).

Recomendação 2.1 - Construção de templates

Recomenda-se que as páginas de CRUD mantenham um padrão visual e comportamental, além de manteram uma padronização de nomenclatura dos elementos HTML para facilitar a construção dos testes automatizados. Esta padronização pode ser vista, por exemplo, na página de CRUD de etnias ilustrada pela figura abaixo. Ressalta-se que esta página serve apenas como exemplo, não sendo necessário seguir este padrão visual.

É possível observar na figura que há pelo menos três áreas que são (ou podem ser) comuns a todas as páginas e consulta: uma área que serve como container para os elementos de filtro, uma área container para os botões de ação e outro container para os resultados da pesquisa. Esta disposição de campos, quando possível, deve ser incluída em um tamplate para páginas da mesma categoria.

Recomendação 2.2 - Páginas de consulta

Nas páginas de consulta geralmente há a presença de um botão de consulta e de um botão de limpeza de campos. Pode-se tomar como exemplo a página de cadastro de etnias exibida pela figura acima. Recomenda-se, nestes caso, mesmo quando não seja viável o uso de templates, que os botões que disparam ações de consulta tenham sempre o mesmo identificador, o mesmo valendo para botões que limpam os filtros de pesquisa. No exemplo acima o identificador dos botões poderiam ser os seguintes:

• botão Pesquisar: id="botaoPesquisar"
• botão Limpar: id="botaoLimpar"

Recomendação 2.3 - Páginas de cadastro/alteração

Páginas de CRUD geralmente reusam o mesmo conteúdo HTML para a inserção e para a alteração de registros. Esta característica deve ser estimulada para que o mesmo script de teste automatizado possa tratar inserções e alterações de maneira uniforme. A figura abaixo mostra as páginas de cadastro e de alteração de etnia, nesta ordem. Pode-se verificar que ambas as páginas matêm os mesmos campos tanto no cadastro quanto na alteração.

Também é recomendável que os identificadores dos botões de inserção, alteração e de novo registro mantenham os mesmos identificadores em todas páginas de CRUD, mesmo nos casos em que não seja viável o uso de templates. No exemplo acima o identificador dos botões poderiam ser os seguintes:

• botão Incluir: id="botaoIncluir"
• botão Gravar: id="botaoGravar"
• botão Novo: id="botaoNovo"

Recomendações para o PJe

Esta seção apresenta recomendações que devem ser seguidas na construção de páginas do PJe. Elas dizem respeito principalmente à padronização de nomeclatura de componentes específicos em páginas do sistema.

Recomendação 3.1 - campos compostos

Alguns inputs das páginas do PJe são compostos por mais de um elemento HTML. É o caso dos campos de número de processo e de inscrição na OAB, por exemplo. Nestes casos, sempre que o framework da camada de visão permitir, devem ser construídos componentes padronizados para os campos compostos, que serão utilizados nas páginas onde forem necessários. Isso permite a manutenção do padrão visual e comportamental do componente, além de facilitar a construção de testes automatizados para os componentes.

Recomendação 3.2 - número da OAB

O número da OAB dos advogados é composto sempre por três elementos. A figura a seguir apresenta um fragmento da página de pesquisa de processo em que constam estes campos.

Recomenda-se que seja criado um padrão para apresentação destes campos, sempre que possível na mesma ordem, e sempre com os mesmos identificadores. Abaixo segue um exemplo de identificadores para os campos da imagem, na mesma ordem em que são apresentados na página.

• seccional da inscrição: id="estadoInscricaoOAB"
• número da inscrição: id="numeroInscricaoOAB"
• letra da inscrição: id="letraInscricaoOAB"

Recomendação 3.3 - número do processo

Da mesma forma que a inscrição na OAB, o número do processo é composto por vários elementos HTML. Neste caso são 6 elementos, um para cada fragmento do número do processo. Recomenda-se que cada um dos elementos HTML que compõem o número do processo tenha um identificador padronizado que se repita em todas as páginas que usar estes elementos. A figura a seguir apresenta um fragmento da página de pesquisa de processo em que constam estes campos.

Abaixo segue um exemplo de identificadores para os campos da imagem, na mesma ordem em que são apresentados na página.

• número sequencial do processo: id="numeroProcessoSequencial"
• dígito verificador do número: id="numeroProcessoDigitoVerificador"
• ano do número: id="numeroProcessoAno"
• tipo de justiça: id="numeroProcessoTipoJustica"
• número do tribunal: id="numeroProcessoTipoTribunal"
• número do órgão da justiça: id="numeroProcessoOrgaoJustica"

Recomendação 3.4 - campos simples

O PJe possui vários campos que são comuns em muitas páginas, e que na estrutura frequentemente possuem identificadores diferentes nas diferentes páginas em que são utilizados. São exemplos de campos comuns os seguintes elementos HTML:

• select para Órgão Julgador
• select para Órgão Julgador Colegiado
• select para Escolaridade
• select para Sexo
• select para Etnia
• select para Estado Civil
• select para Estado
• select para País
• input para CPF
• input para CNPJ
• input para Classe Juficial
• input para Assunto Processual
• input para Localização
• input para Data de Nascimento

A lista acima não busca exaurir as possibilidades. O objetivo é buscar uma forma de que estes elementos tenham sempre os mesmos identificadores em quaisquer páginas em que forem inseridos. A criação de componentes no framework da camada de visão pode ser uma forma de alcançar este objetivo de forma mais eficiente.