k6 teste de carga: um guia prático para APIs

Se sua API funciona bem para um usuário, mas falha sob tráfego, você precisa de testes de carga, e o k6 é uma das maneiras mais limpas de fazer isso. Este guia aborda o que é k6, como instalá-lo, como escrever seu primeiro script e como ler os resultados, para que você possa tratar os testes de carga como parte de sua rotina normal de testes de desempenho de API. Também veremos como o k6 se encaixa nos testes funcionais em CI, baseando-nos na documentação oficial do k6 onde os detalhes importam.

O que é k6?

k6 é uma ferramenta de teste de carga de código aberto, agora mantida pela Grafana. Você escreve seu teste como um arquivo JavaScript, o k6 o executa com um rápido motor Go, e ele ataca seus endpoints com tráfego simulado. A divisão é intencional: você cria testes em uma linguagem que a maioria dos desenvolvedores já conhece, mas o próprio gerador de carga é executado como Go compilado, para que uma única máquina possa gerenciar muitos usuários virtuais sem engasgar.

O k6 é construído para um único trabalho e o faz bem: gerar carga sustentada e repetível e medir como seu sistema responde. Ele relata percentis de latência, taxas de solicitação, taxas de erro e permite definir regras de aprovação/reprovação para esses números. Esse foco é o ponto principal. O k6 não é um cliente de API, uma ferramenta de documentação ou uma estrutura de teste funcional. É um motor de carga.

Alguns termos que você encontrará constantemente:

• Usuário Virtual (VU): um usuário simulado executando seu script em loop. Mais VUs significam mais carga concorrente.
• Iteração: uma passagem completa pela sua função de teste. Um VU executa iterações consecutivamente.
• Estágio: uma etapa em um perfil de carga, usada para aumentar ou diminuir VUs ao longo do tempo.
• Limite (Threshold): uma regra de aprovação/reprovação em uma métrica, como "o percentil 95 da latência deve permanecer abaixo de 500ms".
• Verificação (Check): uma asserção não fatal em uma resposta, como "o status foi 200". Verificações falhas são contadas, mas o teste continua sendo executado.

Instalando k6

O k6 é distribuído como um único binário, então a instalação é rápida. No macOS com Homebrew:

brew install k6

No Windows com Chocolatey:

choco install k6

No Debian ou Ubuntu, adicione o repositório apt da Grafana e instale:

sudo gpg -k
sudo gpg --no-default-keyring --keyring /usr/share/keyrings/k6-archive-keyring.gpg \
  --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys C5AD17C747E3415A3642D57D77C6C491D69
echo "deb [signed-by=/usr/share/keyrings/k6-archive-keyring.gpg] https://dl.k6.io/deb stable main" \
  | sudo tee /etc/apt/sources.list.d/k6.list
sudo apt-get update
sudo apt-get install k6

Confirme se funciona:

k6 version

Uma imagem Docker também está disponível se você preferir não instalar nada localmente. Verifique a página de instalação na documentação para os comandos atuais, já que os detalhes dos pacotes mudam com o tempo.

Seu primeiro script k6

Um teste k6 é um módulo JavaScript com uma função padrão. O k6 chama essa função uma vez por iteração, por VU. Aqui está um script mínimo que atinge um endpoint e verifica a resposta:

import http from 'k6/http';
import { check, sleep } from 'k6';

export default function () {
  const res = http.get('https://test-api.example.com/users');

  check(res, {
    'status is 200': (r) => r.status === 200,
    'body is not empty': (r) => r.body.length > 0,
  });

  sleep(1);
}

Salve como script.js e execute:

k6 run script.js

Por padrão, o k6 executa um VU por uma iteração. Esse sleep(1) adiciona uma pausa de um segundo entre as iterações, o que simula um usuário real pausando entre as ações. Sem o sleep, cada VU faz um loop o mais rápido que a rede permite, o que é útil para testes de throughput brutos, mas irrealista para a simulação do comportamento do usuário.

check() são asserções "suaves". Uma verificação falha aparece no resumo, mas não interrompe a execução. Isso é intencional. Sob carga pesada, você espera algumas falhas, e deseja que o teste continue medindo para que você possa ver o quão ruim a situação fica.

VUs, estágios e limites

O primeiro script executa um único usuário uma vez. O teste de carga real consiste em controlar quantos usuários acessam sua API e por quanto tempo. Você configura isso com um objeto options exportado.

A forma mais simples define um número fixo de VUs e uma duração:

export const options = {
  vus: 50,
  duration: '30s',
};

Isso executa 50 usuários virtuais por 30 segundos. Mais útil é um perfil de rampa construído a partir de estágios, que permite simular o aumento, manutenção e queda do tráfego:

export const options = {
  stages: [
    { duration: '1m', target: 100 },  // aumenta para 100 VUs
    { duration: '3m', target: 100 },  // mantém em 100 VUs
    { duration: '1m', target: 0 },    // diminui para 0
  ],
  thresholds: {
    http_req_duration: ['p(95)<500'],   // 95% das requisições abaixo de 500ms
    http_req_failed: ['rate<0.01'],     // menos de 1% de erros
  },
};

Os limites são onde o k6 ganha seu lugar no CI. Se um limite falha, o k6 sai com um código diferente de zero. Isso significa que uma etapa do pipeline pode falhar a build quando a latência ou as taxas de erro cruzam uma linha que você definiu. Você está codificando um orçamento de desempenho, da mesma forma que codificaria uma asserção funcional.

Um mapa rápido dos perfis de carga comuns e a pergunta que cada um responde:

Você não precisa de todos os cinco. Comece com "fumaça" e "carga". Adicione "estresse" e "pico" quando souber seus números normais. Para uma pesquisa mais ampla de abordagens e as métricas por trás delas, os fundamentos do teste de desempenho se mantêm em todas as ferramentas, não apenas no k6.

Lendo os resultados do k6

Quando uma execução termina, o k6 imprime um resumo no terminal. As linhas mais importantes:

• http_req_duration: tempo total da requisição, mostrado como média, min, max, mediana, p90 e p95. Os percentis p95 e p99 informam o que seus usuários mais lentos realmente experimentam. Médias escondem a dor; percentis a revelam.
• http_req_failed: a parcela de requisições que falharam. Observe como isso se move à medida que os VUs aumentam.
• http_reqs: total de requisições e requisições por segundo. Este é o seu throughput.
• iterations: quantas passagens completas foram concluídas e a taxa.
• vus e vus_max: usuários virtuais ativos e de pico.
• checks: a taxa de aprovação de suas asserções check().

Leia percentis, não médias. Um tempo médio de resposta de 200ms parece bom até você ver um p99 de 4 segundos, o que significa que um em cada cem usuários espera quatro segundos. Essa cauda é onde os usuários desistem.

Para qualquer coisa além de observar o terminal, o k6 pode transmitir resultados para saídas externas. Ele escreve JSON ou CSV e se integra a painéis Grafana e Prometheus para análise visual e ao vivo durante uma execução. Essa combinação, k6 mais Grafana, é o motivo pelo qual você frequentemente verá a ferramenta sendo chamada de "grafana k6". Para um teste único, o resumo do terminal é suficiente; para monitoramento contínuo, envie as métricas para um lugar onde você possa traçá-las.

Onde o k6 se encaixa e onde o Apidog se encaixa

k6 é um motor de carga. Ele responde "como meu sistema se comporta sob tráfego sustentado". Ele não verifica se sua API retorna os dados corretos, se corresponde ao seu contrato ou se lida com a autenticação corretamente em todos os endpoints. Essas são questões de testes funcionais e de contrato, e precisam de uma ferramenta diferente.

Essa é a divisão que vale a pena manter clara. Você quer ambos os tipos de teste em seu pipeline, e eles não competem:

Apidog lida com o lado da correção. Você projeta ou importa sua API, constrói cenários de teste com asserções visuais e os executa em CI com apidog run, da mesma forma que você executaria um script k6. O guia CLI do Apidog mostra como conectar esses testes funcionais a um pipeline. O Apidog também inclui recursos de teste de desempenho mais leves para verificações rápidas, abordados no passo a passo de teste de desempenho de API no Apidog, mas não é um gerador de carga da classe k6 e não tenta ser.

Um fluxo de trabalho prático se parece com isto. A cada commit, o Apidog executa seus testes funcionais e de contrato para confirmar que a API ainda faz o que deveria. Em um cronograma ou antes de um lançamento, o k6 executa um perfil de carga contra um ambiente de homologação para confirmar que a API permanece rápida sob tráfego. Portão de correção e portão de desempenho, cada um com a ferramenta construída para ele.

Se você estiver comparando motores antes de se comprometer, o k6 se posiciona ao lado de JMeter, Gatling e Locust. O resumo de ferramentas de teste de carga e esta comparação de alternativas ao Locust apresentam as compensações se a linguagem de script ou a escala mudarem sua escolha.

Perguntas Frequentes

O k6 é gratuito?

Sim. k6 é de código aberto sob a licença AGPL, e o binário é gratuito para rodar localmente sem limite de usuários virtuais além do seu próprio hardware. A Grafana também oferece o k6 Cloud, um serviço pago para executar grandes testes distribuídos e armazenar resultados, mas você nunca precisa usá-lo. A ferramenta principal atende à maioria das equipes. Se você quiser verificar outras opções gratuitas primeiro, o panorama das ferramentas de teste de carga lista o que cada uma oferece.

Preciso saber JavaScript para usar k6?

Você precisa de JavaScript básico, não de profunda experiência. A maioria dos scripts k6 é uma função padrão, algumas chamadas http.get ou http.post, algumas verificações e um objeto de opções. Se você consegue ler os exemplos neste guia, pode escrever um teste funcional. Não há etapa de construção e nenhum framework para aprender, apenas a API do k6.

Qual a diferença entre k6 e Apidog para teste de desempenho?

O k6 é um gerador de carga dedicado, construído para simular tráfego pesado sustentado e reportar percentis em escala. O Apidog é uma plataforma de API focada em design, testes funcionais e testes de contrato, com recursos mais leves de teste de desempenho para verificações rápidas. Use o k6 quando precisar de carga real e orçamentos de desempenho em CI. Use o Apidog para correção, validação de contrato e execução de testes funcionais a cada commit. Eles resolvem problemas diferentes e funcionam bem juntos.

Posso executar k6 em CI/CD?

Sim, e é uma configuração comum. O k6 sai com um código diferente de zero quando um limite falha, então qualquer sistema de CI pode falhar a build em uma regressão de desempenho. Execute k6 run script.js como uma etapa do pipeline, aponte-o para um ambiente de homologação e defina limites para latência p95 e taxa de erro. Combine-o com testes funcionais do apidog run para que cada commit receba tanto uma verificação de correção quanto uma verificação de carga.

Conclusão

O k6 oferece uma maneira limpa e scriptável de aplicar carga real à sua API e medir o que acontece. Instale o binário, escreva um pequeno arquivo JavaScript, defina VUs e estágios, adicione limites e leia os percentis. Esse é o ciclo completo. Mantenha os testes de carga separados dos testes funcionais, já que cada um responde a uma pergunta diferente, e execute ambos em CI para que nada escape.

Para o lado da correção dessa divisão, o Apidog permite que você projete, teste, simule e documente sua API em um só lugar, e depois execute testes funcionais em CI com apidog run. Baixe o Apidog para emparelhar a confiança no nível do contrato com suas execuções de carga k6.