Artillery é um kit de ferramentas de teste de carga de código aberto, baseado em Node.js, que impulsiona tráfego de alta concorrência em sua API a partir de um simples script YAML. Você define fases de carga e fluxos de requisição, executa artillery run script.yml e lê percentis de latência, taxas de requisição e contagens de erros. Este guia o conduzirá pela instalação do Artillery v2, escrita de um script de teste real, sua execução, captura de resultados da maneira atual do v2 e sua integração em CI.
O que é Artillery e Quando Recorrer a Ele
Artillery gera usuários virtuais (VUs) que acessam seus endpoints e mede como o sistema se comporta sob tráfego sustentado. Um usuário virtual é um cliente simulado que executa um cenário, uma requisição após a outra, assim como um chamador real faria.
Você recorre ao Artillery quando precisa de respostas para questões de escala. Como a latência p95 se comporta a 50 requisições por segundo? Em que taxa de chegada os erros começam a aparecer? A API permanece estável por cinco minutos de carga sustentada, ou ela se degrada?
Artillery é bom nisso porque o teste é declarativo. Você descreve a forma da carga em YAML em vez de codificar um loop de concorrência manualmente. Ele funciona em qualquer lugar onde o Node.js é executado, então o mesmo script funciona em seu laptop e em CI.
Artillery é uma das várias opções neste espaço. Se você ainda está comparando ferramentas, o resumo das principais ferramentas de teste de carga e esta comparação de software de teste de carga cobrem os trade-offs entre k6, JMeter, Gatling e outros.
Instalar Artillery (v2)
O nome do pacote é exatamente artillery, e a versão principal atual é v2. Instale-o globalmente com npm e, em seguida, verifique a versão.
npm install -g artillery@latest
artillery version
Você precisa de uma versão LTS recente do Node.js. Artillery funciona em Windows, macOS e Linux.
Se você preferir não instalar nada globalmente, execute-o sob demanda com npx.
npx artillery@latest run script.yml
Escrevendo um Script de Teste Artillery
Um teste Artillery é um arquivo YAML com duas seções de nível superior. A seção config define o alvo e o perfil de carga. A seção scenarios define o que cada usuário virtual faz.
Aqui está um script completo que aquece, sobe para o pico e, em seguida, mantém uma carga sustentada.
config:
target: "https://api.example.com"
phases:
- name: "Warm up"
duration: 60
arrivalRate: 5
- name: "Ramp to peak"
duration: 120
arrivalRate: 5
rampTo: 50
- name: "Sustained load"
duration: 300
arrivalRate: 50
maxVusers: 500
# Inline variables (or use a CSV via config.payload)
variables:
productId:
- "1001"
- "1002"
scenarios:
- name: "Browse and create order"
flow:
- get:
url: "/v1/products/{{ productId }}"
- post:
url: "/v1/orders"
json:
productId: "{{ productId }}"
quantity: 2
Compreendendo a seção config
config.target é o host base contra o qual cada requisição é executada. Cada etapa em um cenário anexa sua url a esta base.
config.phases é um array de fases de carga que são executadas em ordem. As chaves que você mais usará:
duration: quanto tempo a fase dura, em segundos ou uma string legível por humanos como"5m".arrivalRate: quantos novos usuários virtuais iniciam a cada segundo.rampTo: aumenta linearmente a taxa de chegada dearrivalRateaté este valor ao longo da fase.arrivalCount: um número fixo de VUs distribuídos ao longo da fase, em vez de uma taxa por segundo.maxVusers: um limite para quantos usuários virtuais podem ser executados simultaneamente.name: um rótulo que aparece na saída.
Um detalhe que confunde as pessoas. A duration de uma fase controla por quanto tempo o Artillery continua gerando usuários virtuais, não o tempo total de relógio do teste. Se um VU começa perto do fim de uma fase e seu cenário leva um tempo, a execução continua até que esse usuário termine.
Compreendendo a seção scenarios
scenarios é um array. Cada cenário tem um flow, que é a lista ordenada de passos que um usuário virtual executa. As chaves opcionais incluem name e weight, onde weight define a probabilidade relativa de o Artillery escolher este cenário para um determinado VU.
Os passos do fluxo usam chaves de verbos HTTP: get, post, put, delete e patch. Cada um aceita uma url, e os corpos das requisições vão sob json. A sintaxe de chaves duplas, {{ productId }}, puxa uma variável.
Impulsionando Requisições a partir de um Arquivo CSV
Valores codificados são bons para um teste de fumaça. Para uma carga realista, alimente dados de um CSV com config.payload. Cada usuário virtual escolhe uma linha, e os nomes das colunas se tornam variáveis.
config:
target: "https://api.example.com"
payload:
path: "./users.csv"
fields:
- "email"
- "password"
phases:
- duration: 120
arrivalRate: 20
scenarios:
- flow:
- post:
url: "/login"
json:
email: "{{ email }}"
password: "{{ password }}"
Executando o Teste
O comando básico aponta o Artillery para o seu script.
artillery run script.yml
# Override target without editing the script:
artillery run --target https://staging.example.com script.yml
# Pass variables as JSON:
artillery run -v '{ "productId": ["1001","1002"] }' script.yml
Algumas flags são importantes de se conhecer. --target (ou -t) sobrescreve config.target para que você possa apontar o mesmo script para staging ou produção. --environment (ou -e) seleciona um bloco nomeado em config.environments. --config (ou -c) carrega a configuração de um arquivo separado. --insecure (ou -k) pula a verificação TLS para certificados autoassinados em ambientes de teste.
Lendo os Resultados
Enquanto o teste é executado, Artillery imprime métricas agregadas a cada 10 segundos, aproximadamente. Quando termina, você recebe um relatório resumido. Os números mais importantes:
- Taxa de requisições: requisições por segundo que a execução realmente alcançou.
- Percentis de latência: tempos de resposta p50 (mediana), p95 e p99. O p95 informa a experiência dos 5% mais lentos das requisições, que é geralmente onde o problema aparece primeiro.
- Contagens de erros: requisições falhas, timeouts e respostas que não são 2xx, agrupadas por tipo.
Observe as latências de cauda, não apenas a média. Uma média pode parecer saudável enquanto o p99 sobe silenciosamente para o território de múltiplos segundos. Se os erros aparecerem apenas durante a fase sustentada, você provavelmente encontrou um ponto de saturação que vale a pena investigar. Para um tratamento mais aprofundado sobre quais métricas rastrear e porquê, consulte este guia de teste de desempenho de API.
Gerando um Relatório no Artillery v2
Os relatórios mudaram entre as versões do Artillery, então é aqui que tutoriais desatualizados podem te enganar. Guias mais antigos dizem para executar artillery run --output report.json e depois artillery report report.json para produzir um arquivo HTML. A primeira parte ainda funciona. A segunda parte não.
A flag --output ainda grava um arquivo de resultados JSON legível por máquina.
# Escreve resultados JSON legíveis por máquina (ainda suportado):
artillery run --output report.json script.yml
O comando artillery report, o gerador de JSON para HTML, foi removido da CLI do Artillery. A documentação oficial afirma que "não é mais suportado e foi removido da CLI do Artillery". O código de relatório HTML ficou sem manutenção, foi descontinuado e depois removido, sem planos de trazê-lo de volta. Não escreva artillery report report.json; não funcionará na versão v2 atual.
Em vez disso, você tem três opções atuais.
Primeiro, analise o JSON você mesmo. Isso é ideal para CI, onde você deseja afirmar contra um limite. Puxe a latência p95 agregada com jq:
jq '.aggregate.summaries["http.response_time"].p95' report.json
Segundo, use o Artillery Cloud para um dashboard hospedado. Esta é a substituição oficial para o antigo relatório HTML. Passe --record com sua chave de API.
artillery run --record --key $ARTILLERY_CLOUD_API_KEY script.yml
Terceiro, envie métricas para sua própria pilha de monitoramento com o plugin publish-metrics ou OpenTelemetry, para que a latência e as taxas de erro cheguem aos mesmos painéis que você já usa para produção.
Executando Artillery em CI
Como o Artillery é apenas uma CLI Node.js, ele se encaixa em qualquer pipeline. Aqui está um workflow do GitHub Actions que instala o Artillery, executa o teste e carrega o relatório JSON como um artefato de build.
name: Load test
on: [workflow_dispatch]
jobs:
artillery:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: "lts/*"
- run: npm install -g artillery@latest
- run: artillery run --output report.json script.yml
- uses: actions/upload-artifact@v4
with:
name: artillery-report
path: report.json
Este exemplo é executado por despacho manual. Testes de carga pesados geralmente são acionados sob demanda ou em um cronograma, em vez de em cada commit, pois levam minutos e consomem largura de banda real. Assim que o relatório JSON existe, você pode adicionar um passo jq que falha o job se o p95 exceder seu orçamento.
Onde o Apidog se Encaixa: Testes Funcionais e Gating de CI
Artillery responde à pergunta "a API pode sobreviver a tanto tráfego?". Isso é teste de carga e desempenho. Uma pergunta diferente corre paralela a essa: "a API ainda retorna respostas corretas após essa mudança de código?". Isso é teste funcional e de regressão, e é onde o Apidog se encaixa.
Apidog é uma plataforma de API completa para design, depuração, mocking, documentação e testes automatizados. Seus cenários de teste agrupam endpoints em etapas lógicas com condições como if, for e foreach, para que você possa validar corpos de resposta, códigos de status e contratos. Você executa esses cenários em CI com a CLI do Apidog para controlar merges após alterações no código.
Seja claro sobre o limite. Apidog inclui um recurso de teste de desempenho, mas é limitado a até 100 usuários virtuais. Isso é suficiente para identificar regressões óbvias, e não é um substituto para o Artillery em alta concorrência. Para carga distribuída e modelada por código em grande escala, o Artillery é a ferramenta certa. Essa mesma abordagem honesta aparece em nosso artigo sobre testes de carga de APIs sem Python, e a mecânica do recurso de 100 VUs do Apidog é abordada em testes de desempenho de API no Apidog.
Então, use ambos. Teste de carga com Artillery para escala. Execute verificações funcionais e de regressão em CI com a CLI do Apidog para detectar comportamentos quebrados antes que sejam lançados.
A CLI do Apidog é instalada via npm, e apidog run é apenas por flag.
# Apidog CLI: execução funcional/regressão em CI (somente flag, sem arquivo posicional)
npm install -g apidog-cli
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t <TEST_SCENARIO_ID> \
-e <ENVIRONMENT_ID> \
-r cli,junit \
--out-dir ./apidog-reports
A flag -t é o ID do cenário de teste, -e é o ID do ambiente obrigatório, e -r cli,junit emite tanto a saída do console quanto um relatório XML JUnit que os sistemas de CI podem ler. Para um passo a passo, veja o tutorial da CLI do Apidog, e para padrões de design de pipeline, veja estas melhores práticas de CI/CD para testes de API.
Quer testes funcionais e de contrato protegendo seu CI junto com suas execuções de carga do Artillery? Baixe o Apidog gratuitamente e construa seu primeiro cenário de teste.
Perguntas Frequentes
O que é teste de carga Artillery?
Teste de carga Artillery é a prática de usar o kit de ferramentas de código aberto Artillery para simular muitos usuários virtuais concorrentes acessando sua API. Você descreve a forma da carga e o fluxo de requisição em um script YAML, executa-o e mede percentis de latência, taxas de requisição e erros para ver como seu sistema se comporta sob estresse.
Artillery é gratuito e de código aberto?
Sim. A CLI principal do Artillery é gratuita e de código aberto, distribuída no npm como o pacote artillery. Há também uma oferta paga hospedada, Artillery Cloud, que fornece um painel para resultados, mas você pode executar testes de carga completos localmente e em CI sem ela.
Como você executa um teste de carga Artillery?
Instale-o com npm install -g artillery@latest, escreva um script YAML com um bloco config (alvo e fases) e um bloco scenarios (o fluxo de requisição), e então execute artillery run script.yml. O Artillery imprime métricas ao vivo a cada 10 segundos e um resumo no final.
Como você gera um relatório Artillery?
Execute artillery run --output report.json script.yml para gravar um arquivo de resultados JSON. O antigo comando artillery report que produzia HTML foi removido da CLI. Em vez disso, analise o JSON com uma ferramenta como jq, use o Artillery Cloud via --record --key, ou envie métricas com o plugin publish-metrics ou OpenTelemetry.
Artillery vs k6 ou JMeter: qual você deve usar?
Todos os três lidam com carga em alta escala. Artillery usa YAML declarativo e Node.js, o que se adapta a equipes já no ecossistema JavaScript. k6 cria scripts em JavaScript com um modelo code-first. JMeter é orientado por GUI e baseado em Java, com uma longa história de plugins. A comparação Gatling vs JMeter aborda os trade-offs em mais detalhes. Escolha aquele cujo modelo de script se adapte à sua equipe, e então combine-o com testes de CI funcionais para cobertura completa.