Flow Test Engine - Quick Reference Card

Cheat Sheet de Referência Rápida | Versão 1.0

📋 Estrutura Básica

node_id: "meu-teste"                    # ID único (obrigatório)
suite_name: "Meu Teste"                 # Nome (obrigatório)
base_url: "https://api.example.com"     # URL base (opcional)
execution_mode: "sequential"            # sequential|parallel

metadata:
  priority: "high"                      # critical|high|medium|low
  tags: ["smoke", "api"]                # Categorização

variables:
  user_id: 123                          # Variáveis locais

exports: ["auth_token"]                 # Exportar globalmente

depends:                                # Dependências
  - path: "./setup.yaml"
    required: true

steps: [...]                            # Steps (obrigatório)

🔧 Step Básico

- name: "Nome do step"                  # Obrigatório
  step_id: "unique-id"                  # Para referência
  request:
    method: POST                        # GET|POST|PUT|DELETE|PATCH
    url: "/api/endpoint"                # Relativo ou absoluto
    headers:
      Authorization: "Bearer {{token}}"
    body:
      key: "value"
    params:                             # Query string
      page: 1
  assert:
    status_code: 200
    body:
      id: {exists: true}
  capture:
    result_id: "body.id"

🔄 Interpolação de Variáveis

Tipo	Sintaxe	Exemplo
Local	`{{var}}`	`{{user_id}}`
Cross-suite	`{{suite.var}}`	`{{auth.token}}`
Ambiente	`{{$env.VAR}}`	`{{$env.API_KEY}}` → `FLOW_TEST_API_KEY`
Faker	`{{$faker.x.y}}`	`{{$faker.internet.email}}`
JavaScript	`{{$js:expr}}`	`{{$js:Date.now()}}`

Faker.js Top 10

{{$faker.person.fullName}}              # John Doe
{{$faker.internet.email}}               # john@example.com
{{$faker.phone.number}}                 # +1234567890
{{$faker.string.uuid}}                  # 123e4567-e89b...
{{$faker.location.city}}                # New York
{{$faker.commerce.price}}               # 49.99
{{$faker.date.recent}}                  # 2024-01-15
{{$faker.lorem.sentence}}               # Lorem ipsum dolor...
{{$faker.number.int({min: 1, max: 100})}}  # 42
{{$faker.company.name}}                 # Acme Corp

✅ Assertions - Top 15 Operadores

assert:
  status_code: 200                      # Shorthand

  body:
    id: {exists: true}                  # Campo existe
    name: {equals: "John"}              # Igualdade
    email: {regex: "^[\\w.-]+@"}        # Pattern
    age: {greater_than: 18}             # Numérico >
    score: {less_than: 100}             # Numérico <
    status: {in: ["active", "pending"]} # Está na lista
    role: {not_equals: "admin"}         # Diferente
    bio: {contains: "developer"}        # Substring
    errors: {not_exists: true}          # Campo não existe
    data: {type: "array"}               # Tipo de dados
    items: {length: {greater_than: 0}}  # Array/string length
    description: {notEmpty: true}       # Não vazio
    phone: {pattern: "\\d{10}"}         # Pattern (alias)
    username: {minLength: 3}            # Tamanho mínimo

  response_time_ms:
    less_than: 2000

📦 Capture (JMESPath)

capture:
  # Básico
  token: "body.access_token"
  user_id: "body.user.id"

  # Array
  first_item: "body.items[0]"
  last_item: "body.items[-1]"
  all_ids: "body.data[*].id"

  # Filtros
  active_users: "body.users[?status=='active']"

  # Projeção customizada
  user_list: "body.users[*].{id: id, name: name}"

  # Funções
  count: "length(body.items)"
  max_price: "max(body.prices)"

  # Completo (debug)
  full_response: "@"

🔁 Iteração

Array

- name: "Process {{item.name}}"
  iterate:
    over: "{{items_array}}"
    as: "item"
  request:
    method: POST
    url: "/process"
    body:
      id: "{{item.id}}"

Range

- name: "Page {{page}}"
  iterate:
    range: "1..10"
    as: "page"
  request:
    method: GET
    url: "/items?page={{page}}"

🔀 Cenários Condicionais

scenarios:
  - condition: "status_code == `200`"
    then:
      assert:
        body:
          success: {equals: true}
      capture:
        result: "body.data"

  - condition: "status_code >= `400`"
    then:
      assert:
        body:
          error: {exists: true}

💬 Input Interativo

input:
  prompt: "Enter value:"
  variable: "user_input"
  type: "text"                          # text|password|number|select|confirm
  required: true
  default: "default_value"
  ci_default: "ci_value"                # Para CI/CD
  timeout_seconds: 60
  validation:
    min_length: 3
    pattern: "^[a-z]+$"

Select com opções

input:
  type: "select"
  options:
    - {value: "opt1", label: "Option 1"}
    - {value: "opt2", label: "Option 2"}
  # Ou de variável
  options: "{{list_from_api}}"
  value_path: "id"
  label_path: "name"

🔗 Call Cross-Suite

call:
  test: "../auth/login.yaml"
  step: "login-step"
  variables:
    username: "{{user}}"
  isolate_context: true                 # true|false
  on_error: "fail"                      # fail|continue|warn

⚙️ Configurações Úteis

Retry

metadata:
  retry:
    max_attempts: 3
    delay_ms: 1000

Timeout

metadata:
  timeout: 10000              # Step timeout
request:
  timeout: 5000               # Request timeout

Continue em Falha

continue_on_failure: true

🎯 Comandos CLI Essenciais

# Executar teste
npx flow-test-engine tests/suite.yaml

# Com prioridade
npx flow-test-engine --priority critical,high

# Com tags
npx flow-test-engine --tags smoke,auth

# Dry run (apenas planejar)
npx flow-test-engine --dry-run tests/suite.yaml

# Verbose (logs detalhados)
npx flow-test-engine --verbose tests/suite.yaml

# Listar testes
npx flow-test-engine --list

# Gerar relatório HTML
npm run report:html

🐛 Debug Rápido

# Capturar tudo para debug
capture:
  debug_full: "@"
  debug_status: "status"
  debug_body: "body"

# Variável computada para debug
computed:
  debug_time: "{{$js:new Date().toISOString()}}"

📊 Response Object

{
  status: 200,                // Código HTTP
  headers: {...},             // Headers
  body: {...},                // Corpo parseado
  response_time_ms: 123       // Tempo de resposta
}

🚦 Tipos de Dados para Assertions

"string" - Texto
"number" - Número
"boolean" - Bool
"array" - Lista
"object" - Objeto
"null" - Nulo

💡 Boas Práticas

✅ DO:

IDs únicos em node_id e step_id
ci_default em todos inputs
Validar responses com assertions
Usar exports para compartilhar
Adicionar description em steps complexos

❌ DON’T:

Parallel com input interativo
Dependências circulares
Timeouts muito curtos
Ignorar falhas sem motivo
Capturar dados sensíveis

🔍 Troubleshooting Top 5

Erro	Fix
Variable not found	Definir ou capturar antes
JMESPath failed	Testar em jmespath.org
URL error	Verificar base_url
Timeout	Aumentar timeout
Circular dependency	Revisar depends

📚 Recursos

Docs: /docs/YAML-API-REFERENCE.md
Exemplos: /tests directory
GitHub: https://github.com/marcuspmd/flow-test

Quick Reference v1.0 | Imprima e cole na parede! 📌