Um designer relata que a mensagem de erro de um formulário se sobrepõe ao botão de envio. O desenvolvedor abre a mesma página e não vê problema. Ambos usam o mesmo código, mas um deles possui uma janela de visualização estreita, uma interface traduzida e uma mensagem de validação incomumente longa.
A peça que falta é o estado do formulário.
Uma captura de tela registra o que apareceu na tela. Um exemplo reproduzível também preserva as entradas, respostas, permissões e ambiente que o produziu. Essa distinção é importante quando as pessoas revisam o trabalho em momentos diferentes ou ingressam em um projeto sem conhecer suas convenções não documentadas.
Este artigo usa um formulário de convite para espaço de trabalho como exemplo. O formulário aceita um endereço de e-mail e uma função, envia uma solicitação e exibe uma confirmação ou um erro. As sete verificações abaixo transformam seus estados estranhos em algo que desenvolvedores e designers podem inspecionar juntos.
1. Descreva a falha como um estado e um resultado observável
“O formulário parece quebrado” deixa muito para a próxima pessoa descobrir.
Um relatório útil especifica o estado inicial, a ação, o resultado observado e o comportamento esperado:
Starting state:
Invitation form, English locale, 360 CSS-pixel viewport.
The submitted address already belongs to the workspace.
Action:
Submit an invitation with the Viewer role selected.
Response:
HTTP 409 with error code MEMBER_ALREADY_EXISTS.
Observed:
The error message overlaps the Send invitation button.
Expected:
The error wraps within the form.
The button remains visible and operable.
The entered email and role remain available for correction.
Inclua o navegador, a revisão do aplicativo e as permissões de conta relevantes. Explique se “360 pixels” significa a janela de visualização do layout do navegador ou as dimensões de uma captura de tela exportada.
Evite usar endereços reais de clientes em instalações compartilhadas. Um endereço sintético como member@example.test é suficiente para exercitar a interface.
Este relatório fornece ao designer um requisito de layout claro e ao desenvolvedor um estado preciso para recriar.
2. Preservar dados de limites realistas em luminárias
Um formulário testado apenas com envios bem-sucedidos não possui a maior parte de seu comportamento interessante.
Crie um pequeno conjunto de fixtures que cubram as regras reais do produto:
| Calendário | Comportamento a inspecionar |
|---|---|
| Campo obrigatório vazio | O erro identifica o que precisa de correção |
| Membro existente do espaço de trabalho | O feedback do servidor aparece sem perder os dados inseridos |
| Mensagem de erro longa | Quebra de texto sem cobrir controles |
| Permissão removida antes do envio | A IU explica que a ação não está disponível |
| Resposta atrasada | O estado pendente é compreensível |
| Falha na conexão | O usuário pode se recuperar sem uma reinicialização inexplicável |
| Etiquetas traduzidas | Os controles acomodam a expansão do texto |
Mantenha os valores do fixture determinísticos. Endereços aleatórios ou carimbos de data/hora em constante mudança tornam as comparações visuais mais difíceis de interpretar.
Registre os resultados esperados junto com os dados. Uma resposta contendo uma mensagem não estabelece onde a interface deve exibi-la, se o foco deve ser movido ou quais campos devem permanecer editáveis.
Trate isso como decisões de produto e teste-as explicitamente.
3. Separe as entradas dos componentes do comportamento da rede
Algumas falhas podem ser reproduzidas passando props para um componente. Outros dependem do ciclo de vida da solicitação.
Argumentos do livro de histórias pode descrever entradas para estados de componentes isolados. Uma história de estado de erro pode fornecer uma mensagem, valores de campo atuais e um sinalizador pendente para um componente de formulário de apresentação.
Porém, passando pending: true não prova que a aplicação real entra ou sai desse estado corretamente.
Para comportamento dependente da rede, use Trabalhador de serviço simulado ou a interceptação da solicitação do seu executor de teste para fornecer uma resposta controlada. Preserve a distinção entre essas duas verificações:
- Verificação de componentes: O formulário renderiza um erro longo corretamente?
- Verificação de integração: Receber o erro do servidor faz com que esse estado apareça?
Evite simular o mesmo endpoint em várias camadas sobrepostas. Quando uma resposta é inesperada, a equipe deve ser capaz de identificar qual equipamento a produziu.
Mantenha também pelo menos alguma cobertura de integração com a API real. Uma simulação de front-end que retorna uma forma de erro desatualizada pode fazer com que a interface pareça confiável enquanto oculta um contrato quebrado.
4. Depure o layout antes de alterar valores CSS aleatórios
Abra o estado de falha na viewport gravada. Inspecione o contêiner de erros, seu layout pai e o botão de envio.
Procure restrições como alturas fixas, posicionamento absoluto, estouro oculto e um item flexível ou de grade que se recusa a encolher.
Um layout possível para uma mensagem ao lado de uma ação é:
.form-feedback {
display: grid;
grid-template-columns: minmax(0, 1fr) auto;
align-items: start;
gap: 0.75rem;
}
.form-feedback__message {
min-width: 0;
overflow-wrap: anywhere;
}
@media (max-width: 30rem) {
.form-feedback {
grid-template-columns: 1fr;
}
}
Esse padrão permite que a coluna da mensagem diminua e empilhe os elementos em uma largura estreita. Não é uma solução universal: escolha um ponto de interrupção e um arranjo que se adeque à forma circundante.
Se o erro pertencer a um campo específico, colocá-lo ao lado do botão enviar pode ser o design errado, independentemente de quão bem ele seja agrupado.
SitePoints guia de depuração CSS baseado em navegador explica como inspecionar as regras aplicadas e o comportamento do layout. Isso é guia para solucionar problemas de CSS com Inspect Element fornece informações adicionais.
Use experimentos do DevTools para identificar a causa e, em seguida, faça a mudança duradoura na fonte. Verifique posteriormente uma janela de visualização ampla para que uma correção de tela estreita não introduza uma regressão na área de trabalho.
5. Afirme o comportamento antes de comparar as capturas de tela
Uma captura de tela pode mostrar que há um erro. Não pode, por si só, provar que o formulário preservou o endereço de correio eletrónico ou impediu uma navegação não intencional.
O exemplo do Playwright a seguir assume uma rota de aplicativo existente, configurada baseURLe rótulos de formulário acessíveis. Adapte o endpoint, o esquema de resposta e os seletores ao seu projeto.
import { test, expect } from "@playwright/test";
test("keeps invitation details after a duplicate-member error", async ({
page,
}) => {
await page.setViewportSize({ width: 360, height: 800 });
await page.route("**/api/invitations", async (route) => {
if (route.request().method() !== "POST") {
await route.continue();
return;
}
await route.fulfill({
status: 409,
contentType: "application/json",
body: JSON.stringify({
code: "MEMBER_ALREADY_EXISTS",
message: "This person is already a member of this workspace.",
}),
});
});
await page.goto("/settings/invitations");
const form = page.getByRole("form", { name: "Invite a teammate" });
const email = form.getByLabel("Email address", { exact: true });
const role = form.getByLabel("Role", { exact: true });
const submit = form.getByRole("button", {
name: "Send invitation",
exact: true,
});
await email.fill("member@example.test");
await role.selectOption("viewer");
await submit.click();
await expect(form.getByRole("alert")).toContainText(
"already a member"
);
await expect(email).toHaveValue("member@example.test");
await expect(role).toHaveValue("viewer");
await expect(submit).toBeEnabled();
await page.evaluate(() => document.fonts.ready.then(() => undefined));
await expect(form).toHaveScreenshot("duplicate-member-narrow.png", {
animations: "disabled",
});
});
O exemplo espera uma seleção nativa para a função e um marco de formulário nomeado. Um seletor de função personalizado requer interações diferentes.
As afirmações de comportamento precedem a comparação visual. A captura de tela ajuda os revisores a detectar sobreposições, cortes ou alterações de espaçamento não intencionais.
Documentação de comparação visual do dramaturgo explica as capturas de tela básicas. Gere-os e compare-os em um ambiente consistente; diferenças de sistema operacional e fonte podem afetar a renderização.
Revise a primeira linha de base manualmente. Um teste de captura de tela pode preservar fielmente um bug se a imagem inicial for aprovada sem inspeção. Desativar a animação de um instantâneo também não testa a acessibilidade do movimento em si.
6. Torne as instruções de revisão compreensíveis para novos colaboradores
À medida que um projeto cresce, o comportamento de um componente deve permanecer detectável sem uma explicação privada.
A Polónia também se tornou uma escolha popular para empresas que procuram expandir suas equipes de desenvolvimento sem limitar sua busca ao talento local.
O requisito prático para contribuidores distribuídos é um processo de revisão que tenha seu próprio contexto. Anexe o fixture exato, o local de visualização, o comando de reprodução e o comportamento esperado ao problema ou pull request.
Uma nota de revisão útil poderia dizer:
Fixture:
duplicate-member-long-message
Preview:
Open the invitation error story at 360 and 1280 CSS pixels.
Behavior:
Email and selected role remain unchanged after HTTP 409.
The message wraps and does not obscure the submit button.
Review focus:
Check message placement, reading order, and narrow-screen spacing.
Open decision:
Should the duplicate-member error link to the existing member record?
Mantenha a decisão aberta separada do comportamento implementado. Isso evita que os revisores presumam que uma mudança visual já resolveu um problema de produto.
Nomeie a pessoa ou equipe responsável pelo componente e identifique onde as decisões de design são registradas. Um acessório estável só é útil se alguém o mantiver à medida que o componente evolui.
Um formulário que não se sobrepõe mais ainda pode ser difícil de usar.
Verifique rótulos visíveis, navegação pelo teclado, visibilidade do foco e a relação entre erros e seus campos. Para erros em nível de campo, considere aria-invalid e aria-describedby quando apropriado.
O alerta no exemplo de teste pressupõe um erro no nível do formulário recém-exibido. Não adicione diversas regiões ativas concorrentes nem anuncie cada pressionamento de tecla. Confira a experiência resultante com tecnologia assistiva.
SitePoints guia de layout de formulário acessível é um contexto relevante para a relação entre estrutura e usabilidade.
Um conjunto de ferramentas focado pode dar suporte ao fluxo de trabalho:
| Ferramenta | Tarefa útil | O que não estabelece |
|---|---|---|
| Ferramentas de desenvolvimento do navegador | Inspecione estilos computados, overflow, solicitações e foco | Que todos os ambientes suportados se comportem de forma idêntica |
| Livro de histórias | Preservar estados de componentes para revisão compartilhada | Que o aplicativo atinja esses estados corretamente |
| Trabalhador de serviço simulado | Reproduza respostas de sucesso, fracasso e atrasos | Essa produção implementa o contrato simulado |
| Dramaturgo | Afirme o comportamento de interação e compare capturas de tela | Que todos os requisitos de acessibilidade sejam satisfeitos |
| machado DevTools | Detecte alguns problemas de acessibilidade na UI renderizada | Que as verificações automatizadas substituem os testes manuais |
| Verificador de contraste WebAIM | Avalie as cores escolhidas de primeiro plano/fundo | Esse foco, ordem de leitura e texto são utilizáveis |
Use o menor conjunto que responda à pergunta atual. Adicionar outra ferramenta é útil quando preenche uma lacuna de teste, não apenas porque produz outro relatório.
Uma boa transferência permite que alguém não familiarizado com a conversa original recrie a falha, entenda o comportamento esperado e verifique a correção. Quando a verificação de fixação e regressão permanece com o código, esse trabalho continua ajudando o próximo contribuidor.
