Liderança em Testes: Documentação

Nota do editor: Bem-vindo à série Liderança em Testes, do guru e consultor de testes de software Paul Gerrard. A série foi concebida para ajudar os testadores com alguns anos de experiência — especialmente os que trabalham em equipas ágeis — a destacarem-se nas suas funções de liderança e gestão de testes.

No artigo anterior, apresentámos um manifesto de risco para ajudar os gestores. Neste artigo, colocaremos a velha questão “Quanto teste é suficiente?”. Spoiler: cabe às partes interessadas decidir.

Subscreva a newsletter The QA Lead para receber uma notificação quando forem publicados novos artigos da série. Estes artigos são excertos do curso Liderança em Testes de Paul, que recomendamos vivamente para aprofundar este e outros temas. Se o fizer, utilize o nosso código de cupão exclusivo QALEADOFFER para obter $60 de desconto no preço total do curso!

Independentemente do projeto, da organização ou da abordagem, há sempre lugar para a documentação. Uma boa documentação é uma bênção, proporcionando um registo útil da abordagem, do âmbito, dos planos, dos designs e dos resultados das atividades de análise, desenvolvimento e testes.

Neste artigo, abordarei:

O Valor da Documentação
Os Perigos dos Modelos e do Copiar/Colar
Tipos de Documentação de Testes
Conselhos para Conceber a Documentação

Vamos começar.

O Valor da Documentação

Em projetos estruturados, os documentos são normalmente considerados entregáveis por direito próprio. Em contextos ágeis ou contínuos, a documentação pode ser produzida como um subproduto de maior ou menor valor.

A redação de documentos pode ser a atividade principal dos redactores técnicos profissionais, mas, para a maioria dos profissionais, é uma tarefa penosa — por muito útil que possa ser. Embora a redação de documentos possa ser aborrecida para algumas pessoas, o verdadeiro problema da documentação é que, em muitos contextos, a maior parte dela é simplesmente uma perda de tempo. Tem pouco valor, está desatualizada, é imprecisa — ou reúne as três características.

Todos os gestores de testes já redigiram estratégias de testes que as pessoas não leram nem aceitaram. Os testadores escrevem páginas e páginas de planos, guiões e relatórios de testes, e o único conteúdo de valor para as partes interessadas são os resumos de uma página no início ou no fim.

Todos já redigimos documentos que sabemos terem pouco valor e que ninguém irá ler.

Isto resulta de problemas comuns com a documentação que encontramos em projetos grandes e pequenos. Para cada documento que redigimos, há várias questões que precisamos de abordar:

Que tipo de documento? Uma política ou estratégia, uma abordagem ou plano, um design ou implementação, ou um resultado e respetiva interpretação?
Qual é o objetivo do documento?
Que conteúdo é necessário para cumprir esse objetivo?
Que fontes de conhecimento são necessárias para criar o conteúdo?
Se o documento tiver de mudar ao longo do tempo, como será mantido?
Que nível de detalhe é necessário?

Enquanto gestor de testes ou enquanto equipa, terão de determinar que tipos e formatos de documentação são adequados e, caso se destinem a ser registos exatos ou os chamados documentos vivos, como serão mantidos.

Get Free Access

Get regular tech leadership wisdom for delivering better software and systems.

Have an account? Log In

Os Perigos dos Modelos e do Copiar/Colar

Se o seu projeto determinar que é necessário um determinado documento, por exemplo, um plano de testes do sistema ou um registo de riscos, é tentador procurar na internet um modelo pronto a utilizar para estes documentos — e para muitos outros tipos de documentos.

Alguns modelos podem alegar cumprir uma determinada norma ou convenção e ter sido descarregados e utilizados milhares de vezes. Por vezes, um modelo pode parecer adequar-se exatamente ao seu objetivo. Mas, como veremos, mesmo que o índice pareça abrangente, pode causar-lhe problemas.

Também pode acontecer que você ou outras pessoas da sua empresa tenham preparado um documento semelhante para projetos anteriores. Poderá sentir-se tentado a copiar e mudar o nome desse documento, alterar as referências ao projeto antigo e editar o conteúdo para o adaptar.

Aviso: Na minha experiência enquanto revisor independente, isto é muito comum e constitui frequentemente um problema real.

Em primeiro lugar, é normalmente evidente que foi feita uma cópia ou edição. A linguagem utilizada no texto parece frequentemente desligada do projeto e existem lacunas e texto supérfluo por todo o lado. Porquê?

A utilização de um modelo pré-formatado ou de um documento existente como fonte acarreta vários riscos:

Parece abrangente, mas pode incluir tópicos inadequados e excluir outros que são essenciais.
Fornece títulos para um documento, mas não dá absolutamente nenhuma orientação quanto ao conteúdo adequado para cada título.
Pode conter texto que parece reutilizável e que foi copiado sem alterações de um projeto anterior não relacionado, mas esse texto pode transmitir uma impressão errada ou ser incorreto ou incompleto.

A utilização de modelos para obter títulos e uma estrutura básica de formatação pode ser útil, mas o principal problema dos modelos é este:

*A utilização de um modelo pode poupar algum tempo; o risco é não dedicar reflexão suficiente à redação.*

A tentação com os modelos é confiar demasiado neles e depois escrever conteúdo vazio para as várias secções. Afinal, pode pensar que o documento serve apenas para assinalar uma ‘caixa’ e que, de qualquer forma, ninguém o irá ler. O risco dos modelos é deixar de pensar e escrever um documento com pouco valor.

Tipos de documentação de testes

Nesta secção, analisaremos as várias formas de documentação de testes e discutiremos algumas considerações em projetos estruturados ou ágeis/contínuos, em comparação com o modelo tradicional em cascata.

O conjunto principal de documentos de testes tende a inserir-se nas seguintes categorias:

Política e estratégia (por vezes conhecido como Plano Diretor de Testes)
Definição de testes (também conhecida, de forma confusa, como especificação ou planos de testes)
Conceção de testes
Casos de teste
Procedimentos ou guiões de teste
Execução de testes
Planeamento
Registo
Relatório de testes

A variedade de tipos de documentos acima abrange a definição do processo de testes, as principais atividades de definição e execução e a elaboração de relatórios.

Existem vários outros documentos relacionados com testes que, em ambientes mais burocráticos, incluiriam definições dos ambientes de teste e processos de gestão, procedimentos de aceitação, processos de gestão de incidentes e assim por diante (abordaremos a gestão de incidentes num artigo futuro).

Outra omissão óbvia na lista acima seria um plano ou calendário geral para as atividades de testes. Um calendário não é propriamente um documento de testes; é um subconjunto do plano geral de um projeto estruturado (também abordaremos o planeamento de calendários num artigo futuro, por isso, fique atento!).

Política, estratégia e Plano Diretor de Testes

*Finalidade*	Uma política abrange normalmente uma organização e inclui um subconjunto de tópicos que abrangem todos os projetos. Uma estratégia abrange normalmente um único projeto (ou aplicação) De um modo geral, a estratégia fornece decisões tomadas sobre questões logísticas relativas à abordagem, transferências, responsabilidades, ambientes, etc. Algumas destas decisões podem ser tomadas antecipadamente e documentadas na estratégia Algumas decisões não podem ser tomadas agora, mas a estratégia pode documentar o processo, método ou informação que permitirá tomar decisões (no projeto) Para situações incertas ou eventos não planeados em que seja necessário tomar decisões, a estratégia documentará os princípios gerais (ou o processo) a seguir.
*Conteúdo*	Partes interessadas, objetivos e principais riscos relevantes Princípios/abordagem de testes a adotar, por exemplo, a abordagem de testes baseados no risco Processo de testes (fases dos testes): objetivos e âmbito critérios de aceitação métodos e técnicas entregáveis (documentos) responsabilidade Atividades de testes não funcionais/técnicos Política de gestão de fornecedores de testes Processo de gestão de incidentes Fontes de dados de teste Ambientes de teste Estratégia de ferramentas/automação Formatos/modelos de documentação
*Fontes*	Partes interessadas, utilizadores, BA, programadores e operações
*Manutenção*	Normalmente, um documento único definido para um projeto ou programa
*Considerações Ágeis/Contínuas* A estratégia de testes para projetos ágeis que utilizam Scrum, por exemplo, tende a ser bastante breve e a consistir apenas em algumas páginas (se for documentada). O processo de testes pode não ter fases, mas é provável que exista uma definição de testes a diferentes níveis. Por exemplo: Testes numa sprint ou iteração Testes para uma versão Testes de integração de sistemas (com outros sistemas ou interfaces) Testes com utilizadores (aceitação ao nível da sprint e/ou da versão). A forma como as ferramentas são utilizadas nos testes realizados pelos programadores (e a utilização de BDD ou TDD, por exemplo) provavelmente não será documentada, mas seria esperado que as equipas de desenvolvimento evoluíssem uma abordagem e colaborassem com os restantes membros da equipa à medida que submetem novo código. O papel do testador pode consistir em testar interativamente as funcionalidades à medida que são disponibilizadas pelos programadores ou em atuar como orientador de testes para o resto da equipa. Tal como acontece com a utilização de ferramentas e/ou TDD, a forma de trabalhar evoluiria ao longo do tempo e poderia nunca ser documentada formalmente.

Definição dos testes (conceção, casos e procedimentos)

*Finalidade*	Demonstrar o fluxo ou a rastreabilidade entre as fontes de conhecimento e os testes a realizar Documentar a cobertura (com base em vários modelos) dos aspetos dos requisitos, das funcionalidades do sistema ou do comportamento dos utilizadores Permitir que as partes interessadas revejam o âmbito, a abordagem, a cobertura e as opções escolhidas na criação dos testes a aplicar Fornecer instruções para a execução dos testes num nível de detalhe acordado.
*Conteúdo*	Âmbito dos testes – tanto a um nível elevado, por exemplo, funcionalidades, como a um nível inferior, por exemplo, modelos de comportamento Cobertura dos testes em relação aos itens abrangidos (por exemplo, uma matriz de cobertura de requisitos ou outro modelo de testes) Casos de teste que identificam funcionalidades, pré-condições, entradas e pós-condições (incluindo os resultados esperados) Procedimentos de teste, reutilizáveis para executar casos de teste selecionados.
*Fontes*	Partes interessadas, utilizadores, requisitos, conceções e especificações
*Manutenção*	Em princípio, com requisitos fixos, deverá existir uma versão acordada destes documentos Quando ocorrem alterações aos requisitos ou ao âmbito, os testadores terão de ajustar os documentos, manter os aspetos rastreáveis da documentação e fornecer uma gestão da configuração ou um registo de alterações.
*Considerações Ágeis/Contínuas* A área da definição de testes é aquela em que a abordagem ágil mais se distingue dos projetos estruturados. Potencialmente, os testadores que se concentram nas funcionalidades à medida que estas são disponibilizadas podem não criar qualquer documentação. Isto é adequado se existir, por exemplo, uma política ou um estatuto de testes de âmbito global do sistema para os testes de funcionalidades. É mais provável que exista um breve estatuto para testar cada funcionalidade numa sessão de testes exploratórios. Um estatuto é semelhante a um plano para um curto período de exploração. Normalmente, o estatuto identificaria: O âmbito da sessão de testes – a(s) funcionalidade(s) a abranger e/ou alguma funcionalidade ou comportamento especificado do sistema O objetivo da sessão – explorar determinados aspetos dos comportamentos, concentrar-se num risco ou modo de falha, aplicar alguns cenários selecionados A duração da sessão é normalmente de 45-120 minutos. A sessão tem necessariamente um âmbito limitado, mas os testadores são livres de explorar fora desse âmbito se considerarem que isso é útil Um estatuto pode ter como objetivo concentrar-se na exploração – aprender o que uma funcionalidade faz, identificar comportamentos específicos que valha a pena testar, avaliar quantos testes/quantas sessões são necessários para testar uma funcionalidade grande ou complexa, compreender que dados de teste poderão ser necessários para a testar, entre outros aspetos Um estatuto pode concentrar-se especificamente no teste de uma funcionalidade, mas pode destacar algumas áreas que necessitam de mais atenção do que outras. As ferramentas e histórias de BDD num formato selecionado, por exemplo, histórias e cenários formatados em Cucumber ou Gherkin, podem fornecer a rastreabilidade e o conteúdo assegurados pelas conceções e procedimentos de teste. Cada cenário com cláusulas ‘dado/quando/então’ identifica pré-condições, entradas e pós-condições. Estes são referenciados a uma única funcionalidade, pelo que fornecem um caso/procedimento de teste mínimo e são, pelo menos, rastreáveis às funcionalidades. Os testes que foram escritos para serem executados por ferramentas podem ou não ter documentação intermédia. As equipas dependem mais da observação dos testes automatizados e das tabelas de dados de teste utilizadas pelos scripts automatizados do que de conceções de testes documentadas.

Execução de testes (calendário, registo)

*Objetivo*	Especificar a ordem de execução dos testes Registar o estado dos testes – executado/não executado e estado Fornecer os resultados da execução dos testes para elaboração de relatórios
*Conteúdo*	Identificador do teste, responsável pelos testes, data/hora de execução, estado Para testes que aparentem apresentar um comportamento anómalo (opcionalmente): Detalhes do teste tal como foi executado quando os detalhes diferem do guião Resultados reais vs. esperados Outras observações, interpretação Estado do teste (defeito, configuração ou anomalia do ambiente, etc.) ID da observação ou do relatório de defeito (quando apropriado)
*Fontes*	Inventário de casos/procedimentos de teste, responsáveis pelos testes
*Manutenção*	O calendário deverá ser alterado de acordo com o âmbito dos testes e com os procedimentos alterados, removidos ou adicionados ao plano. É provável que os testes sejam executados várias vezes, quer como novos testes, quer como testes de regressão. O registo deverá conter um histórico completo de todos os testes abrangidos.
*Considerações sobre projetos ágeis/contínuos* Se os projetos ágeis/contínuos não se comprometerem com documentos de definição de testes, compensam parcialmente essa situação incentivando os responsáveis pelos testes a manter registos mais detalhados da execução dos testes. Quando os testes são realizados em sessões com base em guiões, espera-se que o responsável pelos testes mantenha boas notas sobre os testes que executa. Existem poucas ferramentas dedicadas ao registo de testes que sejam mais do que simples cadernos, pelo que muitos responsáveis pelos testes utilizam editores de texto simples, aplicações de tomada de notas ou cadernos em papel. Os registos tendem a ser utilizados para registar toda a atividade significativa e as observações feitas durante as sessões. Um registo típico de testes exploratórios conteria aspetos como: Estrutura das funcionalidades exploradas (um mapa do território) Observações e questões relacionadas com as funcionalidades exploradas na sessão Modelos, listas e tabelas de itens de teste e ideias de teste Testes executados, registados com detalhe suficiente para serem repetidos Anomalias encontradas – falhas, comportamento questionável, respostas lentas, má experiência do utilizador, entre outras Tempo despendido na exploração, configuração dos testes, realização dos testes, investigação, registo de erros, repetição dos testes, testes de regressão e tempo não produtivo Data/hora do registo Quando os responsáveis pelos testes registam a atividade das suas sessões em ferramentas de tomada de notas ou noutras ferramentas, utilizam algum tipo de marcação ou outra linguagem específica do domínio para estruturar as suas notas. Estas podem ser analisadas por ferramentas internas simples para fornecer resumos da atividade a utilizar no relatório de testes. Os testes executados por ferramentas (quer sejam proprietárias ou de código aberto) mantêm registos automaticamente. Normalmente, estes registos podem ser consultados pela ferramenta ou por procedimentos escritos pelo utilizador.

Relatório de testes

*Objetivo*	Comunicar o resultado de uma fase de testes, de testes selecionados ou de uma sessão de testes Pode também aplicar-se a requisitos técnicos ou a atividades de testes não funcionais, caso em que o conteúdo seria diferente para corresponder ao objetivo dos testes Informar parcialmente as partes interessadas, permitindo-lhes tomar uma decisão sobre a aceitação ou o lançamento de um sistema ou subsistema.
*Conteúdo*	Horas de início/fim e duração dos testes Ambiente de testes Versão(ões) do software e do sistema em teste Objetivos e âmbito dos testes (da estratégia de testes e da definição dos testes) Resumo narrativo dos resultados Funcionalidades consideradas como estando a funcionar conforme necessário Riscos considerados como tendo sido tratados Testes significativos pendentes (falhados ou bloqueados) Funcionalidades parcialmente testadas e não testadas Riscos parcialmente tratados ou não tratados. Detalhes dos resultados dos testes, com resultados provenientes dos registos de testes, etc. Estado das soluções alternativas para anomalias pendentes Análises dos testes Progresso e estado dos testes ao longo do tempo Estatísticas de incidentes
*Fontes*	Estratégia de testes, definições dos testes, registo de testes, relatórios de incidentes Grande parte do conteúdo de um relatório de testes será constituída pelas ferramentas utilizadas para registar a(s) definição(ões) dos testes, o registo de testes e o registo de incidentes ou defeitos.
*Manutenção*	Trata-se de um instantâneo no tempo relativo a uma fase de execução de testes e não é mantido.
*Considerações sobre Agile/Contínuo* O objetivo de um relatório de testes num projeto ágil pode abranger uma única iteração ou sprint, os testes para uma versão ou uma fase de testes de nível superior, como a integração ou a aceitação global do sistema. Seja qual for o caso, o objetivo não se altera. Grande parte do conteúdo de um relatório de testes provirá de ferramentas ou de notas dos testadores. O resumo narrativo dos resultados é redigido por um responsável pelos testes ou pelo testador de uma fase de testes de menor escala. Como habitualmente, é provável que o relatório seja menos formal e que contenha menos dados brutos que possam servir de base a análises sofisticadas. Certamente, durante a(s) iteração(ões), o progresso ao longo da iteração em termos de funcionalidades ou histórias entregues, testadas e aprovadas pelos utilizadores poderá ser registado numa ferramenta ou num quadro Kanban público. Desta forma, as partes interessadas são mantidas informadas sobre o progresso ao longo de toda a iteração e há menos necessidade de um relatório formal no final de um período de testes. A visibilidade do progresso é uma preocupação fundamental para as equipas ágeis. Com reuniões diárias regulares, talvez em torno de um quadro Scrum, por exemplo, os membros da equipa partilham constantemente a sua compreensão do progresso, questionam-se mutuamente e acordam uma posição (e os passos seguintes). Desta forma, poderá nunca ser necessário um relatório formal de testes, porque a equipa está sempre informada e atualizada. Se os testadores mantiverem notas escritas das atividades das suas sessões, não estarão disponíveis dados analisáveis para apresentar relatórios automatizados, pelo que os relatórios das sessões e do progresso poderão ser apresentados de forma pública e visual. Isto exige um elevado grau de disciplina e boas capacidades de comunicação por parte dos testadores. O responsável pelos testes ou gestor terá de fornecer às partes interessadas um relatório igualmente informativo, com base em relatórios verbais.

Alguns conselhos

O tema da documentação em projetos é sensível tanto para os testadores como para os restantes membros da equipa do projeto.

A maioria das pessoas considera a redação de documentação uma tarefa penosa.

Eis alguns aspetos a ter em conta ao conceber a sua documentação.

A documentação deve ter um objetivo e um público bem definidos. Se o seu público não precisar da documentação, não a lerá. Se ela não estiver alinhada com os seus próprios objetivos, não a aceitará.
É geralmente melhor registar uma atividade antes de a realizar ou enquanto a realiza. Por exemplo, o TDD regista os testes antes de o código ser escrito. Os registos das sessões de testes devem ser capturados durante a sessão e não redigidos posteriormente.
Os dados essenciais a registar sobre um aspeto dos testes podem ser mínimos. Por exemplo, um teste registado num caderno pode ser suficiente para o testador, mas não pode ser facilmente analisado. Talvez um simples registo de texto com alguma formatação fosse igualmente rápido de capturar, mas também pudesse ser analisado por uma ferramenta personalizada.
Os procedimentos de teste podem nem sequer ser necessários se os testadores conhecerem bem o sistema em teste. Talvez seja necessário apenas um objetivo ou uma carta de testes. Os casos de teste preparados podem ser documentados de forma mínima numa folha de cálculo.

Por fim

A necessidade é a mãe da documentação.

Se preparar uma documentação abrangente para as suas partes interessadas e elas não a lerem, é porque não lhe reconhecem valor.

É melhor apresentar a uma parte interessada uma folha em branco e acrescentar em conjunto os tópicos que ela precisa de ver num documento, trabalhando a partir daí. Pode acontecer que peça resmas de conteúdo, mas aquilo de que realmente precisa seja bastante simples. Continue a perguntar: «porque é que querem isto?»

Obrigado por ler. Junte-se a nós da próxima vez, quando arregaçarmos as mangas e começarmos a trabalhar no planeamento de testes.

Subscreva o boletim informativo da The QA Lead para receber uma notificação quando forem publicados novos artigos da série. Estas publicações são excertos do curso de Liderança em Testes do Paul, que recomendamos vivamente para uma análise mais aprofundada deste e de outros temas. Se o fizer, utilize o nosso código de cupão exclusivo QALEADOFFER para obter um desconto de $60 no preço total do curso!