Como Validar Respostas de API em Testes Playwright

Seus testes Playwright são aprovados. O botão de login é clicado, o painel é renderizado, o gráfico é exibido. Então um cliente relata um bug: os números do gráfico estão errados. Você investiga e descobre que a API retornou um status 200 com um payload malformado, e sua suíte end-to-end nunca percebeu porque apenas verificou que os pixels apareciam na tela. Essa é a lacuna que os testes de navegador sozinhos não conseguem preencher, e é onde as asserções de API se tornam inegociáveis. Ferramentas como o Apidog oferecem uma maneira de validar contratos de API, esquemas e semântica de resposta com o mesmo rigor que você dedica aos seus fluxos de UI, e então executar ambas as suítes juntas na CI.

TL;DR

Você pode validar APIs em testes Playwright combinando o request fixture e o interceptor page.route do Playwright com cenários Apidog que usam a mesma especificação OpenAPI. Compartilhe os fixtures através de um único arquivo de especificação, valide os esquemas de resposta em ambas as camadas e execute as duas suítes em um único job de CI para que uma mudança de contrato falhe rapidamente em qualquer um dos lados.

Introdução

Playwright é o framework de automação de navegador padrão para muitas equipes em 2026, e a documentação do Playwright faz com que o teste de API pareça fácil: algumas chamadas request.get, um expect(response.status()).toBe(200), e pronto. O problema começa quando você escala isso. Você acaba com centenas de testes que verificam códigos de status, mas não a forma da resposta, nenhuma fonte de verdade compartilhada entre seus fluxos de navegador e seus fluxos de API, e nenhuma maneira de simular APIs offline quando o backend está lento ou quebrado.

A solução é direta. Trate sua especificação OpenAPI como o contrato, guie as chamadas request do Playwright e os interceptores page.route a partir desse contrato, e execute uma suíte de cenários Apidog contra a mesma especificação para validação aprofundada de esquema, lógica de negócios e requisições encadeadas. Você obtém feedback rápido na CI, limites claros de propriedade entre testes de frontend e backend, e zero fixtures duplicados. Se você quiser instalar a ferramenta primeiro, Baixe o Apidog e volte; os passos abaixo assumem que ele está disponível localmente.

Aqui está o que você obterá deste post: um modelo mental claro de onde as asserções de API se encaixam em uma suíte Playwright, um padrão request.fixture funcional, uma configuração passo a passo para compartilhar fixtures entre Playwright e Apidog, dicas avançadas para CI e mocking, e uma tabela de comparação das principais alternativas. Para um contexto mais amplo sobre escolhas de ferramentas de teste, veja nossa visão sobre ferramentas de teste de API para engenheiros de QA.

A lacuna entre os testes Playwright e as asserções de API

Um teste Playwright típico faz login, navega para uma página e afirma que algum elemento da UI está visível. Isso diz que o fluxo visível para o usuário funciona. Não diz nada sobre a API por trás dele. Três modos de falha passam despercebidos:

Primeiro, regressões na forma do payload. O endpoint retorna 200 com um campo renomeado de total_count para totalCount. A UI pode converter silenciosamente ou exibir zero. Seu teste Playwright vê um número na tela e passa.

Segundo, desvio da lógica de negócios. Um endpoint de desconto aplica um reembolso de 10 por cento em vez dos 15 por cento contratados. A UI mostra o que a API retorna, então o teste passa. Apenas a equipe financeira percebe, semanas depois.

Terceiro, cobertura de caminhos de erro. Os testes Playwright quase sempre executam o caminho feliz. Sua API tem dezenas de branches 4xx e 5xx: limites de taxa, tokens expirados, falhas parciais, conflitos de idempotência. Nenhum deles é exercitado a menos que você escreva uma suíte de testes de API separada.

Você pode corrigir parte disso adicionando chamadas request.get dentro de suas especificações Playwright e afirmando os corpos de resposta. Isso funciona para alguns endpoints. Falha quando você tem 200 endpoints e deseja cenários encadeados como "criar pedido, buscar pedido, cancelar pedido, verificar webhook de reembolso". Playwright é um framework de automação de navegador em primeiro lugar; ele não foi construído para fluxos de trabalho de API com estado ou ergonomia de asserção em nível de esquema. É aí que uma ferramenta de teste de API dedicada se torna valiosa.

A divisão correta é:

• Testes Playwright verificam fluxos de UI, interceptação de rede e uma fina camada de smoke checks de API no limite de uma ação do usuário.
• Cenários Apidog verificam conformidade de esquema, fluxos de trabalho de API encadeados, conformidade de contrato e caminhos de erro em profundidade.

Ambas as suítes consomem a mesma especificação OpenAPI para que você nunca tenha duas versões da verdade. Para uma visão mais aprofundada da abordagem contract-first, nosso artigo sobre fluxos de trabalho de API design-first mostra o padrão que o envolve.

Como compartilhar fixtures entre Playwright e Apidog

A única fonte de verdade é sua especificação OpenAPI, geralmente openapi.yaml ou openapi.json na raiz do repositório. O Playwright a lê para ajudantes de requisição tipados e payloads de exemplo; o Apidog a importa diretamente para preencher os passos do cenário. Sempre que o backend lança uma mudança de contrato, ambas as suítes a detectam.

Comece com uma pasta fixtures/ que contém dados de teste reutilizáveis: usuários, tokens, payloads de amostra. Crie um arquivo de fixture do Playwright que carregue esses dados e os exponha aos testes:

// tests/fixtures/api.ts
import { test as base, APIRequestContext, expect } from '@playwright/test';
import { readFileSync } from 'fs';
import path from 'path';

type ApiFixtures = {
  apiRequest: APIRequestContext;
  authToken: string;
  sampleOrder: Record<string, unknown>;
};

export const test = base.extend<ApiFixtures>({
  apiRequest: async ({ playwright }, use) => {
    const ctx = await playwright.request.newContext({
      baseURL: process.env.API_BASE_URL ?? 'https://api.staging.example.com',
      extraHTTPHeaders: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
      },
    });
    await use(ctx);
    await ctx.dispose();
  },

  authToken: async ({ apiRequest }, use) => {
    const res = await apiRequest.post('/auth/token', {
      data: { email: 'qa@example.com', password: process.env.QA_PASSWORD },
    });
    expect(res.status()).toBe(200);
    const body = await res.json();
    await use(body.access_token);
  },

  sampleOrder: async ({}, use) => {
    const raw = readFileSync(
      path.join(__dirname, '..', '..', 'fixtures', 'order.json'),
      'utf8',
    );
    await use(JSON.parse(raw));
  },
});

export { expect };

Agora você importa test deste arquivo de fixture em vez de @playwright/test em cada especificação, e você tem um apiRequest tipado, um authToken novo e dados sampleOrder prontos para uso. O arquivo order.json é o mesmo payload que o Apidog usa como corpo de exemplo para POST /orders em seus cenários. Edite-o uma vez, e ambas as suítes mudam.

Para o lado do Apidog, abra o projeto, clique em “Importar” e aponte-o para o mesmo openapi.yaml. O Apidog gera endpoints, exemplos de requisição e esquemas de parâmetros em segundos. Em seguida, salve seus payloads de fixture como “Variáveis de Ambiente” ou “Conjuntos de Dados” do Apidog:

// tests/orders.spec.ts
import { test, expect } from './fixtures/api';

test('POST /orders returns a valid order with 15 percent discount', async ({
  apiRequest,
  authToken,
  sampleOrder,
}) => {
  const res = await apiRequest.post('/orders', {
    headers: { Authorization: `Bearer ${authToken}` },
    data: { ...sampleOrder, coupon: 'SAVE15' },
  });

  expect(res.status()).toBe(201);
  const body = await res.json();

  expect(body).toMatchObject({
    id: expect.any(String),
    status: 'pending',
    discount_pct: 15,
    total_cents: expect.any(Number),
  });
  expect(body.total_cents).toBeLessThan(sampleOrder.subtotal_cents);
});

Dentro do Apidog, o passo do cenário correspondente envia o mesmo payload e, em seguida, executa a verificação de JSON Schema integrada contra o componente Order em openapi.yaml. Isso oferece profundidade: cada campo é verificado quanto ao tipo, campos obrigatórios são validados, valores de enumeração são impostos. O Playwright captura a asserção semântica de alto valor (discount_pct: 15); o Apidog captura cada campo que se desvia, mesmo aqueles que você esqueceu de afirmar manualmente. Se você é novo em testes orientados por especificação, nossa explanação sobre fluxos de trabalho de API design-first mostra o padrão circundante.

Para equipes que já usam Postman e estão considerando uma mudança, alternativas auto-hospedadas ao Postman abordam a mecânica da migração.

Configurar o fluxo de trabalho Apidog + Playwright

Aqui está uma configuração limpa e repetível que o leva de zero a CI de suíte dupla em cerca de uma hora.

Passo 1: Uma única especificação para governar todas. Coloque openapi.yaml na raiz do repositório. Trate-o como código: revisões de PR necessárias, mudanças que quebram a compatibilidade exigem um aumento de versão principal. Se você ainda não tem uma, gere um rascunho de suas rotas existentes usando um plugin de framework (FastAPI, NestJS e outros emitem OpenAPI nativamente), então edite-o manualmente. O Apidog também pode fazer engenharia reversa de uma especificação a partir do tráfego se você importar um arquivo HAR.

Passo 2: Conectar o Playwright. Instale o Playwright (npm init playwright@latest) e adicione o arquivo de fixture mostrado acima. Adicione um script npm run test:e2e e um playwright.config.ts que aponte para seu ambiente de staging. Mantenha os testes pequenos; um cenário por especificação.

Passo 3: Adicionar a camada de cenário Apidog. Dentro do seu projeto Apidog, importe openapi.yaml e, em seguida, construa um cenário por jornada crítica do usuário: cadastro, checkout, reembolso, entrega de webhook, e assim por diante. Cada cenário é uma sequência de chamadas de API com asserções encadeadas. O Apidog suporta variáveis de ambiente, scripts de pré-requisição e asserções de pós-resposta. Exporte o cenário como um JSON executável por CLI via Apidog CLI (apidog-cli run scenario.json).

Passo 4: Interceptação de rede no Playwright. Quando a UI busca dados que você não quer que sejam reais, use page.route para interceptar e simular. As respostas simuladas vêm dos mesmos arquivos de fixture, então o contrato permanece consistente:

test('dashboard renders cached order list when offline', async ({
  page,
  sampleOrder,
}) => {
  await page.route('**/api/orders', async (route) => {
    await route.fulfill({
      status: 200,
      contentType: 'application/json',
      body: JSON.stringify({ orders: [sampleOrder] }),
    });
  });

  await page.goto('/dashboard');
  await expect(page.getByTestId('order-row')).toHaveCount(1);
});

Então, no Apidog, execute o mesmo cenário GET /orders contra seu backend real ou contra um servidor mock do Apidog. Mesmo fixture, duas camadas de verificação.

Passo 5: Integração com CI. Adicione um fluxo de trabalho do GitHub Actions que execute ambas as suítes em paralelo:

name: tests
on: [push, pull_request]
jobs:
  playwright:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx playwright test
  apidog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm i -g apidog-cli
      - run: apidog-cli run ./apidog/scenarios/checkout.json --reporters cli,junit

A falha em qualquer um dos jobs bloqueia o merge. Use --reporters junit para que o GitHub anote as asserções falhas diretamente no PR. A documentação do GitHub Actions aborda builds em matriz e caching se você quiser escalar isso. Para equipes sem uma função de QA dedicada, a explanação da ferramenta de teste de API para engenheiros de QA explica como atribuir a propriedade de cada suíte.

Passo 6: Detecção de desvio. Agende um job diário que compare seu openapi.yaml ativo com a versão usada na última execução de seus testes. Se um campo mudou de tipo, a diferença falha o build antes que qualquer teste seja executado. Isso pega a classe de bug "200 OK com payload errado" que abordamos no início.

Técnicas avançadas e dicas profissionais

Alguns movimentos que valem a pena depois que a configuração básica está funcionando.

Fixar o visualizador de rastreamento do Playwright. Defina trace: 'on-first-retry' em playwright.config.ts. Quando um teste instável falha na CI, você obtém uma linha do tempo completa de chamadas de rede, snapshots do DOM e logs do console. Combine isso com apidog-cli --report html para o lado da API. Juntos, eles mostram se a UI quebrou primeiro ou se a API se desviou.

Use servidores mock do Apidog para execuções offline. O Apidog pode iniciar um servidor mock a partir de sua especificação OpenAPI com um clique. Aponte seu ambiente de desenvolvimento local para ele quando a equipe de backend estiver no meio de um deploy ou o banco de dados de staging estiver sendo redefinido. Sua suíte Playwright roda sem problemas contra o mock, e seus cenários Apidog verificam o backend real em paralelo. Para mais informações sobre este padrão, veja nossa análise sobre geração de testes de API assistida por IA, onde os mocks são centrais.

Limite as contagens de repetição a dois. retries: 2 em playwright.config.ts. Se um teste precisa de três repetições para passar, ele é instável e você tem um problema real. Não o encubra com retries: 5. O mesmo vale para os cenários do Apidog: defina retry: 1 por requisição, no máximo.

Falha fechada no desvio de esquema. Quando o Apidog detecta uma incompatibilidade de esquema, saia com código de erro diferente de zero por padrão. Não deixe um aviso passar despercebido. Se você precisar permitir uma janela de falha suave, proteja-a atrás de uma variável de ambiente como ALLOW_SCHEMA_DRIFT=true e exija um comentário no PR explicando o porquê.

Marque os testes por prioridade. Use test.describe.configure({ mode: 'serial' }) do Playwright para fluxos com estado e marque outros com @smoke, @regression, @nightly. Execute os smoke tests em cada push, os testes de regressão em PRs para a branch principal, e os testes noturnos em toda a suíte de cenários do Apidog. Isso economiza minutos de CI sem perder cobertura.

Erros comuns a evitar:

• Afirmar apenas status === 200. Adicione pelo menos uma verificação de campo do corpo.
• Hardcoding de tokens de portador em fixtures. Use um beforeAll para buscar tokens novos.
• Deixar Playwright e Apidog importarem arquivos de fixture diferentes. Uma fonte, ponto final.
• Pular o Apidog CLI na CI porque “a ferramenta de UI é boa o suficiente.” Não é; o CLI é o que falha o build.
• Tratar os stubs page.route como substituto para testes de API reais. Eles são para isolamento, não cobertura.

Para equipes que geram testes com IA, o guia como testar APIs de agentes de IA aborda os casos não determinísticos que exigem atenção extra.

Alternativas e comparação de ferramentas

Várias combinações de ferramentas podem validar APIs juntamente com testes de navegador. Veja como as principais opções se comparam.

Se você vem de ferramentas mais antigas da era SOAP, nossos artigos sobre alternativas ao script Groovy do SoapUI e alternativas ao ReadyAPI cobrem o caminho de migração. Para fluxos de trabalho local-first, extensões de cliente REST para VSCode vale a leitura.

O pareamento Playwright + Apidog é vencedor para equipes que possuem uma especificação OpenAPI, entregam múltiplos serviços e desejam um único pipeline de CI que capture regressões de UI e API sem pagar por duas licenças SaaS por engenheiro.

Casos de uso no mundo real

Checkout de e-commerce. Uma equipe de varejo executa testes Playwright para o fluxo do carrinho até a confirmação e cenários Apidog para a cadeia de API de intenção de pagamento, verificação de fraude e decremento de estoque. Quando o gateway de pagamento mudou um campo de resposta de error_code para errorCode, o Apidog o detectou em 90 segundos; o Playwright teria mostrado uma tela genérica de “checkout falhou” e levado horas para triar.

Painel SaaS com dados de gráfico. Um produto de análise B2B valida a renderização da UI com snapshots do Playwright e usa o Apidog para afirmar que os endpoints de agregação retornam somas, percentis e séries agrupadas por tempo corretos. Um bug em que o endpoint de latência p99 silenciosamente descartava outliers foi pego na camada da API; o gráfico parecia normal.

Fluxo de trabalho baseado em webhook. Uma equipe de fintech usa Playwright para o portal voltado para o usuário e cenários Apidog para entrega de webhook, lógica de repetição e idempotência. O script do Apidog verifica se IDs de webhook duplicadas são rejeitadas, se as assinaturas são válidas e se a janela de consistência eventual está abaixo de 30 segundos.

Conclusão

Playwright é excelente para fluxos de navegador. Não é construído para testes de API profundos. Combiná-lo com Apidog oferece:

• Uma especificação OpenAPI como contrato entre ambas as suítes.
• Fixtures compartilhados para que os dados de teste nunca se desviem.
• Validação em nível de esquema em cada endpoint, além dos códigos de status.
• Servidores mock para desenvolvimento offline.
• Um único pipeline de CI que falha em regressões de UI ou API.
• Interceptação de rede no Playwright, cadeias de cenário profundas no Apidog.
• Propriedade clara: engenheiros de UI são responsáveis pelas especificações Playwright, engenheiros de API são responsáveis pelos cenários Apidog.

Comece com uma jornada crítica, como checkout ou cadastro. Conecte o fixture do Playwright, construa o cenário Apidog correspondente, execute ambos na CI. Expanda a partir daí. Baixe o Apidog, importe sua especificação OpenAPI e você poderá ter o primeiro cenário rodando hoje.

FAQ

Posso validar APIs em testes Playwright sem Apidog? Sim, usando o request fixture do Playwright e chamadas expect manuais. Você cobrirá códigos de status e alguns campos do corpo. Para validação de esquema, cenários encadeados, mocks e cobertura de caminhos de erro em escala, uma ferramenta dedicada como o Apidog é mais rápida e produz menos falsos positivos. Veja nossa ferramenta de teste de API para engenheiros de QA para as compensações.

Preciso de uma especificação OpenAPI para usar esta configuração? Você precisa de uma para obter o benefício completo. Sem uma especificação, você ainda pode executar Playwright e Apidog lado a lado, mas perde a fonte de verdade compartilhada e terá que manter payloads de exemplo em dois lugares. Gerar uma especificação a partir de rotas existentes leva um ou dois dias.

Como lido com a autenticação em ambas as ferramentas? Use um passo beforeAll que busca um token novo do seu endpoint de autenticação, então armazene-o em um fixture do Playwright e em uma variável de ambiente do Apidog. Gire os tokens por execução de teste para que tokens obsoletos nunca causem instabilidades.

Os cenários Apidog podem substituir o Playwright completamente? Não. O Apidog é excelente para fluxos de trabalho de API, mas não renderiza navegadores. Para asserções de UI (texto visível, layout, fluxos de clique) você ainda precisa do Playwright. As duas ferramentas cobrem superfícies diferentes.

E se meu backend não tiver um ambiente de staging estável? Use o servidor mock integrado do Apidog. Ele inicia um mock com estado a partir de sua especificação OpenAPI com um clique, retornando respostas de exemplo definidas na especificação. Sua suíte Playwright e os cenários Apidog rodam sem problemas contra o mock, e você volta para o backend real quando o staging estiver saudável.

Como mantenho a CI rápida à medida que a suíte cresce? Marque os testes por prioridade e execute apenas @smoke em cada push. Execute a suíte completa de regressão e cenários Apidog em PRs para a branch principal e em uma programação noturna. Paralelize o Playwright com workers: 4 e os cenários Apidog com a flag --parallel do CLI.

Preciso de um plano pago do Apidog para CI? O Apidog CLI executa localmente e na CI sem licenciamento por usuário para execução de cenários. Verifique a página de preços atual antes de adotar em escala. O nível gratuito cobre a maioria das pequenas equipes.