criação-de-scripts-k6

O que criação-de-scripts-k6 faz?

Esta skill gera testes de performance com k6 que qualquer pessoa da equipe possa executar, entender e corrigir, mesmo sem conhecer k6. Para isso, cada script sai com a mesma estrutura, com nomes que dizem o que é, com credenciais fora do código e com um .md que o explica parte por parte.

Prioridades da equipe: load e stress, tanto HTTP quanto k6 browser. O smoke é sempre o passo prévio.

Fonte da verdade: a documentação oficial

Tudo o que for escrito deve coincidir com https://grafana.com/docs/k6/latest/ (k6 v2.x). As referências desta skill resumem essa documentação. Se algo não estiver coberto, ou se você tiver a menor dúvida sobre uma API, uma opção ou uma métrica, consulte a página oficial (mapa em references/official-docs.md) em vez de confiar na memória. Muitos exemplos da internet usam APIs antigas (k6/experimental/browser, browser síncrono, browser_web_vital_fid) que na v2 já não funcionam mais.

Arquivos de referência (leia apenas o que precisar)

Arquivo	Quando ler
references/test-types.md	Sempre: escolher tipo de teste, perfil de stages e executor
references/thresholds-checks.md	Sempre: thresholds padrão e como escrever checks
references/http-patterns.md	Testes de API: ciclo de vida, auth, segredos, correlação, dados
references/browser-patterns.md	Testes com k6 browser ou híbridos
references/doc-template.md	Ao escrever o .md explicativo
references/official-docs.md	Para buscar a página oficial de um tema
assets/lib/config.js	Copiar exatamente para k6/lib/config.js
assets/templates/*	Base para flows, testes, README, .secrets.example

Padrão de estrutura no projeto

k6/
├── tests/
│   ├── api/        <tipo>-<fluxo>.js            ex. load-checkout.js, stress-search-products.js
│   └── browser/    <tipo>-<fluxo>-browser.js    ex. load-login-browser.js
├── lib/
│   ├── config.js   (copiado de assets/lib/config.js)
│   ├── flows/      <fluxo>.js — os passos do usuário, reutilizados por todos os tipos
│   └── pages/      <pagina>-page.js — page objects (apenas browser, se o fluxo tiver várias páginas)
├── data/           dados de teste JSON/CSV (nunca credenciais)
├── docs/           <mesmo-nome-que-o-script>.md
├── .secrets.example
└── README.md       (de assets/templates/k6-README.md, com o índice de scripts)

Nomes: kebab-case, prefixo de tipo (smoke-, load-, stress-, spike-, soak-, breakpoint-) + fluxo de negócio descritivo (checkout, search-products, não test1 nem api). Os de browser levam sufixo -browser. O .md tem exatamente o mesmo nome que o script.

Idioma: comentários e documentação em português; identificadores de código em inglês.

Se o projeto já tiver uma pasta k6/, reutilize config.js, flows e page objects existentes em vez de duplicá-los, e respeite o que já estiver.

Fluxo de trabalho

1. Entender o pedido

Extraia do que o usuário disse:

• Tipo de teste: load, stress ou outro. Se disser "ver quanto aguenta" ou "levar ao limite", é stress (ou breakpoint se quiser o ponto de ruptura exato). Se disser "carga normal" ou "um dia típico", é load.
• API, browser ou híbrido.
• Endpoints ou telas e ordem do fluxo, como se autentica e o que valida cada passo.
• Carga (usuários concorrentes ou req/s), duração e SLA (ex. p95 < 500 ms).
• Ambiente alvo.

Pergunte apenas o que bloqueia e não pode ser razoavelmente assumido: a URL ou os endpoints se não foram fornecidos, e sempre se o objetivo é produção quando não estiver claro. O resto assume-se com os valores padrão das referências (SLA 500 ms, think time 1–3 s, stress = 2× a carga de load) e cada suposição fica registrada na seção "Suposições" do .md. Se o usuário não conhecer seus números de carga, diga a ele: sem eles, o teste responde a uma pergunta diferente da que lhe interessa.

2. Preparar a estrutura

Crie o que faltar de k6/: lib/config.js (cópia exata de assets/lib/config.js), .secrets.example com as chaves que o script usar, README.md a partir do template, e adicione ao .gitignore do projeto:

k6/.secrets
k6/screenshots/

3. Escrever o fluxo e os testes

• Fluxo em k6/lib/flows/<fluxo>.js (base: assets/templates/flow-api.js). Tem os requests, checks, groups numerados, tags name e think time. Se o fluxo precisar de login, exporte uma função login() que é chamada a partir de setup().
• Teste em k6/tests/api/<tipo>-<fluxo>.js (base: assets/templates/test-api.js). Apenas define options (cenário + thresholds), setup() e default(), que chama o fluxo. Os stages e thresholds vão explícitos no arquivo, com um comentário por linha.
• Browser em k6/tests/browser/<tipo>-<fluxo>-browser.js (base: assets/templates/test-browser.js). Por padrão, híbrido: carga HTTP mais poucos VUs de browser. Leia references/browser-patterns.md.
• Gere sempre também smoke-<fluxo>.js se não existir. É barato (reutiliza o fluxo) e é o primeiro passo obrigatório antes de load ou stress.
• Se pedirem stress e não existir o load do mesmo fluxo, gere ambos: a documentação oficial diz que o stress é executado depois do load e reutiliza o script dele.

Regras que não se negociam, porque protegem a equipe e os sistemas:

• Credenciais, tokens e API keys apenas via k6/secrets (await secrets.get('NOME')) com --secret-source=file=k6/.secrets. Nunca no código, em data/, em padrões de __ENV nem em console.log.
• A URL e o ambiente, via -e BASE_URL / -e TARGET_ENV lidos de lib/config.js. Nunca hardcoded.
• Não remova nem enfraqueça a proteção de produção de config.js.
• Imports de jslib com versão exata (ver official-docs.md).
• Browser: k6/browser, funções async, options.browser.type: 'chromium' no cenário, page.close() em finally, check do k6-utils para checks assíncronos, page.waitForTimeout() em vez de sleep().
• Cada request com tag name estável ('GET /items/:id'), para que URLs com IDs não explodam a quantidade de métricas.

4. Escrever o .md explicativo

Um por script em k6/docs/<nome>.md, seguindo todas as seções de references/doc-template.md. Quem o ler não é especialista: explique cada termo na primeira vez (VU, iteração, p95, threshold), explique o porquê de cada número e use os valores reais do script. Inclua o diagrama ASCII do perfil de carga, a tabela de checks e thresholds "em palavras", os comandos exatos para executá-lo (smoke primeiro) e os erros comuns. Depois, adicione o script ao índice de k6/README.md.

5. Validar

• Execute k6 inspect -e BASE_URL=https://example.test -e TARGET_ENV=staging <script> em cada script novo. Detecta erros de sintaxe, imports quebrados e opções inválidas sem gerar carga. Se o k6 não estiver instalado, diga e deixe o comando para que executem.
• Uma execução real apenas com permissão explícita do usuário e como smoke (poucos VUs e poucos segundos) contra um ambiente que não seja produção. Nunca lance load, stress, spike, soak nem breakpoint por conta própria: eles geram carga real sobre sistemas compartilhados.

6. Responder

Resposta curta:

• Lista de arquivos criados ou modificados.
• O comando para executar o smoke e depois o teste solicitado.
• Suposições principais (as mesmas que no .md).
• O que você validou e o que não (por exemplo, "passa k6 inspect; não foi executado contra a API").

Revisar ou corrigir um script existente

Quando o pedido for entender, corrigir ou melhorar um script:

1. Leia-o completamente e compare com o padrão e com a documentação oficial (APIs antigas, browser sem await, falta de page.close, credenciais no código, sem thresholds, sem tags name, sem think time, perfis tipo "montanha-russa").
2. Explique os problemas em linguagem simples, ordenados por gravidade, e proponha a mudança.
3. Ao corrigi-lo, atualize (ou crie) o .md para que a documentação continue coincidindo com o código.
4. Se o nome não seguir o padrão, sugira a renomeação, mas não o faça sem confirmação, pois pode quebrar pipelines que o invocam.