Introdução
Depois de conversar com as pessoas envolvidas em um projeto, a equipe acumula anotações, pedidos e exemplos. O levantamento de requisitos ajuda a descobrir essas necessidades, mas ainda falta registrá-las de um jeito curto, compreensível e fácil de priorizar.
Histórias de usuário e critérios de aceitação cumprem esse papel. A história diz quem precisa de algo, o quê e por quê. Os critérios dizem, de forma verificável, quando o resultado pode ser considerado pronto. Neste artigo, você vai aprender a escrever os dois e a conectá-los com casos de uso, modelagem e testes.
O que é uma história de usuário?
Uma história de usuário é uma descrição curta de uma necessidade, escrita do ponto de vista de quem vai usar o sistema. Ela não explica como a funcionalidade será construída; explica qual resultado a pessoa espera e qual valor isso traz.
Ela serve para:
- manter o foco no usuário e no benefício, não na tecnologia;
- dividir o trabalho em partes pequenas que podem ser priorizadas;
- abrir conversas entre quem conhece o negócio e quem vai desenvolver;
- servir de base para critérios de aceitação e testes.
Uma história envolve várias pessoas. Quem conhece a necessidade, como usuários e responsáveis pelo produto, ajuda a escrevê-la e priorizá-la. Quem desenvolve e testa faz perguntas, estima o esforço e ajuda a definir os critérios. A história é, antes de tudo, um lembrete de uma conversa, não um documento que substitui essa conversa.
A estrutura “Como, quero, para”
O formato mais conhecido tem três partes:
Como [tipo de usuário], quero [objetivo], para [benefício].
No exemplo educacional deste artigo, um cadastro de membros, a história fica assim:
Como atendente, quero cadastrar os dados de um membro, para manter suas informações organizadas no sistema.
O usuário
“Como atendente” indica quem tem a necessidade. Use um papel, não o nome de uma pessoa, e evite o genérico “como usuário” quando houver papéis diferentes. Uma pessoa atendente e uma pessoa gestora podem precisar de coisas muito diferentes do mesmo sistema.
O objetivo
“Quero cadastrar os dados de um membro” descreve o que a pessoa deseja fazer, com um verbo e um resultado. O objetivo deve caber em uma frase; se precisar de “e” várias vezes, talvez sejam várias histórias.
O benefício
“Para manter suas informações organizadas” explica por que isso importa. O benefício ajuda a priorizar e a escolher soluções: se o objetivo real é organização, talvez uma busca por nome seja tão importante quanto o próprio cadastro.
O que torna uma história clara
Uma boa história pode ser entendida por alguém de fora da conversa original, sem explicações longas. Ela é pequena o bastante para ser feita em pouco tempo, independente o bastante para ser priorizada sozinha e verificável por meio de critérios. Muitas equipes usam o acrônimo INVEST (independente, negociável, valiosa, estimável, pequena e testável) como lembrete dessas qualidades.
Compare: “Como usuário, quero um sistema de cadastro melhor” é vaga. Não diz quem precisa, o que significa “melhor” nem como verificar. Já a história do atendente tem papel, objetivo e benefício definidos.
O que são critérios de aceitação?
Critérios de aceitação são as condições que precisam ser verdadeiras para que a história seja considerada atendida. Eles transformam a intenção da história em regras observáveis.
Eles são importantes porque:
- evitam interpretações diferentes sobre o que é “pronto”;
- revelam cenários de erro antes da implementação;
- orientam o desenvolvimento e a revisão;
- dão origem direta aos testes.
Critérios também podem registrar qualidades esperadas, como tempo de resposta ou controle de acesso. Essa ponte entre comportamento e qualidade é discutida no artigo sobre requisitos funcionais e não funcionais.
O formato “Dado, Quando, Então”
Um formato popular para escrever critérios é Dado / Quando / Então:
- Dado descreve o contexto inicial;
- Quando descreve a ação;
- Então descreve o resultado esperado.
Para a história do atendente, dois critérios seriam:
Cenário de sucesso: Dado que os dados obrigatórios foram preenchidos, quando o atendente confirmar o cadastro, então o sistema deve registrar o cadastro e informar que a operação foi concluída.
Cenário de erro: Dado que um campo obrigatório não foi preenchido, quando o atendente tentar confirmar, então o sistema deve informar que existem dados pendentes.
A tabela abaixo mostra esses e outros exemplos no mesmo formato:
| Cenário | Dado | Quando | Então |
|---|---|---|---|
| Sucesso | os dados obrigatórios foram preenchidos | o atendente confirmar o cadastro | o cadastro é registrado e a conclusão é informada |
| Dado pendente | um campo obrigatório está vazio | o atendente tentar confirmar | o sistema informa quais dados estão pendentes |
| Cancelamento | o atendente começou a preencher o formulário | ele cancelar a operação | nenhum dado é registrado |
Os critérios são educacionais. Quais campos são obrigatórios, por exemplo, é uma decisão que precisa ser tomada com as pessoas envolvidas em cada projeto.
Da necessidade aos critérios de aceitação
Transformar uma necessidade em história e critérios segue um caminho previsível:
- Parta da necessidade real descoberta no levantamento: “as informações dos membros estão espalhadas em planilhas”.
- Identifique quem sente o problema: neste caso, a pessoa atendente.
- Escreva o objetivo com um verbo: cadastrar os dados de um membro.
- Explique o benefício: manter as informações organizadas.
- Pergunte “como saberemos que está pronto?” e escreva o cenário de sucesso.
- Pergunte “o que pode dar errado?” e escreva os cenários de erro relevantes.
- Revise com quem pediu e ajuste até que todos concordem com o significado.
Depois disso, a história segue pela trilha: pode ser detalhada em um caso de uso, modelada em diagramas e verificada por testes.
Requisito, história, caso de uso, critério e teste
Esses conceitos aparecem juntos com frequência, mas não são a mesma coisa:
| Conceito | Pergunta principal | Objetivo |
|---|---|---|
| Requisito | O que o sistema precisa atender? | Registrar uma necessidade, regra ou qualidade esperada. |
| História de usuário | Quem precisa de quê, e por quê? | Expressar uma necessidade do ponto de vista do usuário, de forma curta. |
| Caso de uso | Como o ator interage com o sistema para atingir o objetivo? | Descrever o fluxo principal e os fluxos alternativos. |
| Critério de aceitação | Como saber se a história foi atendida? | Definir condições verificáveis de “pronto”. |
| Caso de teste | Como verificar, na prática, cada condição? | Executar passos com dados concretos e comparar com o resultado esperado. |
O requisito é o conceito mais amplo, estudado pela Engenharia de Requisitos; histórias de usuário são uma das formas de registrá-lo. A história é curta e centrada no valor. O caso de uso é mais detalhado e descreve a interação passo a passo, inclusive alternativas, como mostra o artigo sobre diagrama de casos de uso.
O critério de aceitação diz o que precisa ser verdade; o caso de teste diz como verificar isso com dados e passos concretos. Um único critério, como “informar dados pendentes”, pode gerar vários casos de teste: nome vazio, telefone vazio, ambos vazios.
Quando o fluxo de uma história tem muitas decisões, um diagrama de atividades ajuda a visualizar os caminhos de sucesso e de erro que os critérios descrevem. Os conceitos citados na história, como Membro, podem aparecer depois no diagrama de classes.
Relação entre história e testes
Critérios bem escritos são quase testes prontos. O “Dado” vira a preparação, o “Quando” vira a ação e o “Então” vira a verificação. Por isso, é comum que a mesma frase oriente a pessoa que desenvolve e a pessoa que testa. Os tipos e níveis de teste são explicados em o que são testes de software.
O código abaixo é uma representação didática da regra dos critérios de cadastro. Ele não é uma implementação do SIGM nem de nenhum sistema real; neste exemplo, nome e telefone foram escolhidos como campos obrigatórios apenas para ilustrar.
CAMPOS_OBRIGATORIOS = ["nome", "telefone"]
def campos_pendentes(dados):
pendentes = []
for campo in CAMPOS_OBRIGATORIOS:
if not dados.get(campo, "").strip():
pendentes.append(campo)
return pendentes
def confirmar_cadastro(dados, cadastros):
pendentes = campos_pendentes(dados)
if pendentes:
return "Existem dados pendentes: " + ", ".join(pendentes)
cadastros.append(dados)
return "Cadastro concluído."
# Verificações ligadas aos critérios de aceitação
cadastros = []
sucesso = confirmar_cadastro({"nome": "Maria Silva", "telefone": "(11) 99999-0000"}, cadastros)
assert sucesso == "Cadastro concluído."
assert len(cadastros) == 1
erro = confirmar_cadastro({"nome": "João Souza", "telefone": ""}, cadastros)
assert "pendentes" in erro
assert len(cadastros) == 1 # nada novo foi registrado
print("Critérios verificados.")A função campos_pendentes() confere se os dados obrigatórios foram preenchidos. A função confirmar_cadastro() segue os dois critérios: se houver pendências, informa quais são e não registra nada; se não houver, registra e informa a conclusão. As linhas com assert funcionam como testes simples: a primeira dupla verifica o cenário de sucesso, e a segunda verifica o cenário de erro, incluindo a garantia de que nenhum cadastro novo foi criado.
Erros comuns e como melhorar
- Escrever como especificação técnica: “como sistema, quero uma tabela com cinco colunas” não é uma história. Volte ao usuário e ao resultado que ele espera.
- Usuário indefinido: “como usuário” esconde diferenças entre papéis. Nomeie o papel, como atendente ou gestor.
- Benefício ausente: sem o “para”, fica difícil priorizar. Pergunte “por que isso importa?” até chegar a um valor real.
- Vários objetivos em uma história: “cadastrar, editar e excluir membros” são três histórias. Divida-as.
- Critérios vagos: “o cadastro deve ser fácil” não pode ser verificado. Descreva um comportamento observável.
- Critérios impossíveis de verificar: “o sistema nunca pode falhar” não tem teste possível. Defina condições concretas e mensuráveis.
- Confundir critério com caso de teste: o critério diz o que deve ser verdade; os dados e passos específicos pertencem ao caso de teste.
- Critérios desconectados da história: uma regra sobre relatórios não pertence à história de cadastro. Mova-a para a história certa.
Checklist para revisar uma história
- O usuário está claro?
- O objetivo está claro e é único?
- O benefício está claro?
- A história pode ser compreendida sem contexto excessivo?
- Os critérios são verificáveis?
- Existem cenários positivos?
- Existem cenários de erro, quando necessários?
- Todos os critérios estão relacionados à história?
Se alguma resposta for “não”, ajuste antes de levar a história para desenvolvimento.
Resumo
Uma história de usuário descreve, em uma frase, quem precisa de algo, o quê e por quê, no formato “Como, quero, para”. Critérios de aceitação definem as condições verificáveis para considerar a história atendida, muitas vezes no formato “Dado, Quando, Então”.
Juntos, eles fazem a ponte entre o levantamento de requisitos e o restante da trilha: casos de uso detalham o fluxo, diagramas modelam a solução e testes verificam cada critério. Comece com histórias pequenas, sempre com cenários de sucesso e de erro, e revise-as com quem conhece o problema.