Cypress Testes de API: Como Testar APIs com cy.request()

Você já executa o Cypress para testes end-to-end. Agora você quer acessar uma API diretamente, verificar o código de status e fazer asserções no corpo JSON sem navegar pela interface do usuário. O Cypress pode fazer isso. O comando cy.request() envia requisições HTTP reais do Node, fora do navegador, para que você possa testar um endpoint por conta própria ou configurar o estado antes que um teste de UI seja executado.

Este guia mostra como testar APIs com Cypress: os fundamentos do cy.request(), como fazer asserções em respostas, encadear requisições para reutilizar um token de autenticação e simular o tráfego do navegador com cy.intercept(). Você também verá onde o Cypress para API se encaixa bem e onde uma ferramenta nativa de API se encaixa melhor.

Por que testar APIs com Cypress

A maioria das suites Cypress dirige um navegador. Mas muito do que você verifica na UI é a API subjacente: o /login retorna um token, o /users retorna o formato correto, um POST cria o registro que você espera.

Testar esses endpoints diretamente tem duas vantagens. Primeiro, as verificações de API são executadas mais rapidamente do que os fluxos de UI porque não há renderização, nem espera por elementos. Segundo, você pode usar cy.request() para configurar dados de teste. Em vez de clicar em um formulário de cadastro para criar um usuário, você envia um POST e passa para a asserção que realmente lhe interessa.

Se o Cypress já está na sua stack, adicionar testes de API significa que não há nenhuma nova ferramenta para instalar. Você os escreve nos mesmos arquivos de especificação, com as mesmas asserções expect, na mesma execução de CI.

Fundamentos do cy.request()

cy.request() faz uma requisição HTTP e retorna a resposta. Ele é executado a partir do processo Node do Cypress, e não do navegador, então não está sujeito a regras de CORS ou same-origin.

O comando aceita várias formas:

cy.request(url)
cy.request(url, body)
cy.request(method, url)
cy.request(method, url, body)
cy.request(options)

A chamada mais simples passa uma URL. Sem um método, o Cypress assume GET por padrão:

cy.request('https://jsonplaceholder.typicode.com/users')

Para qualquer coisa além de um GET básico, passe um objeto de opções. Isso lhe dá controle total sobre método, corpo e cabeçalhos:

cy.request({
  method: 'POST',
  url: 'https://jsonplaceholder.typicode.com/posts',
  headers: {
    'Content-Type': 'application/json'
  },
  body: {
    title: 'API test',
    body: 'created from Cypress',
    userId: 1
  }
})

Opções úteis nesse objeto:

• method: o verbo HTTP (GET, POST, PUT, PATCH, DELETE, e outros). O padrão é GET.
• url: o endpoint. Obrigatório.
• body: o payload da requisição. O Cypress serializa objetos para JSON.
• headers: um objeto de cabeçalhos de requisição.
• auth: credenciais para autenticação HTTP Básica.
• qs: parâmetros da string de consulta (query string) como um objeto.
• failOnStatusCode: defina como false quando quiser fazer asserções em uma resposta 4xx ou 5xx em vez de falhar o teste.

Essa última opção é importante para testes negativos. Por padrão, cy.request() falha o teste em qualquer status que não seja 2xx ou 3xx. Se você está verificando se uma requisição inválida retorna 400, você precisa desativar esse comportamento:

cy.request({
  method: 'GET',
  url: 'https://jsonplaceholder.typicode.com/users/99999',
  failOnStatusCode: false
}).then((response) => {
  expect(response.status).to.eq(404)
})

Fazendo asserções no status e no corpo

cy.request() retorna um objeto de resposta. Encadeie .then() para lê-lo. A resposta possui quatro propriedades que você usará mais frequentemente:

• status: o código de status HTTP.
• body: o payload da resposta. O Cypress o analisa para um objeto JavaScript quando o Content-Type termina em json.
• headers: os cabeçalhos da resposta.
• duration: quanto tempo a requisição levou, em milissegundos.

Aqui está um teste completo que verifica o status, o formato do corpo e um campo específico:

describe('Users API', () => {
  it('returns a list of users', () => {
    cy.request('https://jsonplaceholder.typicode.com/users').then((response) => {
      expect(response.status).to.eq(200)
      expect(response.body).to.be.an('array')
      expect(response.body).to.have.length(10)
      expect(response.body[0]).to.have.property('email')
    })
  })
})

Como response.body já é um objeto analisado, você faz asserções nele com o Chai padrão. Você pode verificar o tipo, o comprimento, propriedades aninhadas ou valores exatos. Esta é a mesma sintaxe de asserção que você usa para testes de UI, então não há nada de novo para aprender.

Você também pode fazer asserções nos cabeçalhos da resposta, o que é útil para verificar o tipo de conteúdo ou caching:

cy.request('https://jsonplaceholder.typicode.com/users').then((response) => {
  expect(response.headers['content-type']).to.include('application/json')
})

Para uma análise mais aprofundada sobre a estruturação dessas verificações, consulte nosso guia sobre asserções de API e as melhores práticas de teste de API mais amplas.

Encadeando requisições e reutilizando um token de autenticação

APIs reais precisam de autenticação. O padrão comum é fazer login uma vez, pegar o token e então enviá-lo em todas as requisições subsequentes. cy.request() encadeia de forma limpa para isso.

Envie a requisição de login, leia o token do corpo da resposta e então use-o na próxima chamada:

describe('Authenticated API flow', () => {
  it('logs in and fetches a protected resource', () => {
    cy.request({
      method: 'POST',
      url: 'https://api.example.com/login',
      body: {
        email: 'user@example.com',
        password: 'secret'
      }
    }).then((loginResponse) => {
      expect(loginResponse.status).to.eq(200)
      const token = loginResponse.body.token

      cy.request({
        method: 'GET',
        url: 'https://api.example.com/profile',
        headers: {
          Authorization: `Bearer ${token}`
        }
      }).then((profileResponse) => {
        expect(profileResponse.status).to.eq(200)
        expect(profileResponse.body).to.have.property('email', 'user@example.com')
      })
    })
  })
})

Se vários testes precisam do mesmo token, mova o login para um beforeEach e armazene o token com Cypress.env() ou um alias encapsulado para que cada teste possa usá-lo. Isso mantém a configuração de autenticação em um só lugar, em vez de repeti-la em cada especificação.

Este padrão de login e uso é o mesmo formato que você escreveria em qualquer fluxo de teste de integração de API, onde uma chamada alimenta dados na próxima.

cy.intercept() para stubbing

cy.request() acessa a API real. Às vezes, você quer o oposto: interceptar as requisições que seu aplicativo front-end faz e retornar uma resposta falsa. Isso é cy.intercept().

Há uma distinção importante aqui. cy.intercept() intercepta apenas requisições feitas pelo seu aplicativo front-end no navegador. Ele não intercepta cy.request(), porque cy.request() ignora completamente o navegador. Use cy.intercept() quando estiver testando como sua UI reage a uma determinada resposta de API, e não quando estiver testando a própria API.

Você pode espionar uma requisição, simular (stub) com uma resposta estática ou esperar por ela. Para simular, passe um objeto de resposta:

cy.intercept('GET', '/api/users', {
  statusCode: 200,
  body: [{ id: 1, name: 'Ada' }]
})

Agora, qualquer requisição do navegador para /api/users retorna esse payload fixo. Isso permite testar casos de borda que são difíceis de serem acionados contra um backend ativo, como uma lista vazia, um erro 500 ou uma resposta lenta.

Para afirmar que a requisição aconteceu, crie um alias com .as() e espere por ela:

it('shows an error banner when the API fails', () => {
  cy.intercept('GET', '/api/users', {
    statusCode: 500,
    body: { message: 'Server error' }
  }).as('getUsers')

  cy.visit('/dashboard')
  cy.wait('@getUsers').its('response.statusCode').should('eq', 500)
  cy.contains('Something went wrong').should('be.visible')
})

A linha cy.wait('@getUsers') pausa o teste até que a requisição interceptada seja resolvida, e então entrega a você a requisição e a resposta para fazer asserções. Configure a interceptação antes da ação que dispara a requisição, ou ela não irá capturar nada. Se você está avaliando quando falsificar uma resposta versus simular um serviço inteiro, nossos posts sobre API mocking e API stubbing vs API mocking detalham os tradeoffs.

Quando o Cypress para API faz sentido e quando não faz

Cypress é uma ótima opção para verificações de API que vivem dentro de uma suite de testes de UI. Se você já está escrevendo testes e2e e precisa semear dados, verificar um endpoint do qual sua UI depende ou simular uma resposta para testar o tratamento de erros, cy.request() e cy.intercept() mantêm tudo em um só lugar. Sem troca de contexto, sem segunda ferramenta.

Também é bom para um pequeno número de testes de fumaça de API autônomos quando o Cypress é seu único executor de testes e você não quer adicionar outra dependência.

Onde fica complicado é em uma suite de testes de API grande e autônoma. O Cypress foi construído para o navegador, então o teste de API é uma capacidade adicionada, não o design central. Algumas lacunas aparecem à medida que a suite cresce:

• Nenhum construtor de requisições visual. Cada requisição é código. Compor cabeçalhos, corpos e parâmetros de consulta manualmente se torna lento quando você tem centenas de endpoints.
• Mais fraco para um pipeline de API apenas em CI. O Cypress inicializa um contexto de navegador mesmo para execuções puras de API, o que é um overhead que você não precisa.
• Nenhuma definição de API compartilhada. Os formatos de requisição vivem em seus arquivos de teste, não em uma especificação que sua equipe pode reutilizar em design, documentação e testes.

É aqui que uma ferramenta nativa de API se encaixa melhor. O Apidog é construído em torno da própria API: você projeta um endpoint uma vez, e então constrói cenários de teste contra ele com um construtor de requisições visual e asserções visuais, sem a necessidade de código para os casos comuns. Requisições, ambientes e autenticação vivem em um workspace compartilhado, para que sua equipe não precise redesenhá-los a partir dos arquivos de teste.

Para CI, o Apidog CLI executa seus cenários de teste salvos de forma headless em qualquer etapa que possa executar Node:

npm install -g apidog-cli

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t <scenarioOrSuiteId> \
  -e <environmentId> \
  -r cli,html,json,junit

O flag -t direciona para um cenário ou suite salvo, -e seleciona um ambiente, e -r escolhe os formatos de relatório (cli, html, json, junit). A saída JUnit se conecta diretamente com a maioria dos dashboards de CI. Adicione -d ou --iteration-data para conduzir um teste a partir de um arquivo de dados, e --upload-report para enviar os resultados de volta ao seu workspace. O CLI executa cenários salvos; não é um remetente de requisições interativo.

Uma maneira útil de pensar sobre isso: use cy.request() para verificações de API que suportam seus testes de navegador, e recorra a uma ferramenta nativa de API quando o teste de API for o trabalho principal. Se você está comparando opções, nossos resumos de ferramentas de automação de testes de API que rodam em CI/CD e as 30 melhores ferramentas de teste de API abrangem o campo.

FAQ

cy.request() é executado no navegador?

Não. cy.request() é executado a partir do processo Node do Cypress, fora do navegador. É por isso que ele não é bloqueado por CORS ou política de same-origin, e por que cy.intercept() não pode interceptá-lo. Se você precisa de uma requisição feita pelo navegador, acione-a através do seu aplicativo e capture-a com cy.intercept().

Como testar uma resposta 400 ou 404 sem falhar o teste?

Por padrão, cy.request() falha em qualquer status que não seja 2xx ou 3xx. Defina failOnStatusCode: false no objeto de opções, e então faça a asserção no status você mesmo com expect(response.status).to.eq(404).

Posso usar cy.request() para fazer login antes de um teste de UI?

Sim, e é um padrão comum. Envie um POST para o seu endpoint de login com cy.request(), leia o token de response.body e armazene-o (em Cypress.env(), localStorage ou um cookie) para que seu teste de UI comece já autenticado. Isso pula o formulário de login e acelera a suite.

Qual a diferença entre cy.request() e cy.intercept()?

cy.request() envia uma requisição HTTP real e retorna a resposta real, então você o usa para testar uma API. cy.intercept() observa ou simula as requisições que seu front-end faz no navegador, então você o usa para controlar o que sua UI recebe. Um acessa a rede; o outro a molda.

Devo usar Cypress ou uma ferramenta dedicada para testes de API?

Use o Cypress quando as verificações de API suportam uma suite de testes de navegador que você já executa. Para uma grande suite de API autônoma, pipelines de API apenas em CI, ou uma definição de API compartilhada da qual toda a sua equipe trabalha, uma ferramenta nativa de API como o Apidog se encaixa melhor. Consulte nossas melhores práticas de teste de API para saber como decidir.