Você tem um endpoint GraphQL e precisa saber se ele funciona. Não "o servidor está funcionando", mas a coisa real: a consulta user retorna os campos que seu aplicativo lê, uma mutação createOrder realmente persiste um pedido e as formas se mantêm quando você muda uma variável. Uma ferramenta REST que só conhece chamadas de caminho e verbo torna isso complicado. GraphQL envia tudo para uma única URL como um corpo POST, então você precisa de um cliente que entenda a própria linguagem de consulta, ofereça sugestões de campo e permita que você faça asserções no JSON que retorna.
Apidog trata GraphQL como um tipo de requisição de primeira classe, ao lado de HTTP, gRPC, WebSocket, SSE e SOAP. Este guia descreve a construção de uma requisição GraphQL do zero: escrever uma consulta, buscar o esquema para autocompletar código, passar variáveis, executar uma mutação e fazer asserções na resposta. O exemplo em execução é uma API de e-commerce onde você consulta um usuário e seus pedidos, e então cria um novo pedido. Se você deseja o contexto conceitual sobre por que GraphQL envia uma única consulta tipada em vez de muitos endpoints, a documentação oficial do GraphQL é a referência canônica, e nossa comparação de REST vs GraphQL aborda quando cada um se encaixa.
O que você está testando e por que GraphQL é diferente
REST oferece muitos endpoints, cada um retornando uma forma fixa. GraphQL oferece um único endpoint e permite que o chamador peça exatamente os campos que deseja. Essa flexibilidade é o objetivo principal, e também é o que faz o teste parecer diferente.
Duas coisas mudam. Primeiro, a requisição é um documento de consulta no corpo, não uma URL que você varia. Um GET /users/42 se torna uma seleção user(id: 42) { ... } enviada por POST. Segundo, GraphQL quase nunca retorna um status não-200 para um erro de negócio. Uma consulta falha ainda retorna 200 OK com um array errors no JSON. Portanto, verificar o código de status não é suficiente. Você precisa ler o corpo. Esse único fato molda como você fará asserções mais adiante neste guia.
Apidog oferece um tipo de corpo GraphQL dedicado, autocompletar código ciente do esquema, variáveis para consultas reutilizáveis e as mesmas ferramentas de asserção e cenário de teste que você usaria para REST. Você projeta e executa a requisição no aplicativo e depois a salva em um cenário que pode ser executado novamente. Vamos construir um.
Criar uma requisição GraphQL no Apidog
Primeiro, Baixe o Apidog ou abra-o no seu navegador, depois abra seu projeto. Se você estiver começando do zero, crie um projeto para que a requisição tenha onde viver.
Passo 1: crie uma nova requisição e mude o corpo para GraphQL
Clique no botão + e escolha New Request (Nova Requisição). Isso abre o construtor de requisições padrão, o mesmo que você usaria para uma chamada REST: método, URL, parâmetros e Authorization.
Defina o método como POST e cole seu endpoint GraphQL na barra de URL. Um típico se parece com isto:
https://api.yourstore.com/graphql
Agora, diga ao Apidog que esta é uma requisição GraphQL. Na área do corpo da requisição, clique em Body, então selecione GraphQL. O editor de corpo muda para uma visualização consciente de GraphQL com uma caixa Query, que é onde a linguagem de consulta reside.
Se seu endpoint precisar de um token, abra a seção Authorization e adicione-o lá, por exemplo, um token Bearer. A autenticação em uma requisição GraphQL funciona da mesma forma que qualquer outra requisição HTTP no Apidog, porque, por baixo dos panos, ainda é um POST HTTP.
Passo 2: escreva sua primeira consulta
Na aba Run, digite sua consulta na caixa Query. Comece com algo concreto. Aqui você quer um usuário e os pedidos anexados a ele:
query GetUserWithOrders {
user(id: "usr_1024") {
id
name
email
orders {
id
total
status
createdAt
}
}
}
Isso pede um usuário e uma lista aninhada de seus pedidos. Os nomes dos campos devem corresponder exatamente ao esquema do seu servidor. Se seu esquema o chama de emailAddress em vez de email, esta consulta falha. Esse é o trabalho do próximo passo para evitar.
Passo 3: busque o esquema para autocompletar código
Adivinhar nomes de campos é onde o teste de GraphQL fica lento. O Apidog pode ler seu esquema para que o editor sugira campos e tipos válidos enquanto você digita, em vez de você ter que verificar um documento em outra aba.
Esta é uma ação manual e sob demanda. Clique no botão Fetch Schema (Buscar Esquema) na caixa de entrada. O Apidog executa uma consulta de introspecção contra seu endpoint e puxa o sistema de tipos. Assim que for bem-sucedido, o autocompletar código é ativado: comece a digitar um campo dentro de uma seleção e você receberá sugestões no estilo IntelliSense para o que realmente está disponível naquele tipo.
Duas coisas importantes a saber. O autocompletar código não é automático; ele só é ativado depois que você clica em Fetch Schema. E se seu endpoint tiver a introspecção desabilitada (alguns servidores de produção fazem isso por segurança), a busca não retornará um esquema, então você terá que escrever os campos manualmente com base em sua própria documentação. Se a busca funcionar, refaça-a após qualquer alteração no esquema para que as sugestões permaneçam atualizadas.
Passo 4: execute e leia a resposta
Clique em Send (Enviar). A resposta aparece na metade inferior da interface. Um resultado saudável se parece com isto:
{
"data": {
"user": {
"id": "usr_1024",
"name": "Dana Whitfield",
"email": "dana@example.com",
"orders": [
{ "id": "ord_5001", "total": 89.90, "status": "SHIPPED", "createdAt": "2026-07-01T09:14:00Z" },
{ "id": "ord_5002", "total": 12.50, "status": "PENDING", "createdAt": "2026-07-12T16:03:00Z" }
]
}
}
}
Observe a chave data de nível superior. Cada resposta GraphQL aninha seu resultado sob data, e quaisquer problemas aparecem em um array errors irmão. Mantenha essa estrutura em mente, porque suas asserções apontarão para data.user..., e não para a raiz.
Passe variáveis para tornar a requisição reutilizável
Codificar "usr_1024" na consulta funciona uma vez. Para uma requisição que você irá executar novamente para vários usuários e ambientes, mova esse valor para uma variável. GraphQL tem uma sintaxe de variável de primeira classe para isso, e o Apidog a suporta. A sintaxe em si é GraphQL padrão, não uma invenção do Apidog, então a documentação oficial do GraphQL sobre variáveis é a fonte da verdade.
Declare a variável na assinatura da consulta com um prefixo $ e um tipo, então use-a nos argumentos:
query GetUserWithOrders($userId: ID!) {
user(id: $userId) {
id
name
orders {
id
total
status
}
}
}
Em seguida, forneça o valor como um pequeno objeto JSON de variáveis:
{
"userId": "usr_1024"
}
Agora a mesma consulta é executada para qualquer usuário alterando um valor JSON. Combine isso com as variáveis de ambiente do Apidog e você pode apontar a requisição idêntica para o ambiente de staging e produção sem editar a consulta. É isso que transforma uma chamada única em algo que você pode salvar, compartilhar e executar em um conjunto.
Escreva uma mutação para criar um pedido
Uma mutação altera dados. No GraphQL, não há protocolo ou UI separado para isso; uma mutação é escrita como GraphQL na mesma caixa Query, com a palavra-chave mutation em vez de query. Assim, o fluxo de trabalho que você já conhece se aplica diretamente.
Aqui você cria um pedido para o usuário que consultou anteriormente:
mutation CreateOrder($input: CreateOrderInput!) {
createOrder(input: $input) {
id
total
status
createdAt
}
}
As variáveis carregam o payload:
{
"input": {
"userId": "usr_1024",
"items": [
{ "sku": "TSHIRT-BLK-M", "quantity": 2 },
{ "sku": "MUG-CERAMIC", "quantity": 1 }
],
"currency": "USD"
}
}
Clique em Send (Enviar). Uma boa resposta ecoa o pedido criado:
{
"data": {
"createOrder": {
"id": "ord_5003",
"total": 42.30,
"status": "PENDING",
"createdAt": "2026-07-15T10:22:11Z"
}
}
}
Como as mutações escrevem dados reais, execute-as em um ambiente de teste ou staging, não em produção. Um padrão comum é executar a mutação, capturar o id retornado, então executar sua consulta GetUserWithOrders novamente e confirmar que o novo pedido aparece na lista. Esse ciclo de consulta-mutação-consulta é uma verificação de ponta a ponta realista, e é exatamente o tipo de coisa que você vai querer salvar como um cenário na próxima seção.
Faça asserções na resposta em vez de apenas inspecioná-la visualmente
Ler JSON manualmente é bom enquanto você explora. Para um teste que é executado sem supervisão, você precisa de asserções que passem ou falhem por conta própria. O Apidog permite adicionar asserções a uma requisição para que uma execução seja julgada automaticamente, o que você configura em asserções de API.
Para GraphQL, três verificações cobrem a maioria dos casos:
- Verifique se o status HTTP é
200. Necessário, mas não suficiente, já que GraphQL retorna 200 mesmo em erros de negócio. - Verifique se o campo
errorsestá ausente. Esta é a verdadeira porta de passagem ou falha do GraphQL. Seerrorsexistir, a operação falhou, não importa o que o status diga. - Verifique valores específicos dentro de
data, usando um JSONPath como$.data.createOrder.statusigual aPENDING, ou$.data.user.orderstem um comprimento maior que zero.
Essa combinação captura os modos de falha que uma verificação apenas de status perde: uma consulta que retorna 200 com um array errors, ou uma que é bem-sucedida, mas retorna a forma errada. Aponte suas asserções de valor para o caminho aninhado sob data, correspondendo à estrutura da resposta que você viu anteriormente.
Salve-o em um cenário de teste
Uma única requisição assertiva é um bom teste de fumaça. O verdadeiro ganho é encadear requisições em um cenário: consultar o usuário, criar um pedido e depois consultar novamente para confirmar que ele foi persistido. Os cenários de teste do Apidog permitem sequenciar essas etapas, passar dados entre elas (capturar o id da mutação, alimentá-lo na consulta de confirmação) e executar todo o fluxo com um clique. O passo a passo completo está em como escrever um cenário de teste com Apidog.
Em alto nível: crie um novo cenário de teste, adicione sua consulta e mutação GraphQL como etapas em ordem, extraia o id do pedido da resposta da mutação para uma variável e faça referência a essa variável na etapa final da consulta. Anexe as asserções da seção anterior a cada etapa. Agora você tem um teste de regressão repetível para sua API GraphQL que um humano, um agendamento ou um pipeline pode executar.
Para equipes que pesam GraphQL contra outros estilos antes de se comprometerem, nossa análise de REST vs GraphQL vs gRPC e o resumo de ferramentas de teste e mocking de GraphQL ajudam a contextualizar este fluxo de trabalho. E se sua stack também fala SOAP, o mesmo padrão de requisição e asserção se aplica em como testar APIs SOAP no Apidog.
Automatize o fluxo de trabalho com a CLI do Apidog
Uma vez que seus cenários GraphQL estejam no projeto, você pode executar os cenários de teste salvos do projeto a partir de um terminal ou executor de CI com a CLI do Apidog. Instale-a e faça login:
npm install -g apidog-cli
apidog login --with-token <seu-token>
Em seguida, execute um cenário salvo por ID, apontado para um ambiente:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Aqui, -t é o ID do cenário de teste, -e é o ID do ambiente e -r é o reporter (cli, html ou junit; separe-os por vírgula, como -r html,cli, para mais de um). A CLI executa cenários e suítes de teste salvos de seu projeto na nuvem e relata aprovação ou falha, o que conecta o Apidog a um build. Uma ressalva honesta: a documentação da CLI confirma a execução de cenários HTTP, e não afirma se cenários contendo etapas GraphQL são executados sem interface gráfica. Trate a CLI como seu motor para execuções de regressão HTTP e para manter as especificações em sincronia através de seu comando import (OpenAPI, HAR, Postman e mais), e faça seu trabalho de consulta, mutação e asserção GraphQL no aplicativo. Consulte o guia de instalação da CLI do Apidog para configuração de token e CLI do Apidog em um pipeline do GitHub Actions para integrá-lo ao CI.
FAQ
Preciso de um plano pago para testar GraphQL no Apidog? A documentação de requisições GraphQL não restringe este recurso a um nível de plano, e também não traça uma linha entre nuvem e auto-hospedado. Você pode começar no nível gratuito: experimente gratuitamente, sem necessidade de cartão de crédito, e consulte Apidog para detalhes dos planos atuais.
Por que minha requisição GraphQL retorna 200 mas ainda falha? Isso é um comportamento normal do GraphQL. O transporte foi bem-sucedido, então o status HTTP é 200, mas a operação encontrou um erro de negócio ou validação que aparece no array errors do corpo JSON. Sempre verifique se errors está ausente, além de verificar o status, conforme abordado em asserções de API.
Como obtenho sugestões de campo ao escrever uma consulta? Clique no botão Fetch Schema (Buscar Esquema) na caixa de entrada. O Apidog inspeciona seu endpoint e habilita o autocompletar código para que o editor sugira campos e tipos válidos. É uma etapa manual, não automática, então clique nele assim que a URL do seu endpoint estiver definida e refaça a busca após qualquer alteração no esquema.
Onde vão as mutações? Não vejo uma aba separada para mutações. Não há uma. Uma mutação é escrita como GraphQL na mesma caixa Query, usando a palavra-chave mutation em vez de query. Passe seu payload através de variáveis e clique em Send, assim como em uma consulta.
Como passo valores diferentes sem reescrever a consulta? Use variáveis GraphQL. Declare-as na assinatura da operação com um prefixo $ e forneça um objeto JSON de valores. A sintaxe segue a especificação padrão do GraphQL, e o suporte a variáveis do Apidog se combina com as variáveis de ambiente para que uma requisição seja executada em ambientes de staging e produção.
Conclusão
Testar GraphQL se resume a alguns hábitos honestos: escreva a consulta na caixa Query, busque o esquema para que o editor o ajude, mova valores fixos para variáveis e faça asserções no corpo em vez de confiar no código de status. Execute uma mutação da mesma forma que executa uma consulta, depois encadeie ambos em um cenário salvo para que a verificação se repita. Baixe o Apidog para acompanhar, construa o fluxo de usuário e pedidos acima, e você terá um teste de regressão GraphQL que poderá executar novamente sempre que seu esquema mudar.