Flow Test Engine - YAML API Reference

Versão: 1.0 Última Atualização: 10 de outubro de 2025 Status: Documentação Completa ✅

📚 Índice Navegável

🏗️ Estrutura e Configuração

• 1. TestSuite (Estrutura Base)
• 2. TestStep (Propriedades dos Steps)
• 16. Execution Modes
• 17. Priority Levels
• 18. Tags

🔄 Variáveis e Interpolação

• 3. Sistema de Interpolação
  • 3.1 Sintaxe Básica
  • 3.2 Faker.js
  • 3.3 JavaScript Expressions
• 14. Escopo de Variáveis

✅ Validação e Assertions

• 4. Assertions (Validações)
  • 4.1 Estrutura
  • 4.2 Operadores
  • 4.3 Tipos Suportados
  • 4.4 Validação de Length
  • 4.5 Custom Assertions
• 5. Extração de Dados (JMESPath)

💬 Input e Interação

• 6. Input Interativo
  • 6.1 Propriedades
  • 6.2 Tipos de Input
  • 6.3 Options
  • 6.4 Validação

🔁 Controle de Fluxo

• 7. Iteração
  • 7.1 Array Iteration
  • 7.2 Range Iteration
• 8. Cenários Condicionais
• 9. Step Call Cross-Suite

⚙️ Configurações Avançadas

• 10. Tipos de Dados
• 11. Retry
• 12. Timeouts
• 13. URLs
• 15. Response Structure

� Diagramas e Visualizações

• 19. Diagramas e Fluxos
  • 19.1 Fluxo de Execução Geral
  • 19.2 Fluxo de Variáveis
  • 19.3 Interpolação
  • 19.4 Cenários Condicionais
  • 19.5 Iteração
  • 19.6 Dependency Resolution
  • 19.7 Step Call
  • 19.8 Retry Logic

�📖 Exemplos e Ajuda

• 20. Exemplos Práticos
• 21. Troubleshooting
• 22. Limitações

🚀 Quick Start

Estrutura Mínima

node_id: "meu-teste"
suite_name: "Meu Primeiro Teste"
base_url: "https://api.example.com"

steps:
  - name: "Fazer requisição"
    request:
      method: GET
      url: "/endpoint"
    assert:
      status_code: 200

Exemplo Completo

node_id: "user-management"
suite_name: "User Management Tests"
base_url: "{{api_base_url}}"
execution_mode: "sequential"

metadata:
  priority: "high"
  tags: ["users", "crud"]
  timeout: 30000

variables:
  test_user_email: "{{$faker.internet.email}}"

exports: ["created_user_id"]

depends:
  - path: "./auth-setup.yaml"
    required: true

steps:
  - name: "Create user"
    request:
      method: POST
      url: "/users"
      headers:
        Authorization: "Bearer {{auth-setup.token}}"
      body:
        email: "{{test_user_email}}"
        name: "{{$faker.person.fullName}}"
    assert:
      status_code: 201
      body:
        id: {exists: true}
        email: {equals: "{{test_user_email}}"}
    capture:
      created_user_id: "body.id"

1. TestSuite (Estrutura Base)

Propriedades Principais

Suite Metadata

metadata:
  priority: "critical"        # critical|high|medium|low
  tags: ["smoke", "auth"]     # Categorização
  timeout: 30000              # Timeout geral em ms
  estimated_duration_ms: 5000 # Duração estimada
  requires_user_input: false  # Flag para inputs

Flow Dependency

depends:
  # Caminho relativo (padrão)
  - path: "./auth/login.yaml"
    required: true
    cache: 300  # TTL em segundos

  # Caminho absoluto (a partir de test_directory)
  - path: "common/setup.yaml"
    path_type: "absolute"
    required: true

  # Por node_id
  - node_id: "auth-setup"
    cache: true

  # Com condição
  - path: "./optional.yaml"
    condition: "environment == 'dev'"

  # Com variáveis e retry
  - path: "./database-setup.yaml"
    variables:
      db_name: "test_db"
    retry:
      max_attempts: 3
      delay_ms: 1000

2. TestStep (Propriedades dos Steps)

Propriedades Principais

*request é opcional apenas se houver input ou call

Request Details

request:
  method: POST              # GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS
  url: "/api/users"         # Absoluta ou relativa
  headers:
    Content-Type: "application/json"
    Authorization: "Bearer {{token}}"
  body:
    name: "John Doe"
    email: "john@example.com"
  params:                   # Query string
    page: 1
    limit: 10
  timeout: 30000            # ms

Step Metadata

metadata:
  priority: "high"
  tags: ["critical"]
  timeout: 10000
  retry:
    max_attempts: 3
    delay_ms: 1000
  depends_on: ["step-1", "step-2"]
  description: "Creates user account"
  skip: "{{environment}} === 'prod'"  # Condição para pular

3. Sistema de Interpolação

3.1 Sintaxe e Fontes

3.2 Faker.js - Categorias Principais

variables:
  user_email: "{{$faker.internet.email}}"           # test@example.com
  user_name: "{{$faker.person.fullName}}"           # John Doe
  user_phone: "{{$faker.phone.number}}"             # +1234567890
  product_price: "{{$faker.commerce.price}}"        # 49.99
  uuid: "{{$faker.string.uuid}}"                    # 123e4567-e89b...
  random_int: "{{$faker.number.int({min: 1, max: 100})}}"  # 42

3.3 JavaScript Expressions

computed:
  timestamp: "{{$js:Date.now()}}"                   # 1704110400000
  iso_date: "{{$js:new Date().toISOString()}}"      # 2024-01-01T12:00:00.000Z
  random: "{{$js:Math.random()}}"                   # 0.123456789
  calculation: "{{$js:{{price}} * {{quantity}}}}"   # Resultado do cálculo
  rounded: "{{$js:Math.round({{value}}\)}}}"        # Valor arredondado
  base64: "{{$js:Buffer.from('text').toString('base64')}}"  # dGV4dA==
  json_parse: "{{$js:JSON.parse('{{json_string}}')}}"       # Objeto parseado

4. Assertions (Validações)

4.1 Estrutura de Assertions

assert:
  # Shorthand para status
  status_code: 200

  # Validações do body
  body:
    user.id: {exists: true, type: "number"}
    user.email: {regex: "^[\\w.-]+@[\\w.-]+\\.\\w+$"}
    items: {length: {greater_than: 0}}

  # Headers
  headers:
    content-type: {contains: "json"}

  # Response time
  response_time_ms:
    less_than: 2000
    greater_than: 10

  # Custom
  custom:
    - name: "Valid ID"
      condition: "body.id > 0"
      message: "ID must be positive"

4.2 Operadores de Asserção (AssertionChecks)

4.3 Tipos Suportados

• "string" - Texto
• "number" - Número (int/float)
• "boolean" - Booleano
• "array" - Lista
• "object" - Objeto
• "null" - Nulo

4.4 Validação de Length

body:
  items:
    length:
      equals: 10              # Exatamente 10
      greater_than: 0         # Mais de 0
      less_than: 100          # Menos de 100
      greater_than_or_equal: 5
      less_than_or_equal: 50

4.5 Custom Assertions

custom:
  - name: "Valid user ID format"
    condition: "body.user.id && typeof body.user.id === 'number'"
    message: "User ID must be a number"

  - name: "Email matches username"
    condition: "body.email.startsWith(body.username)"
    message: "Email should start with username"

5. Extração de Dados - Capture (JMESPath)

Sintaxe Básica

Operações Avançadas

capture:
  # Filtros
  active_users: "users[?status=='active']"
  expensive_items: "items[?price > `100`]"

  # Projeções customizadas
  user_list: "users[*].{id: id, name: name, email: email}"

  # Funções
  total_count: "length(items)"
  max_price: "max(products[*].price)"
  min_price: "min(products[*].price)"

  # Ordenação
  sorted_items: "sort_by(items, &created_at)"

  # Flatten
  all_tags: "posts[].tags[]"

  # Pipes
  first_five: "items | [0:5]"

  # Contains
  has_admin: "contains(roles, 'admin')"

6. Input Interativo (InputConfig)

6.1 Propriedades Base

input:
  prompt: "Enter your API key:"       # OBRIGATÓRIO
  variable: "api_key"                  # OBRIGATÓRIO
  type: "password"                     # OBRIGATÓRIO
  description: "API key for auth"
  default: "default_value"
  placeholder: "sk-..."
  required: true
  style: "boxed"                       # simple|boxed|highlighted
  timeout_seconds: 60
  condition: "{{status}} == 200"
  ci_default: "{{$env.CI_API_KEY}}"
  validation: {...}
  dynamic: {...}
  options: [...]                       # Para select/multiselect

6.2 Tipos de Input

6.3 Options para Select

# Estático
options:
  - {value: "dev", label: "Development"}
  - {value: "prod", label: "Production"}

# De variável
options: "{{environments}}"
value_path: "id"
label_path: "name"

# JMESPath
options: "{{users[*].{value: id, label: name}}}"

6.4 Input Validation

validation:
  min_length: 5
  max_length: 100
  pattern: "^[a-zA-Z0-9]+$"
  min: 0
  max: 100
  custom_validation: "value.length > 3"
  expressions:
    - name: "Valid format"
      expression: "value.startsWith('sk-')"
      message: "Must start with sk-"
      severity: "error"      # error|warning

7. Iteração (IterationConfig)

7.1 Array Iteration

- name: "Process {{user.name}}"
  iterate:
    over: "{{test_users}}"    # Array ou expressão
    as: "user"                # Nome da variável
  request:
    method: POST
    url: "/users"
    body:
      name: "{{user.name}}"
      email: "{{user.email}}"

7.2 Range Iteration

- name: "Test page {{page}}"
  iterate:
    range: "1..10"            # start..end (inclusive)
    as: "page"
  request:
    method: GET
    url: "/items?page={{page}}"

Iteration Context

Durante a iteração, estão disponíveis:

• {{<as_variable>}} - Valor atual
• _iteration.index - Índice (0-based)
• _iteration.isFirst - Primeira iteração
• _iteration.isLast - Última iteração

8. Cenários Condicionais (ConditionalScenario)

scenarios:
  - name: "Success path"
    condition: "status_code == `200`"  # JMESPath
    then:
      assert:
        body:
          success: {equals: true}
      capture:
        result_id: "body.id"
      variables:
        operation_succeeded: true
      steps:                             # Apenas em 'then'
        - name: "Verify result"
          request:
            method: GET
            url: "/verify/{{result_id}}"

  - name: "Error path"
    condition: "status_code >= `400`"
    then:
      assert:
        body:
          error: {exists: true}
      variables:
        operation_failed: true
    else:
      variables:
        operation_succeeded: true

Operadores em Condições

• ==, != - Igualdade
• <, <=, >, >= - Comparação
• && - E lógico
• || - OU lógico
• ! - Negação

Literais numéricos: `200` Strings: 'text'

9. Step Call Cross-Suite (StepCallConfig)

call:
  test: "../auth/login.yaml"          # Caminho do arquivo
  path_type: "relative"                # relative|absolute
  step: "login-step"                   # ID ou nome do step
  variables:                           # Injetar variáveis
    username: "{{test_user}}"
    password: "{{test_pass}}"
  isolate_context: true                # Namespace de variáveis
  on_error: "fail"                     # fail|continue|warn
  timeout: 30000
  retry:
    max_attempts: 3
    delay_ms: 1000

Comportamento de Isolamento

10. Tipos de Dados e Valores Especiais

Primitivos

variables:
  text: "Hello"              # string
  number: 42                 # number
  decimal: 3.14              # number
  active: true               # boolean
  empty: null                # null
  list: [1, 2, 3]            # array
  object:                    # object
    key: "value"

Response Object

{
  status: 200,               // Código HTTP
  status_code: 200,          // Alias
  headers: {...},            // Headers da resposta
  body: {...},               // Corpo parseado
  data: {...},               // Alias para body (axios)
  response_time_ms: 123      // Tempo de resposta
}

11. Configuração de Retry

# No step metadata
metadata:
  retry:
    max_attempts: 3
    delay_ms: 1000

# Em dependency
depends:
  - path: "./setup.yaml"
    retry:
      max_attempts: 2
      delay_ms: 500

# Em call
call:
  test: "./external.yaml"
  step: "api-call"
  retry:
    max_attempts: 5
    delay_ms: 2000

12. Timeouts

13. Resolução de URLs

14. Escopo de Variáveis

Ordem de Precedência (maior → menor)

1. Variáveis runtime (step atual)
2. Variáveis de iteração (as)
3. Variáveis locais
4. Variáveis de dependencies
5. Variáveis globais (exports)
6. Variáveis de ambiente

15. Response Object Structure

interface Response {
  status: number;              // 200, 404, etc.
  status_code: number;         // Alias
  headers: Record<string, string>;
  body: any;                   // JSON parseado ou string
  data: any;                   // Alias para body
  response_time_ms: number;    // Tempo de resposta
}

16. Execution Modes

17. Priority Levels

npx flow-test-engine --priority critical,high

18. Tags

Exemplos comuns:

• smoke, regression, auth
• api, e2e, integration
• performance, security

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

19. Diagramas e Fluxos de Execução

19.1 Fluxo de Execução Geral

┌─────────────────────────────────────────────────────────────────┐
│                    FLOW TEST ENGINE                             │
│                     Ciclo de Vida                               │
└─────────────────────────────────────────────────────────────────┘

    ┌──────────────┐
    │   Discovery  │  1. Descobre arquivos .yaml
    │   (Config)   │  2. Valida estrutura
    └──────┬───────┘  3. Resolve dependências
           │
           ▼
    ┌──────────────┐
    │ Dependency   │  4. Ordena por depends
    │  Resolution  │  5. Detecta ciclos
    └──────┬───────┘  6. Valida cache
           │
           ▼
    ┌──────────────┐
    │  Variables   │  7. Carrega env vars
    │    Setup     │  8. Inicializa variables
    └──────┬───────┘  9. Processa Faker/JS
           │
           ▼
    ┌──────────────┐
    │ Step-by-Step │  10. Executa cada step
    │  Execution   │  11. Interpola variáveis
    └──────┬───────┘  12. HTTP request
           │
           ├──────────────┐
           │              ▼
           │       ┌──────────────┐
           │       │  Assertions  │  13. Valida status
           │       │  Validation  │  14. Valida body
           │       └──────┬───────┘  15. Valida headers
           │              │
           │              ▼
           │       ┌──────────────┐
           │       │   Capture    │  16. Extrai dados (JMESPath)
           │       │   & Export   │  17. Armazena variáveis
           │       └──────┬───────┘  18. Exporta globais
           │              │
           │              ▼
           │       ┌──────────────┐
           │       │  Scenarios   │  19. Avalia condições
           │       │  Evaluation  │  20. Executa then/else
           │       └──────────────┘
           │
           ▼
    ┌──────────────┐
    │   Reporting  │  21. Gera resultados JSON
    │  Generation  │  22. Cria relatório HTML
    └──────────────┘  23. Exibe sumário

19.2 Fluxo de Variáveis

┌──────────────────────────────────────────────────────────────────┐
│               ESCOPO E PRECEDÊNCIA DE VARIÁVEIS                  │
└──────────────────────────────────────────────────────────────────┘

Precedência (do maior para o menor):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. ┌─────────────────────────┐  ← MAIOR PRIORIDADE
   │   Runtime Variables     │
   │   (step atual)          │
   │   • capture: {...}      │
   │   • computed: {...}     │
   └─────────────────────────┘

2. ┌─────────────────────────┐
   │  Iteration Variables    │
   │  (durante loop)         │
   │  • as: "item"           │
   │  • _iteration.index     │
   └─────────────────────────┘

3. ┌─────────────────────────┐
   │   Suite Variables       │
   │   (locais)              │
   │   variables:            │
   │     user_id: 123        │
   └─────────────────────────┘

4. ┌─────────────────────────┐
   │  Dependency Variables   │
   │  (de depends)           │
   │  {{suite-id.var}}       │
   └─────────────────────────┘

5. ┌─────────────────────────┐
   │   Global Variables      │
   │   (exports)             │
   │   {{suite-id.var}}      │
   └─────────────────────────┘

6. ┌─────────────────────────┐  ← MENOR PRIORIDADE
   │  Environment Variables  │
   │  (sistema)              │
   │  {{$env.VAR}}           │
   └─────────────────────────┘

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Fluxo de Dados:
───────────────

Suite A                    Suite B
  ↓                          ↓
variables:            depends: [Suite A]
  local_var: 1              ↓
  ↓                    {{suite-a.exported}}
exports: [exported]         ↓
  ↓                    variables:
capture:                    uses_export: true
  api_result: "..."         ↓
  ↓                    steps: [...]
{{api_result}}

19.3 Interpolação de Variáveis - Processo

┌──────────────────────────────────────────────────────────────────┐
│            PROCESSO DE INTERPOLAÇÃO {{variable}}                 │
└──────────────────────────────────────────────────────────────────┘

Input String:
"Hello {{user.name}}, your ID is {{user_id}}"
       ↓
┌──────────────────────┐
│  1. Detecção         │  Regex: /\{\{([^}]+)\}\}/g
│     de Padrões       │  Encontra: ["{{user.name}}", "{{user_id}}"]
└──────┬───────────────┘
       │
       ▼
┌──────────────────────┐
│  2. Classificação    │  user.name → Objeto aninhado
│     de Tipo          │  user_id   → Variável simples
└──────┬───────────────┘
       │
       ├──────────────────────┬────────────────────┐
       ▼                      ▼                    ▼
┌──────────────┐   ┌──────────────┐    ┌──────────────┐
│ Variável     │   │  Ambiente    │    │   Faker.js   │
│ Simples      │   │  $env.VAR    │    │ $faker.x.y   │
└──────┬───────┘   └──────┬───────┘    └──────┬───────┘
       │                  │                    │
       ▼                  ▼                    ▼
┌──────────────┐   ┌──────────────┐    ┌──────────────┐
│ Cross-Suite  │   │  JavaScript  │    │   JMESPath   │
│ suite.var    │   │  $js:expr    │    │  (capture)   │
└──────┬───────┘   └──────┬───────┘    └──────┬───────┘
       │                  │                    │
       └──────────────────┴────────────────────┘
                         │
                         ▼
              ┌─────────────────────┐
              │  3. Resolução       │
              │     de Valor        │
              │  • Busca em escopo  │
              │  • Executa função   │
              │  • Avalia expressão │
              └──────────┬──────────┘
                         │
                         ▼
              ┌─────────────────────┐
              │  4. Substituição    │
              │     no String       │
              └──────────┬──────────┘
                         │
                         ▼
Output String:
"Hello John Doe, your ID is 12345"

19.4 Fluxo de Cenários Condicionais

┌──────────────────────────────────────────────────────────────────┐
│                    CENÁRIOS CONDICIONAIS                         │
└──────────────────────────────────────────────────────────────────┘

Step Executado
     │
     ▼
┌─────────────────┐
│ HTTP Response   │
│ {status: 200,   │
│  body: {...}}   │
└────────┬────────┘
         │
         ▼
┌─────────────────────────────────────┐
│  Cenário 1: Success Path            │
│  condition: "status_code == `200`"  │
└────────┬────────────────────────────┘
         │
         ├── Avalia → TRUE ──┐
         │                   ▼
         │           ┌───────────────┐
         │           │  then:        │
         │           │  • assert     │
         │           │  • capture    │
         │           │  • variables  │
         │           │  • steps[]    │
         │           └───────────────┘
         │
         └── Avalia → FALSE
                     │
                     ▼
         ┌─────────────────────────────────────┐
         │  Cenário 2: Error Path              │
         │  condition: "status_code >= `400`"  │
         └────────┬────────────────────────────┘
                  │
                  ├── Avalia → TRUE ──┐
                  │                   ▼
                  │           ┌───────────────┐
                  │           │  then:        │
                  │           │  • assert     │
                  │           │  • variables  │
                  │           └───────┬───────┘
                  │                   │
                  │           ┌───────────────┐
                  │           │  else:        │
                  │           │  (opcional)   │
                  │           └───────────────┘
                  │
                  └── Avalia → FALSE
                              │
                              ▼
                  Próximo Step ou Fim

19.5 Iteração - Fluxo

┌──────────────────────────────────────────────────────────────────┐
│                      ITERAÇÃO (LOOP)                             │
└──────────────────────────────────────────────────────────────────┘

┌─────────────────┐
│  iterate:       │
│    over: arr    │  Array: [item1, item2, item3]
│    as: "item"   │  ou
└────────┬────────┘  Range: "1..5"
         │
         ▼
┌─────────────────────────────────────────┐
│  Iteration Context Setup                │
│  • index = 0                            │
│  • isFirst = true                       │
│  • isLast = false                       │
│  • variableName = "item"                │
│  • value = <current>                    │
└────────┬────────────────────────────────┘
         │
    ╔════▼════════════════════════════════════╗
    ║  Loop Iteration N                       ║
    ║                                         ║
    ║  Variables Available:                   ║
    ║  • {{item}} = current value             ║
    ║  • {{_iteration.index}} = N             ║
    ║  • {{_iteration.isFirst}} = boolean     ║
    ║  • {{_iteration.isLast}} = boolean      ║
    ║                                         ║
    ║  ┌─────────────────────────────┐       ║
    ║  │  1. Interpola variáveis     │       ║
    ║  │     com contexto atual      │       ║
    ║  └──────────┬──────────────────┘       ║
    ║             ▼                           ║
    ║  ┌─────────────────────────────┐       ║
    ║  │  2. Executa Request         │       ║
    ║  └──────────┬──────────────────┘       ║
    ║             ▼                           ║
    ║  ┌─────────────────────────────┐       ║
    ║  │  3. Assertions              │       ║
    ║  └──────────┬──────────────────┘       ║
    ║             ▼                           ║
    ║  ┌─────────────────────────────┐       ║
    ║  │  4. Capture                 │       ║
    ║  │     "result_{{index}}"      │       ║
    ║  └─────────────────────────────┘       ║
    ╚═════════════════════════════════════════╝
         │
         ├─── Mais itens? → Sim ──┐
         │                        │
         │                        └─→ Loop++
         │
         └─── Não mais itens
              │
              ▼
         Próximo Step

19.6 Dependency Resolution

┌──────────────────────────────────────────────────────────────────┐
│                  RESOLUÇÃO DE DEPENDÊNCIAS                       │
└──────────────────────────────────────────────────────────────────┘

Suites Descobertas:
  • suite-a.yaml
  • suite-b.yaml
  • suite-c.yaml
  • suite-d.yaml

Dependências Declaradas:
  suite-b → depends: [suite-a]
  suite-c → depends: [suite-a, suite-b]
  suite-d → depends: [suite-c]

         ┌─────────────────┐
         │   DAG Builder   │  (Directed Acyclic Graph)
         └────────┬────────┘
                  │
                  ▼
         ┌─────────────────┐
         │ Cycle Detection │  Verifica loops
         └────────┬────────┘
                  │
                  ├─── Ciclo? → Sim → ❌ ERROR
                  │
                  └─── Não
                       │
                       ▼
         ┌─────────────────────┐
         │ Topological Sort    │
         └────────┬────────────┘
                  │
                  ▼

Ordem de Execução:

Level 0:  ┌───────────┐
          │  suite-a  │  (sem dependências)
          └─────┬─────┘
                │
                ▼
Level 1:  ┌───────────┐
          │  suite-b  │  (depende de suite-a)
          └─────┬─────┘
                │
                ▼
Level 2:  ┌───────────┐
          │  suite-c  │  (depende de suite-a + suite-b)
          └─────┬─────┘
                │
                ▼
Level 3:  ┌───────────┐
          │  suite-d  │  (depende de suite-c)
          └───────────┘

Cache Strategy:
──────────────
┌─────────────────────────────────────────┐
│ suite-a executa → exports cached        │
│    ↓                                    │
│ suite-b usa cache → não reexecuta       │
│    ↓                                    │
│ suite-c usa cache → não reexecuta       │
└─────────────────────────────────────────┘

19.7 Step Call Cross-Suite

┌──────────────────────────────────────────────────────────────────┐
│                    STEP CALL CROSS-SUITE                         │
└──────────────────────────────────────────────────────────────────┘

Suite Caller (main.yaml)
     │
     ▼
┌─────────────────────────────────────┐
│  Step com call:                     │
│    call:                            │
│      test: "./auth/login.yaml"      │
│      step: "login-step"             │
│      variables:                     │
│        user: "{{test_user}}"        │
│      isolate_context: true          │
└────────┬────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────┐
│  1. Resolve Path                    │
│     Relativo ou Absoluto            │
└────────┬────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────┐
│  2. Load Target Suite               │
│     (auth/login.yaml)               │
└────────┬────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────┐
│  3. Find Step by ID                 │
│     step_id: "login-step"           │
└────────┬────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────┐
│  4. Inject Variables                │
│     Mescla com contexto             │
└────────┬────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────┐
│  5. Execute Step                    │
│     • Request                       │
│     • Assertions                    │
│     • Captures                      │
└────────┬────────────────────────────┘
         │
         ├────── isolate_context: true ──┐
         │                                ▼
         │                    ┌────────────────────────┐
         │                    │  Variáveis em          │
         │                    │  namespace:            │
         │                    │  {{step-id.variable}}  │
         │                    └────────────────────────┘
         │
         └────── isolate_context: false ─┐
                                          ▼
                              ┌────────────────────────┐
                              │  Variáveis mesclam    │
                              │  diretamente no       │
                              │  escopo do caller     │
                              └────────────────────────┘
         │
         ▼
Continua execução em Suite Caller

19.8 Retry Logic

┌──────────────────────────────────────────────────────────────────┐
│                      RETRY MECHANISM                             │
└──────────────────────────────────────────────────────────────────┘

Step com Retry:
  metadata:
    retry:
      max_attempts: 3
      delay_ms: 1000

┌─────────────────┐
│  Attempt 1      │
└────────┬────────┘
         │
         ├─── ✅ Success → Continue
         │
         └─── ❌ Failure
              │
              ▼
         ┌─────────────┐
         │  Delay      │  Wait 1000ms
         └──────┬──────┘
                │
                ▼
         ┌─────────────────┐
         │  Attempt 2      │
         └────────┬────────┘
                  │
                  ├─── ✅ Success → Continue
                  │
                  └─── ❌ Failure
                       │
                       ▼
                  ┌─────────────┐
                  │  Delay      │  Wait 1000ms
                  └──────┬──────┘
                         │
                         ▼
                  ┌─────────────────┐
                  │  Attempt 3      │  (max_attempts)
                  └────────┬────────┘
                           │
                           ├─── ✅ Success → Continue
                           │
                           └─── ❌ Failure
                                │
                                ▼
                           ❌ FINAL ERROR
                           (max attempts reached)

Retry aplicável em:
  • Request HTTP (timeout, 5xx errors)
  • Dependencies (falha na execução)
  • Step Call (erro no step chamado)

20. Exemplos Práticos Completos

20.1 Autenticação Básica

node_id: "auth-basic"
suite_name: "Basic Authentication"
base_url: "{{api_url}}"

variables:
  username: "{{$env.TEST_USERNAME}}"
  password: "{{$env.TEST_PASSWORD}}"

exports: ["auth_token"]

steps:
  - name: "Login"
    request:
      method: POST
      url: "/auth/login"
      body:
        username: "{{username}}"
        password: "{{password}}"
    assert:
      status_code: 200
      body:
        token: {exists: true}
    capture:
      auth_token: "body.token"

20.2 CRUD Completo

node_id: "user-crud"
suite_name: "User CRUD Operations"
base_url: "{{api_url}}"

depends:
  - path: "./auth-basic.yaml"

variables:
  test_user:
    name: "{{$faker.person.fullName}}"
    email: "{{$faker.internet.email}}"

steps:
  # Create
  - name: "Create user"
    request:
      method: POST
      url: "/users"
      headers:
        Authorization: "Bearer {{auth-basic.auth_token}}"
      body:
        name: "{{test_user.name}}"
        email: "{{test_user.email}}"
    assert:
      status_code: 201
      body:
        id: {exists: true}
    capture:
      user_id: "body.id"

  # Read
  - name: "Get user"
    request:
      method: GET
      url: "/users/{{user_id}}"
      headers:
        Authorization: "Bearer {{auth-basic.auth_token}}"
    assert:
      status_code: 200
      body:
        id: {equals: "{{user_id}}"}
        email: {equals: "{{test_user.email}}"}

  # Update
  - name: "Update user"
    request:
      method: PUT
      url: "/users/{{user_id}}"
      headers:
        Authorization: "Bearer {{auth-basic.auth_token}}"
      body:
        name: "Updated Name"
    assert:
      status_code: 200

  # Delete
  - name: "Delete user"
    request:
      method: DELETE
      url: "/users/{{user_id}}"
      headers:
        Authorization: "Bearer {{auth-basic.auth_token}}"
    assert:
      status_code: 204

20.3 Data-Driven Testing

node_id: "validation-test"
suite_name: "Email Validation Tests"
base_url: "{{api_url}}"

variables:
  test_cases:
    - {email: "valid@example.com", expected: 200}
    - {email: "invalid", expected: 400}
    - {email: "", expected: 400}
    - {email: "no-at-sign.com", expected: 400}

steps:
  - name: "Test: {{test.email}}"
    iterate:
      over: "{{test_cases}}"
      as: "test"
    request:
      method: POST
      url: "/validate-email"
      body:
        email: "{{test.email}}"
    assert:
      status_code: "{{test.expected}}"

21. Guia de Troubleshooting

Problemas Comuns

Debug Tips

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

# Assertions verbosas
assert:
  custom:
    - name: "Debug"
      condition: "body"
      message: "Response: {{body}}"

CLI Úteis

# Dry run
npx flow-test-engine --dry-run tests/suite.yaml

# Verbose
npx flow-test-engine --verbose tests/suite.yaml

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

22. Limitações Conhecidas

| Assertion failed | Adicionar scenarios para múltiplos casos | | Timeout exceeded | Aumentar timeout | | Circular dependency | Revisar cadeia de depends | | Input timeout | Definir ci_default e timeout_seconds | | Iteration failed | Validar array não está vazio |

Debug Tips

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

# Assertions verbosas
assert:
  custom:
    - name: "Debug"
      condition: "body"
      message: "Response: {{body}}"

CLI Úteis

# Dry run
npx flow-test-engine --dry-run tests/suite.yaml

# Verbose
npx flow-test-engine --verbose tests/suite.yaml

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

22. Limitações Conhecidas

Técnicas

Boas Práticas

✅ DO:

• Usar node_id únicos
• Definir ci_default para inputs
• Capturar variáveis essenciais
• Validar com múltiplas assertions

❌ DON’T:

• Parallel com input
• Dependências circulares
• Timeouts muito curtos em CI
• Ignorar falhas sem motivo

📚 Recursos Adicionais

• Repositório: https://github.com/marcuspmd/flow-test
• Exemplos: /tests directory
• Issues: GitHub Issues
• Wiki: GitHub Wiki

Flow Test Engine v1.0 - Documentação Oficial Copyright © 2025 - Todos os direitos reservados