Forem: Augusto Hubert

Organizing Tests with Clarity: the Unfolding Tests Technique

Augusto Hubert — Thu, 09 Oct 2025 16:13:43 +0000

[pt-BR] Existe uma versão desse artigo em pt-BR, que você pode acessar aqui

In recent years, much of my work has involved helping teams expand and optimize their automated test suites. And one thing that comes up repeatedly is the same kind of problem: the tests exist, but they are hard to understand.

No one knows exactly what is being tested, where certain scenarios are, or whether the logical branches are truly covered. As a result, you see coverage gaps, redundant tests, and a lot of time wasted trying to understand what already exists.

On many occasions, when pairing with less experienced developers, I notice a recurring pattern: they spend a long time scrolling up and down the test file, looking for code that looks “similar” to what they want to write. The idea is to place the new test “near the other similar ones.” This habit is understandable, but it’s also a symptom of a structural problem: if you need to “guess” where the test should go, the file structure isn’t clear enough.

Over time, I developed a technique that helps me organize and visualize test structures. It’s simple and practical, and it leverages a feature that almost every modern text editor has: code folding.

I call this technique Unfolding Tests.

The examples in this article use Ruby on Rails and RSpec, but the same principles apply to any other testing framework.

The idea behind Unfolding Tests

The idea is to use code block folding as both a reading and writing tool. In VS Code, for example, you can fold and unfold blocks such as describe, context, and it.

To start, use the Fold All command (on macOS: Cmd + Shift + P; on Windows: Ctrl + Shift + P) and type “Fold All.”

This technique is grounded in the idea of reducing cognitive load. When everything is folded, you see only the skeleton of the test, which lets you quickly understand what’s being tested and how the scenarios are organized, without reading the implementation details. That way, the focus becomes the intent, rather than every line of code.

From there, I gradually expand the blocks and come to understand:

What’s being tested (describe)
What the possible scenarios are (context)
What the expectations are in each scenario (it)
And which setups are used at each level

This hierarchical view provides a much clearer reading of the system’s behavior under test. What’s most interesting is that the same process also works when writing tests.

Writing tests

When I start a new test file, I don’t think in lines of code. I think in the structure I want to see when folded.

First, I create the skeleton of the test:

RSpec.describe UserPolicy do
  context 'when user is admin' do
    it 'allows access'
  end

  context 'when user is not admin' do
    it 'denies access'
  end
end

When that file is fully folded, what I see is something like:

UserPolicy
  when user is admin
    allows access
  when user is not admin
    denies access

This is already enough to understand what’s being tested and what the scenarios are.

By the way, this view is very similar to the RSpec output when you use the --format documentation option.

If you’re not using that format yet, you should. It turns test execution into an almost narrative reading, showing exactly what each test describes, in the same hierarchy you defined in the describe, context, and it blocks.

After that, I unfold block by block and fill in the details: setups, mocks, expectations, and so on.

The hierarchy of setups

One of the most important parts of Unfolding Tests is respecting the hierarchy between the blocks and their setups.

Under each describe, there should be a setup with the general prerequisites for all scenarios inside that block.
Under each context, there should be a setup with the prerequisites specific to that scenario. Your setup here must provide the conditions that make the context description true.
The test code itself should always be inside the it block, which is the lowest level in the structure where expectations are verified.

describe 'Listing orders' do
  let(:admin_user) { create(:user, :admin) }

  before do
    sign_in(admin_user)
    visit orders_path
  end

  context 'when there are no orders' do
    before { Order.delete_all } 

    it 'shows the empty state message' do
      expect(page).to have_content('No orders found')
    end
  end

  context 'when there are orders' do
    let!(:orders) { create_list(:order, 2) }

    it 'lists all orders' do
      expect(page)
        .to have_text(orders.first.id)
        .and have_text(orders.second.id)
    end
  end
end

If you fold this file, even without seeing the implementation details, you can understand the purpose of the test, the scenarios it covers, and the expected behavior in each case. Then, when you unfold each block, you reveal the necessary details: first the setup, then the test.

Contexts as logical branches

An important principle of this technique is that each logical branch deserves its own context. If a variable can take three states (for example, full, partial, empty), then you should have three contexts, one for each case.

Example:

context 'when report is full' do
  # ...
end

context 'when report is partial' do
  # ...
end

context 'when report is empty' do
  # ...
end

This helps ensure that the tests truly explore all relevant possibilities.

And more: to me, it doesn’t make sense to have a context without others that represent opposing states. If there’s a context 'when user is admin', there should also be a context 'when user is not admin'. These pairs make it clear that the test covers both sides of the logic, and that’s easy to see when the file is folded.

Why this works

Unfolding Tests turns the act of reading and writing tests into something visual and incremental.
You see the structure before you see the details, which helps you:

Quickly understand the scope of the file
Identify redundancies and gaps
Ensure that each logical path has its counterpart
Write tests that also serve as living documentation

In the end, a good test is also a good form of documentation. And the clearer the intent expressed in the structure, the easier it will be for anyone to understand the expected behavior of the system.

Tips to start applying

Fold everything (Fold All).
Start with the test file completely folded. This gives you a clear overview of the structure, the main blocks, and the existing scenarios.
Unfold gradually.
Expand the outer describe blocks first to understand what’s being tested. Then open the context blocks to see the scenarios, and finally the it blocks to look at the expectations. This gradual progression helps you understand the test layer by layer, without overloading your mind with unnecessary details right away.
Check if the structure makes sense when folded.
If, with everything folded, you can’t tell what the file is testing or which scenarios it covers, that’s a sign the structure needs to be revisited.
When writing new tests, think about the structure first.
Build the skeleton with describe, context, and it before writing any code.
Use context to express logical variations.
Whenever possible, write contexts in pairs — for example, “when user is admin” and “when user is not admin.”
Respect the setup hierarchy.
Place general before and let definitions inside the describe, and specific setups inside each context.
Only then write the test code (it).
Once the structure and prerequisites are clear, add the actual test code.

Unfolding Tests is a simple way to bring clarity and intent to your tests.

It forces you to think about structure before details and to treat each scenario as part of a cohesive whole. In the end, the benefit is twofold: tests become easier to understand, and the code is less likely to get lost among confusing or redundant cases.

If you often get lost in large test files, try folding everything and then unfolding gradually. It’s a very simple technique, yet it’s impressive how much it changes the way you read and write tests.

Organizando testes com clareza: a técnica do Unfolding Tests

Augusto Hubert — Thu, 09 Oct 2025 16:12:50 +0000

[EN] There is a version of this article in english, you can access it here

Nos últimos anos, grande parte do meu trabalho tem sido ajudar times a ampliar e otimizar suas suítes de testes automatizados. E uma coisa que se repete o tempo todo é o mesmo tipo de problema: os testes até existem, mas são difíceis de entender.

Ninguém sabe exatamente o que está sendo testado, onde estão certos cenários ou se as ramificações lógicas estão realmente cobertas. Como resultado, aparecem buracos de cobertura, testes redundantes e muito tempo perdido tentando entender o que já existe.

Em diversas ocasiões, ao parear com desenvolvedores menos experientes, vejo um padrão se repetir: eles passam um bom tempo rolando o arquivo de testes de cima a baixo, procurando por um código “parecido” com o que querem escrever. A ideia é colocar o novo teste “perto dos outros semelhantes”. Esse hábito é compreensível, mas também um sintoma de um problema estrutural: se você precisa "adivinhar" onde o teste deveria estar, é porque a estrutura do arquivo não está clara o suficiente.

Com o tempo, desenvolvi uma técnica que me ajuda bastante a organizar e visualizar a estrutura dos testes. É simples, prática e aproveita um recurso que praticamente todo editor de texto moderno tem: o folding de código.

Eu chamo essa técnica de Unfolding Tests.

Os exemplos que aparecem neste artigo usam Ruby on Rails e RSpec, mas os mesmos princípios se aplicam a qualquer outro framework de testes.

A ideia por trás do Unfolding Tests

A ideia é usar o “folding” de blocos de código como uma ferramenta de leitura e escrita. No VSCode, por exemplo, você pode dobrar (fold) e desdobrar (unfold) blocos de código como describe, context e it.

Para começar, basta usar o comando Fold All (no macOS: Cmd + Shift + P; no Windows: Ctrl + Shift + P) e digitar “Fold All”.

Essa técnica vem muito da ideia de reduzir a carga cognitiva. Quando tudo está dobrado, você vê apenas o esqueleto do teste, o que permite entender rapidamente o que está sendo testado e como os cenários estão organizados, sem precisar ler detalhes de implementação.

Com isso, o foco passa a ser principalmente a INTENÇÃO, e não cada linha de código.

A partir daí, começo a expandir os blocos aos poucos e com isso passo a entender:

O que está sendo testado (describe)
Quais são os cenários possíveis (context)
Quais são as expectativas em cada cenário (it)
E quais setups estão sendo usados em cada camada

Essa visão hierárquica me dá uma leitura muito mais clara do comportamento do sistema testado. E o mais interessante é que o mesmo processo funciona também para escrever testes.

Escrevendo testes com Unfolding Tests

Quando começo um novo arquivo de testes, eu não penso nas linhas de código. Penso na estrutura que quero ver dobrada.

Crio primeiro o esqueleto do teste:

RSpec.describe UserPolicy do
  context 'when user is admin' do
    it 'allows access'
  end

  context 'when user is not admin' do
    it 'denies access'
  end
end

Quando esse arquivo está totalmente dobrado, o que vejo é algo como:

UserPolicy
  when user is admin
    allows access
  when user is not admin
    denies access

Isso já é suficiente para entender o que está sendo testado e quais são os cenários.

Aliás, essa visualização lembra bastante o output do RSpec quando você usa o formato --format documentation.

Se você ainda não está usando esse formato, deveria. Ele transforma a execução dos testes em uma leitura quase narrativa, mostrando exatamente o que cada teste descreve, na mesma hierarquia que você definiu nos blocos describe, context e it.

Depois disso, vou desdobrando bloco por bloco e preenchendo os detalhes: setups, mocks, expectations e assim por diante.

A hierarquia de setups

Uma das partes mais importantes do Unfolding Tests é respeitar a hierarquia entre os blocos e seus setups.

Abaixo de cada describe deve haver um setup com os pré-requisitos gerais para todos os cenários que estão dentro daquele bloco.
Abaixo de cada context deve haver um setup com os pré-requisitos específicos daquele cenário. Aqui seu setup deve prover as condições para que a descrição do seu context seja verdadeira.
E o código do teste em si deve estar sempre dentro do bloco it, que é o nível mais baixo da estrutura, onde as expectativas são verificadas.

describe 'Listing orders' do
  let(:admin_user) { create(:user, :admin) }

  before do
    sign_in(admin_user)
    visit orders_path
  end

  context 'when there are no orders' do
    before { Order.delete_all } 

    it 'shows the empty state message' do
      expect(page).to have_content('No orders found')
    end
  end

  context 'when there are orders' do
    let!(:orders) { create_list(:order, 2) }

    it 'lists all orders' do
      expect(page)
        .to have_text(orders.first.id)
        .and have_text(orders.second.id)
    end
  end
end

Se você dobrar esse arquivo, mesmo sem ver os detalhes de implementação do teste, dá para entender o propósito do teste, os cenários que ele cobre e o comportamento esperado em cada caso. E então, ao desdobrar cada bloco, você revela os detalhes necessários: primeiro o setup, depois o teste.

Contexts como ramificações lógicas

Um princípio importante dessa técnica é que cada ramificação lógica merece o seu próprio context.Se uma variável pode assumir três estados (Ex. full, partial, empty), então você deve ter três contexts, um para cada caso.

Exemplo:

context 'when report is full' do
  # ...
end

context 'when report is partial' do
  # ...
end

context 'when report is empty' do
  # ...
end

Isso ajuda a garantir que os testes realmente explorem todas as possibilidades relevantes.

E mais: para mim, não faz sentido ter um context sem outros que representam outros estados antagonistas. Se existe um context 'when user is admin', então precisa existir outro context 'when user is not admin'. Esses pares deixam claro que o teste cobre ambos os lados da lógica, e isso é fácil de perceber quando o arquivo está dobrado.

Por que isso funciona

O Unfolding Tests transforma o ato de ler e escrever testes em algo visual e incremental.
Você vê a estrutura antes de ver os detalhes, o que ajuda a:

Entender rapidamente o escopo do arquivo
Identificar redundâncias e lacunas
Garantir que cada caminho lógico tem seu par
Escrever testes que também servem como documentação viva

No fim das contas, u*m bom teste é também uma boa forma de documentação*. E quanto mais clara for a intenção expressa na estrutura, mais fácil será para qualquer pessoa entender o comportamento esperado do sistema.

Dicas para começar a aplicar

Dobre tudo (Fold All).
Comece com o arquivo de testes completamente dobrado. Isso te dá uma visão geral da estrutura, dos blocos principais e dos cenários existentes.
Vá desdobrando gradualmente.
Expanda primeiro os blocos describe para entender o que está sendo testado. Depois abra os context para ver os cenários e, por fim, os it para olhar as expectativas. Essa progressão te permite entender o teste camada por camada, sem sobrecarregar a mente com detalhes desnecessários logo de início.
Verifique se a estrutura faz sentido dobrada.
Se, com tudo dobrado, você não consegue entender o que o arquivo testa ou quais cenários cobre, é sinal de que a estrutura precisa ser revista.
Ao escrever novos testes, pense primeiro na estrutura.
Monte o esqueleto com describe, context e it antes de escrever o código.
Use context para expressar variações lógicas.
Sempre que possível, escreva contexts em pares — por exemplo, “when user is admin” e “when user is not admin”.
Respeite a hierarquia dos setups.
Use o before e o let geral dentro do describe, e setups específicos dentro de cada context.
Só então escreva o conteúdo dos testes (it).
Depois que a estrutura e os pré-requisitos estiverem claros, adicione o código do teste em si.

O Unfolding Tests é uma forma simples de trazer clareza e intenção para os testes.

Ele força você a pensar na estrutura antes dos detalhes e a tratar cada cenário como parte de um todo coeso. No fim, o benefício é duplo: os testes ficam mais fáceis de entender e o código fica mais difícil de se perder em meio a casos confusos ou redundantes.

Se você costuma se perder em arquivos grandes de teste, experimente dobrar tudo e ir desdobrando aos poucos. É uma técnica muito simples mas é impressionante como isso muda a maneira de ler e escrever testes.