Como Testar APIs GraphQL no Apidog (Queries, Mutations e Automação)

Você tem um endpoint GraphQL e precisa validar o comportamento real da API: a consulta user retorna os campos consumidos pelo aplicativo, a mutação createOrder persiste um pedido e a resposta mantém a estrutura esperada quando as variáveis mudam. Como GraphQL envia operações para uma única URL — normalmente via POST — você precisa de um cliente que entenda consultas, variáveis, esquema e asserções sobre o JSON retornado.

Experimente o Apidog hoje

Apidog trata GraphQL como um tipo de requisição de primeira classe, junto com HTTP, gRPC, WebSocket, SSE e SOAP. Neste guia, você vai criar uma requisição GraphQL, buscar o esquema para usar autocompletar, passar variáveis, executar uma mutação e validar a resposta com asserções.

O exemplo usa uma API de e-commerce: primeiro você consulta um usuário e seus pedidos; depois cria um novo pedido. Para a base conceitual, consulte a documentação oficial do GraphQL e a comparação REST vs GraphQL.

O que muda ao testar GraphQL

Em REST, você geralmente testa vários endpoints, cada um com uma resposta relativamente fixa. Em GraphQL, há um único endpoint e o cliente define os campos que quer receber.

Na prática, isso muda dois pontos:

1. A operação vai no corpo da requisição, não na URL. Por exemplo, GET /users/42 pode virar user(id: 42) { ... } enviado por POST.
2. Um erro de negócio ou validação pode retornar HTTP 200 OK, com detalhes no array errors do JSON.

Por isso, validar somente o status HTTP não é suficiente. Você também precisa verificar errors e os valores dentro de data.

Criar uma requisição GraphQL no Apidog

Primeiro, baixe o Apidog ou abra-o no navegador. Em seguida, abra ou crie um projeto.

1. Crie a requisição e selecione GraphQL

1. Clique em +.
2. Selecione New Request.
3. Defina o método como POST.
4. Informe a URL do endpoint GraphQL:

https://api.yourstore.com/graphql

1. Abra a seção Body.
2. Selecione GraphQL.

O editor exibirá o campo Query, onde você escreve a operação GraphQL.

Se o endpoint exigir autenticação, configure-a na seção Authorization, por exemplo usando um token Bearer. GraphQL continua sendo uma requisição HTTP por baixo dos panos.

2. Escreva uma consulta inicial

Na aba Run, adicione uma consulta que busque um usuário e seus pedidos:

query GetUserWithOrders {
  user(id: "usr_1024") {
    id
    name
    email
    orders {
      id
      total
      status
      createdAt
    }
  }
}

Os campos precisam corresponder exatamente ao esquema da API. Por exemplo, se o servidor expõe emailAddress em vez de email, a consulta falhará.

3. Busque o esquema para habilitar autocompletar

Para evitar adivinhar nomes de tipos e campos:

1. Configure a URL do endpoint.
2. Clique em Fetch Schema no editor.
3. Aguarde a conclusão da introspecção.
4. Use as sugestões de campos e tipos enquanto escreve a consulta.

A busca de esquema é manual. Se a introspecção estiver desabilitada no servidor, o Apidog não poderá carregar o esquema e você precisará usar a documentação da sua API. Depois de alterações no esquema, execute Fetch Schema novamente.

4. Execute e inspecione a resposta

Clique em Send. Uma resposta bem-sucedida pode ser semelhante a esta:

{
  "data": {
    "user": {
      "id": "usr_1024",
      "name": "Dana Whitfield",
      "email": "[e-mail]",
      "orders": [
        {
          "id": "ord_5001",
          "total": 89.9,
          "status": "SHIPPED",
          "createdAt": "2026-07-01T09:14:00Z"
        },
        {
          "id": "ord_5002",
          "total": 12.5,
          "status": "PENDING",
          "createdAt": "2026-07-12T16:03:00Z"
        }
      ]
    }
  }
}

Em GraphQL, o resultado normalmente fica dentro de data. Quando há falhas de validação ou execução, elas aparecem no array errors.

Use variáveis para reutilizar a consulta

Evite fixar valores como "usr_1024" diretamente na consulta. Declare uma variável GraphQL e passe o valor em JSON.

query GetUserWithOrders($userId: ID!) {
  user(id: $userId) {
    id
    name
    orders {
      id
      total
      status
    }
  }
}

No campo de variáveis, informe:

{
  "userId": "usr_1024"
}

Agora você pode executar a mesma operação para diferentes usuários sem editar o documento GraphQL. A sintaxe é padrão do GraphQL; consulte a documentação sobre variáveis.

Combine variáveis GraphQL com variáveis de ambiente para usar a mesma requisição em staging e produção, alterando apenas os valores do ambiente.

Execute uma mutação para criar um pedido

Mutações usam o mesmo editor Query. A diferença é a palavra-chave mutation.

mutation CreateOrder($input: CreateOrderInput!) {
  createOrder(input: $input) {
    id
    total
    status
    createdAt
  }
}

Passe o payload como variável:

{
  "input": {
    "userId": "usr_1024",
    "items": [
      {
        "sku": "TSHIRT-BLK-M",
        "quantity": 2
      },
      {
        "sku": "MUG-CERAMIC",
        "quantity": 1
      }
    ],
    "currency": "USD"
  }
}

Clique em Send. Uma resposta esperada seria:

{
  "data": {
    "createOrder": {
      "id": "ord_5003",
      "total": 42.3,
      "status": "PENDING",
      "createdAt": "2026-07-15T10:22:11Z"
    }
  }
}

Execute mutações em um ambiente de teste ou staging. Elas podem alterar dados reais.

Um fluxo útil de ponta a ponta é:

1. Consultar o usuário.
2. Criar um pedido.
3. Capturar o id retornado.
4. Consultar o usuário novamente.
5. Confirmar que o pedido criado aparece na lista.

Adicione asserções à resposta GraphQL

Inspecionar a resposta manualmente ajuda durante a exploração. Para testes repetíveis, adicione asserções à requisição.

Veja o guia de asserções de API para configurar essas validações no Apidog.

Para GraphQL, comece com estas verificações:

• Status HTTP igual a 200.
• Campo errors ausente.
• Valores esperados dentro de data.

Exemplos de caminhos JSONPath:

$.data.createOrder.status

Valide que o valor é:

PENDING

Para conferir se o usuário possui pedidos, use:

$.data.user.orders

E valide que o comprimento do array é maior que zero.

A verificação de errors é essencial: uma operação GraphQL pode retornar 200 OK e, ainda assim, falhar no nível da operação.

Salve o fluxo como cenário de teste

Uma requisição com asserções é um bom teste de fumaça. Para validar um fluxo completo, crie um cenário de teste com múltiplas etapas:

1. Adicione a consulta do usuário.
2. Adicione a mutação createOrder.
3. Extraia o id do pedido da resposta da mutação.
4. Execute uma consulta final para confirmar a persistência.
5. Adicione asserções em cada etapa.

O guia como escrever um cenário de teste com Apidog mostra o fluxo completo.

Esse cenário se torna um teste de regressão reutilizável para validar consultas, mutações e contratos de resposta após alterações no esquema.

Para comparar estilos de API e ferramentas relacionadas, consulte:

• REST vs GraphQL vs gRPC
• Ferramentas de teste e mocking de GraphQL
• Como testar APIs SOAP no Apidog

Automatize cenários com a CLI do Apidog

Depois de salvar seus cenários no projeto, você pode executá-los pelo terminal ou em um executor de CI com a CLI do Apidog.

Instale a CLI e faça login:

npm install -g apidog-cli
apidog login --with-token <seu-token>

Execute um cenário salvo usando o ID do cenário e o ID do ambiente:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli

Parâmetros principais:

• -t: ID do cenário de teste.
• -e: ID do ambiente.
• -r: reporter, como cli, html ou junit.

Para usar mais de um reporter:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r html,cli

A CLI executa cenários e suítes de teste salvos no projeto e reporta aprovação ou falha. A documentação confirma a execução de cenários HTTP, mas não afirma explicitamente se cenários com etapas GraphQL são executados sem a interface gráfica. Use a CLI para execuções de regressão HTTP e sincronização de especificações via import, incluindo OpenAPI, HAR e Postman. Para consultas, mutações e asserções GraphQL, use o aplicativo.

Consulte o guia de instalação da CLI do Apidog e o guia da CLI do Apidog no GitHub Actions.

FAQ

Preciso de um plano pago para testar GraphQL no Apidog?

A documentação de requisições GraphQL não restringe esse recurso a um plano específico. Você pode começar no nível gratuito e consultar o Apidog para os detalhes atuais dos planos.

Por que minha requisição retorna 200, mas ainda falha?

Esse é um comportamento normal em GraphQL. O transporte HTTP foi bem-sucedido, mas a operação pode ter falhado por validação ou regra de negócio. Verifique o array errors além do status HTTP, conforme descrito nas asserções de API.

Como obtenho sugestões de campos ao escrever uma consulta?

Clique em Fetch Schema. O Apidog executa introspecção no endpoint e habilita sugestões de campos e tipos. Repita o processo após mudanças no esquema.

Onde escrevo mutações?

No mesmo campo Query usado pelas consultas. Use a palavra-chave mutation, passe os dados por variáveis e clique em Send.

Como uso valores diferentes sem reescrever a consulta?

Declare variáveis na assinatura da operação, usando o prefixo $, e forneça os valores em um objeto JSON. Consulte a especificação de variáveis do GraphQL.

Conclusão

Para testar GraphQL de forma confiável:

1. Escreva a operação no campo Query.
2. Use Fetch Schema para reduzir erros de campos e tipos.
3. Mova valores fixos para variáveis.
4. Valide errors e os valores dentro de data.
5. Encadeie consultas e mutações em um cenário salvo.

Com esse fluxo, você transforma uma consulta manual em um teste de regressão reutilizável para sua API GraphQL.