Forem: Ricardo Silva

Desafios Comuns na Escrita de Testes Automatizados: Rumo à Clareza e Padronização - Parte 3

Ricardo Silva — Tue, 27 Feb 2024 14:59:49 +0000

Na parte dois, nós vimos as três etapas que compõem um teste automatizado: Preparação, execução e resultado.

Com isso em mente, vamos dedicar nossa terceira parte a responder às seguintes perguntas:

O que devo testar?
O que não devo testar?

O que devo testar?

Apesar de ser uma atividade técnica, o ato de testar é influenciado por alguns fatores subjetivos que podem dificultar a vida de uma pessoa na hora de definir o escopo que precisa ser testado. Cada membro pode ter sua própria interpretação do que é importante testar, e isso é um fator subjetivo. Determinadas partes do sistema têm mais criticidade que outras, e isso é outro fator subjetivo.

Antes de mais nada, o time precisa ter discussões claras que irão colocar todos na mesma página a respeito do que é importante testar, pois estabelecendo esse tipo de acordo, ficará mais fácil identificar quando determinada entrega (um PR, por exemplo) contém testes que fogem muito da estrutura dos demais testes existentes no projeto.

Eu costumo propor que os testes precisam usar como referência principal os requisitos da tarefa, levando em conta os cenários "felizes" e "não felizes", onde o caminho feliz é o percurso ideal de execução, seguindo todas as condições esperadas sem ocorrência de erros, contrastando com o caminho não feliz, que abrange situações indesejadas ou desvios do comportamento previsto.

Se essas informações não estão claras na descrição da tarefa, é importante mapeá-los (ao menos os iniciais, uma vez que dúvidas e requisitos não identificados antes poderão aparecer durante o processo de desenvolvimento).

Vamos considerar que a seguinte task foi criada no board do projeto:

Cadastro de Chamado no Sistema

História:
Como usuário do sistema, desejo poder cadastrar um chamado para reportar problemas ou solicitar suporte.

Critérios de Aceitação:

Número Único de Identificação:
- Após o cadastro bem-sucedido, com usuário informando título e descrião do chamado, o sistema deve gerar automaticamente um número único de identificação para o chamado.
- Número único de identificação precisa conter letras maísculas e números

Cenários de Teste:

Caminho Feliz:
- O sistema gera um número único de identificação para o chamado.
Caminho Não Feliz:
- O usuário tenta cadastrar um chamado sem preencher todos os campos obrigatórios, resultando em uma mensagem de erro.

Vamos supor que estamos na etapa de construir um Service Object que aplicará essas regras descritas na tarefa. Um bom ponto de partida seria “transferir os requisitos” da tarefa para uma estrutura mais ou menos assim:

# ticket_creator_spec.rb

RSpec.describe TicketCreator do
  describe '#call' do
    context 'When title and description are filled in' do
      it 'generates a unique identification number with uppercase letters and numbers' do
        # etapas do caminho feliz ficarão aqui
      end
    end

    context 'When title is not filled in' do
      it 'raises an error' do
        #etapas do caminho não feliz ficarão aqui
      end
    end
  end
end

O próximo passo é focar em escrever as etapas dos testes. Vamos começar pelo caminho feliz?

Podemos dar início através do setup do teste, sempre tentando montar essa etapa somente com o que é estritamente necessário. Nesse caso, seriam os dados de título e descrição.

# ticket_creator_spec.rb

RSpec.describe TicketCreator do
  describe '#call' do
    context 'When title and description are filled in' do
      it 'generates a unique identification number with uppercase letters and numbers' do
         valid_attributes = { 
                   title: 'Issue Title', 
                     description: 'Detailed description of the issue' 
                 }
      end
    end

    context 'When title is not filled in' do
      it 'raises an error' do
        #etapas do caminho não feliz ficarão aqui
      end
    end
  end
end

Como eu considero que isso é muito pouco para executar o teste, vou seguir com o segundo passo, que seria a execução, colocando em nosso teste a unidade de código testada.

# ticket_creator_spec.rb

RSpec.describe TicketCreator do
  describe '#call' do
    context 'When title and description are filled in' do
      it 'generates a unique identification number with uppercase letters and numbers' do
         valid_attributes = { 
                   title: 'Issue Title', 
                     description: 'Detailed description of the issue' 
                 }

                ticket = TicketCreator.new(valid_attributes).call
      end
    end

    context 'When title is not filled in' do
      it 'raises an error' do
        #etapas do caminho não feliz ficarão aqui
      end
    end
  end
end

Aqui já conseguimos ter duas escolhas:

Rodar o teste e receber o feedback de que a classe TicketCreator ainda não existe, mais ou menos assim:
```
NameError:
  uninitialized constant TicketCreator
```
Partir para a terceira etapa, que seria determinar que após a execução da unidade de código (TicketCreator), um identification_number precisa ter sido gerado

Se a ideia for seguir pelo segundo caminho, nosso teste poderia ficar mais ou menos assim:

# ticket_creator_spec.rb

RSpec.describe TicketCreator do
  describe '#call' do
    context 'When title and description are filled in' do
      it 'generates a unique identification number with uppercase letters and numbers' do
         valid_attributes = { 
                   title: 'Issue Title', 
                     description: 'Detailed description of the issue' 
                 }

                ticket = TicketCreator.new(valid_attributes).call

                expect(ticket.identification_number).not_to be_nil
                expect(ticket.identification_number).to match(/\A[A-Z0-9]+\z/)
      end
    end

    context 'When title is not filled in' do
      it 'raises an error' do
        #etapas do caminho não feliz ficarão aqui
      end
    end
  end
end

Na medida em que formos rodando os testes, coletando os feedbacks e implementando o código até que os testes passem
(ciclo Red-Green-Refactor), no final teremos uma classe mais ou menos assim:

# app/services/ticket_creator.rb

class TicketCreator
  attr_reader :title, :description

  def initialize(attributes = {})
    @title = attributes[:title]
    @description = attributes[:description]
  end

  def call
    ticket = Ticket.create(
      title: title,
      description: description,
      identification_number: generate_identification_number
    )

    ticket
  end

  private

  def generate_identification_number
    SecureRandom.hex(6).upcase
  end
end

Uma vez que o caminho feliz foi implementado, podemos partir para a implementação do cenário não feliz com a confiança de que, caso façamos besteira e o caminho feliz pare de funcionar, seremos devidamente advertidos pelos testes.

Primeiro os testes

# ticket_creator_spec.rb

RSpec.describe TicketCreator do
  describe '#call' do
    context 'when title and description are filled in' do
      it 'generates a unique identification number with uppercase letters and numbers' do
         valid_attributes = { 
                   title: 'Issue Title', 
                     description: 'Detailed description of the issue' 
                 }

                ticket = TicketCreator.new(valid_attributes).call

                expect(ticket.identification_number).not_to be_nil
                expect(ticket.identification_number).to match(/\A[A-Z0-9]+\z/)
      end
    end

    context 'when title is not filled in' do
      it 'raises an error' do
        invalid_attributes = { 
          title: '', 
          description: 'Detailed description of the issue' 
        }

        expect { TicketCreator.new(invalid_attributes).call }.to raise_error(ValidationError, 'Title can\'t be blank')
      end
    end
  end
end

Agora a implementação

# app/services/ticket_creator.rb

class TicketCreator
  attr_reader :title, :description

  def initialize(attributes = {})
    @title = attributes[:title]
    @description = attributes[:description]
  end

  def call
    validate_attributes

    ticket = Ticket.create(
      title: title,
      description: description,
      identification_number: generate_identification_number
    )

    ticket
  end

  private

  def validate_attributes
    raise ValidationError, 'Title can\'t be blank' if title.blank?
  end

  def generate_identification_number
    SecureRandom.hex(6).upcase
  end
end

Obviamente, o código final da classe irá variar de acordo com o gosto da pessoa/time que estiver desenvolvendo, mas o importante aqui é que, desde o início, o foco sempre foi atender aos requisitos determinados na tarefa e avançar em direção a um código legível e organizado, uma prova de que os testes têm influência direta no design do código implementado, ao mesmo tempo em que diminui os riscos de se gerar novos bugs durante o processo.

Outro ponto que vale destacar é a relevância dos dados de entrada das classes em relação aos dados de saída. Através dos dados de entrada, nós conseguimos ter total controle a respeito dos resultados esperados, baseado nos contextos definidos. É por isso que passar um título preenchido ou não foi o suficiente para simular o caminho feliz e o caminho não feliz.

O que não devo testar?

Existe um motivo para que o método call seja o único método levado em consideração nos testes: métodos privados são detalhes de implementação e não devem ser testados diretamente, ao mesmo passo em que, se uma classe tem somente um método público, isso será uma forma de garantir que ela assumirá somente uma responsabilidade (aqui não é sobre testes necessariamente, mas sobre o princípio de responsabilidade única)

O foco do teste precisa ser garantir que o comportamento externo da unidade de código (a classe TicketCreator) atenda aos requisitos especificados. E isso acontece através dos métodos públicos, que são de quem os usuários e outros componentes dependerão.

Testar métodos privados pode (e provavelmente vai) resultar em testes frágeis e poluídos, uma vez que estarão sujeitos a mudanças internas na implementação que não afetarão o comportamento externo da unidade de código testada, ou seja: a saída do método público. Isso quer dizer que mudanças nos métodos privados poderão ou não causar quebra ou mudança no comportamento da classe, mas caso cause, os testes do método público já estarão cobrindo isso.

Se um método privado executa rotinas muito complexas, vale a pena extrair esse código para uma classe contendo seus próprios testes.

Testes simples, implementação simples… De complicado já basta a vida, não é verdade?

E assim finalizamos a parte três da nossa série.

Nos vemos na parte quatro!

Desafios Comuns na Escrita de Testes Automatizados: Rumo à Clareza e Padronização - Parte 2

Ricardo Silva — Fri, 23 Feb 2024 01:17:48 +0000

Na primeira parte nós vimos como testes são uma excelente forma de documentação, principalmente se os blocos describe, context e it estiverem organizados e com descrições claras, ajudando a dar clareza a respeito do objetivo daquela unidade de código em questão (e qual o papel dela em relação a outras unidades de código).

A ideia dessa segunda parte é continuar trabalhando padrões, agora focando nos seguintes pontos:

Etapas de um teste automatizado
Testes e implementação são interdependentes (e isso não deveria ser negociável)

> Etapas de um teste automatizado

Um teste automatizado é composto por três etapas:

Preparação(Setup) - Aqui a gente carrega tudo aquilo que consideramos necessário para testar nossa unidade de código, seja a criação de um registro no banco, chamada para uma API externa, carregamento de arquivos e tudo mais que for imprescíndivel antes e para execução dos testes.

Execução(Execution) - Aqui é onde as coisas acontecem de fato. Nessa etapa o teste vai servir como gatilho para executar a unidade de código alvo, seja uma classe, um endpoint ou qualquer outro componente do sistema. Eu não vou dizer que absolutamente tudo pode ser testado, mas até hoje não vi algo que não possa. Porém, vale destacar que o verdadeiro objetivo é testar tudo aquilo que é referente a regras de negócio do sistema. Então não faz muito sentido testar métodos de uma biblioteca, por exemplo.

Resultado(Assertion/Verification) - Aqui é a etapa onde a gente verifica se o comportamento esperado da unidade de código aconteceu como esperado, de acordo com o cenário proposto, como por exemplo se algum registro foi criado/alterado no banco.

Exemplo:

it 'must change the band name' do
  # Preparação: Cria uma banda com o nome 'The Rolling Stones'
  band = create(:band, name: 'The Rolling Stones')

  # Execução: Executa a unidade de código desejada
  updated_band = BandNameUpdater.new(band, 'Oasis').call

  # Resultado: Valida se o resultado saiu conforme esperado
  expect(updated_band.name).to eq('Oasis')
end

Independente do tamanho e complexidade do que está sendo testado, o objetivo é sempre se ater a essas três etapas na hora de construir ou modificar seus testes, tentando sempre mantê-los o mais simples possível. E é aqui onde os testes começam a influênciar diretamente na qualidade do código do software, pois se estiver sendo difícil contemplar os possíveis comportamentos de uma unidade de código através dessas três etapas, isso pode ser o primeiro sinal de que essa unidade de código está assumindo multiplas responsabilidades e possivelmente uma quebra em unidades de códigos menores deverá ser seu próximo passo, com o intuito de torna-la mais coesa.

> Testes e implementação são interdependentes (e isso não deveria ser negociável)

Essas três etapas também estão presentes em testes manuais. Se você usa ferramentas como o postman, por exemplo, você vai precisar criar objetos no banco, setar URL's, configurar headers (Preparação). Depois você vai clicar no botãozinho para fazer a requisição (Execução). E, por fim, você vai analisar tudo aquilo que veio na resposta (status 200? Json contendo determinado dado? Novo registro criado?).

E dito isso, fica o questionamento:

Se você faz tudo isso manualmente para só depois escrever os testes automatizados, isso não seria um retrabalho?

Talvez tudo o que você precise é se forçar a colocar os testes automatizados desde o inicio do seu processo de desenvolvimento, por mais que sejamos constantemente tentados a abrir mão da qualidade (não só em testes) em detrimento de uma falsa sensação de velocidade de desenvolvimento, o que na prática não se concretiza, por conta do retrabalho que mais cedo ou mais tarde acontece. Um exemplo muito comum? Lá vai:

1 - Dev estima tarefa com e sem testes

2 - Dev apresenta essas estimativas ao Product Owner (ou seja lá quem for a pessoa pra quem você estima tarefas)

3 - Há um consenso de que escrever sem testes será mais rápido e que os testes serão escritos posteriormente

4 - A entrega é feita e lançada em produção com uma falsa sensação de rapidez

5 - A entrega resultou em um bug

6 - Para tudo para resolver o bug, dessa vez com muito mais pressão para entregar

7 - Surge o questionamento de quanto tempo levará para corrigir o bug

8 - De volta ao item 1 🤡

Ver os testes como separados da implementação é separar o código da qualidade do código, uma aposta difícil de ganhar, e eu achei importante trazer esse ponto antes de seguirmos com exemplos mais práticos pois, na minha percepção, fazer essa separação é o primeiro passo para ter testes frágeis, dificeis de manter e com pouca ou nenhuma padronização.

Considere que testes e implementação são a mesma coisa e você estará colocando isso em prática mais cedo do que imagina.

Na parte três vamos ver na prática que tão importante quanto saber o que testar é saber o que não testar.

Até lá.

Desafios Comuns na Escrita de Testes Automatizados: Rumo à Clareza e Padronização - Parte 1

Ricardo Silva — Mon, 19 Feb 2024 15:16:26 +0000

Do que é composto um software?

Gosto da premissa de que um software pode ser considerado um conjunto de unidades de código, como objetos, classes, métodos e variáveis, que interagem e se comunicam entre si para realizar determinadas operações.

O que faz um código ser considerado um código de qualidade?

Em poucas palavras, é quando essas unidades de código conseguem existir de forma coesa (onde tudo faz sentido) e desacoplada (quando a alteração de uma unidade não causa a quebra de uma outra unidade).

Nos próximos artigos nós tentaremos entender um pouco mais sobre como os testes automatizados, desde que bem escritos, podem nos ajudar a conseguir colocar em prática os pontos acima.

ps: A ideia aqui não é ensinar os conceitos básicos de testes automatizados, muito menos mergulhar nas sopas de letrinhas do SOLID, BDD, DRY, Design Patterns, pirâmide de testes, etc. Vou evitar até mesmo usar termos como testes de integração e unitários, utilizando sempre o termo “testes automatizados". Embora tudo isso seja levando em conta no conteúdo proposto (até porque nada do que vou passar aqui foi inventado por mim), a ideia principal é estabelecer um ponto de partida para criar testes automatizados que sejam consistentes e que validem de fato o que um software deve fazer.

ps2: Os conceitos e exemplos aqui são agnósticos a tecnologias. Irei utilizar Ruby (com Rails) e RSpec como stack para os exemplos, mas recomendo que tente replica-los na stack que você preferir.

ps3: Como o óbvio também precisa ser dito, objetivo aqui não é determinar a melhor forma de escrever testes e sim tentar estabelecer algumas formas padronizadas de fazer isso.

Nessa primeira parte nós começaremos abordando:

Consequências ao ignorar os testes automatizados
Testes automatizados como documentação

> Consequências ao ignorar os testes automatizados

Algo que vi com certa frequência em boa parte dos projetos em que trabalhei foi a falta de clareza e objetividade na escrita dos testes automatizados. Não raramente, desenvolvedores dos mais diversos níveis de experiência apresentando insegurança a respeito de como escrever testes automatizados para um código que ele mesmo escreveu me faz refletir sobre como algum tipo de padronização de pensamento poderia ajudar na hora de montar esses testes.

Em resumo:

1 - Nenhum desenvolvedor (com o juízo no lugar) questiona a importância de escrever testes.

2 - Muitos desenvolvedores não tem clareza sobre como escrever tais testes.

A falta de clareza sobre como escrever testes leva muitos desenvolvedores a gastar horas tentando reproduzir cenários para validar implementações ou corrigir bugs usando ferramentas como Postman ou o console do framework.

Agora vamos ao nosso primeiro exemplo, já que ninguém é obrigado a acreditar no que eu falo:

Em nosso exemplo, nós temos uma API responsável por publicar artigos, sendo composto pelos seguintes requisitos:

Article pertence à Author e Category, que precisam estar previamente cadastrados
Article possui title e body como atributos
Ao cadastrar um novo artigo, o autor precisará ser notificado que seu artigo já foi publicado
Teremos um Service Object responsável por executar todo esse fluxo

Dito isso, em um cenário onde testes automatizados estão sendo ignorados naquele momento pelo desenvolvedor, ele precisará abrir o console e preparar tudo o que precisa para reproduzir o fluxo de publicação de um artigo:

# primeiro criando um autor
author = Author.create(name: 'John Doe', email: 'john.doe@example.com')

# depois criando uma categoria
category = Category.create(name: 'Technology')

# em seguida montando o hash com os dados de um novo artigo
article_params = {
  title: 'Introduction to Rails',
  body: 'This is the content of the article.',
  author_id: author.id,
  category_id: category.id
}

# e executando o Service Object que irá performar todo o fluxo de criação 
service = ArticleCreationService.new(article_params)
service.call

Quando eu disse que os testes foram ignorados pelo desenvolvedor, eu me referi a duas possibilidades bem comuns:

Os testes não existem e o desenvolvedor optou por escreve-los somente após concluir a implementação em que está trabalhando (lembrando que pode ser um bugfix, refatoração ou algo totalmente novo).
Os testes existem, mas o desenvolvedor não quis abri-los, entende-los e executá-los.

Qualquer uma das opções impactam negativamente em vários aspectos, dos quais nesse momento podemos destacar duas:

Entender o código de um Service Object pode ser demorado, pois o desenvolvedor precisa analisar o código-fonte e as classes relacionadas para compreender completamente o propósito da implementação. Até que ocorram "epifanias" que esclareçam o fluxo da execução, o desenvolvimento pode ser prolongado, especialmente ao lidar com código legado.
A montagem e reprodução do cenário necessário para testes também podem ser morosas. No exemplo fornecido, já foi necessário criar manualmente registros no banco e preparar um hash de dados para um novo artigo. Em um software real com mais complexidade, essa preparação pode envolver várias etapas, com vários possíveis contextos e resultados diferentes, tornando frequentemente necessário o auxílio de um membro experiente da equipe para configurar o ambiente de teste, ao contrário da facilidade proporcionada por comandos que automatizam esse processo.

> Testes automatizados como documentação

Testes automatizados, antes de mais nada, são uma documentação viva do software, servindo de referencia para o entendimento de contextos de cada funcionalidade, contemplando as entradas esperadas, saídas esperadas, mudanças implementadas e a relação entre cada uma das unidades de que compõem de código de um software.

Agora um exemplo de testes que poderiam auxiliar o desenvolvedor nesse primeiro desafio de entender e reproduzir o cenário desejado:

# spec/services/article_creation_service_spec.rb
require 'rails_helper'

RSpec.describe ArticleCreationService, type: :service do
  describe '#call' do
    context 'when passing valid data' do
      it 'creates a new article' do
                author = create(:author)
        category = create(:category)
        article_params = {
          title: 'Test Article',
          body: 'This is a test article.',
          author_id: author.id,
          category_id: category.id
        }

        ArticleCreationService.new(article_params).call

        expect(Article.count).to eq(1)
      end

      it 'enqueues email notification job' do
                author = create(:author)
        category = create(:category)
        article_params = {
          title: 'Test Article',
          body: 'This is a test article.',
          author_id: author.id,
          category_id: category.id
        }

        ArticleCreationService.new(article_params).call

        expect(Sidekiq::Worker.jobs.count).to eq(1)
        expect(Sidekiq::Worker.jobs.first['class']).to eq('ArticleMailer')
      end
    end

    context 'when passing invalid data' do
      it 'does not create a new article' do
                invalid_article_params = {
          title: 'Test Article',
          body: 'This is a test article.',
          author_id: nil,
          category_id: nil
        }

        ArticleCreationService.new(invalid_article_params).call

        expect(Article.count).to eq(0)
      end

      it 'does not enqueue email notification job' do
                invalid_article_params = {
          title: 'Test Article',
          body: 'This is a test article.',
          author_id: nil,
          category_id: nil
        }

        ArticleCreationService.new(invalid_article_params).call

        expect(Sidekiq::Worker.jobs.count).to eq(0)
      end
    end
  end
end

Essa estrutura é focada em três blocos: describes, contexts e its

O bloco describe determina qual a unidade de código está sendo testada, no nosso caso aqui estamos falando do método call. O describe engloba todos os contexts (possível contextos), que por sua vez guardam os its que são as saídas esperadas para essas unidades de código.

O termo “documentação viva” se dá justamente por conta da mensagem que os testes passam, descrevendo o que está sendo testado e qual o comportamento esperado de acordo com cada possível cenário:

**Dada(describe)** a unidade de código ArticleCreationService, 
  **Que contém (describe)** a unidade de código call
    **Quando (context)** forem passados dados válidos
      **Espera-se (it)** que um novo artigo seja criado
      **Espera-se (it)** que um email de notificação seja enfileirado
    **Quando (context)** forem passados dados inválidos
      **Espera-se (it)** que um novo artigo não seja criado
      **Espera-se (it)** que um email de notificação não seja enfileirado

Outro ponto que faz com que testes sejam uma documentação viva é que alterações no código poderão acarretar em quebra dos testes, o que forçará o desenvolvedor a ajustar os testes de acordo com a nova necessidade e por consequência os descritivos de cada bloco.

Por enquanto é isso. Nas próximas continuações (se a procrastinação não me vencer) iremos ver outras abordagens que te ajudarão na hora de escrever testes para suas aplicações.

Até lá.