Propriedades do Flow Test Engine

Índice

Estrutura e Configuração

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

Variáveis e Interpolação

• 3. Sistema de Interpolação de Variáveis
• 14. Escopo de Variáveis

Validação e Assertions

• 4. Assertions (Validações)
• 5. Extração de Dados - Capture (JMESPath)

Input e Interação

• 6. Input Interativo (InputConfig)

Controle de Fluxo

• 7. Iteração (IterationConfig)
• 8. Cenários Condicionais
• 9. Step Call Cross-Suite

Configurações Avançadas

• 10. Tipos de Dados e Valores Especiais
• 11. Configuração de Retry
• 12. Timeouts
• 13. Resolução de URLs
• 15. Response Object Structure

Exemplos e Troubleshooting

• 19. Exemplos Práticos Completos
• 20. Guia de Troubleshooting
• 21. Limitações Conhecidas

Descrição

Este documento descreve o processo de documentação abrangente de todas as propriedades técnicas do projeto Flow Test Engine, um motor de testes de API baseado em YAML que executa flows declarativos com recursos avançados de automação, relatórios e integração.

Objetivo

Criar uma documentação técnica completa que cubra todas as propriedades, tipos de dados, capacidades de interpolação, operadores, e funcionalidades do Flow Test Engine, facilitando o desenvolvimento, manutenção e uso correto do framework.

Contexto do Projeto

• Framework: Flow Test Engine (TypeScript/Node.js)
• Propósito: Motor de testes de API com execução declarativa via YAML
• Arquitetura: Services modulares com suporte a interpolação avançada, asserções, captura de dados e relatórios
• Formato Principal: YAML para definição de suites de teste

Referência Completa de Propriedades YAML

1. Estrutura Base do YAML (TestSuite)

1.1 Metadata da Suite

1.2 Flow Dependency (FlowDependency)

Nota: Deve fornecer path OU node_id, não ambos.

2. Propriedades dos Steps (TestStep)

Nota: request é opcional apenas se o step contém apenas input ou call.

2.1 Request Details (RequestDetails)

2.2 Step Metadata (TestStepMetadata)

3. Sistema de Interpolação de Variáveis

3.1 Sintaxe e Fontes

3.2 Faker.js - Categorias Principais

3.3 JavaScript Expressions

4. Assertions (Validações)

4.1 Estrutura de Assertions

4.2 Operadores de Asserção (AssertionChecks)

4.3 Tipos Suportados

4.4 Validação de Length

# Length com operators aninhados
body:
  items:
    length:
      equals: 10              # Exatamente 10 itens
      greater_than: 0         # Mais de 0
      less_than: 100          # Menos de 100
      greater_than_or_equal: 5  # 5 ou mais
      less_than_or_equal: 50    # 50 ou menos

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"

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

5.1 Sintaxe Básica

5.2 Operações Avançadas JMESPath

5.3 Exemplos Práticos de Capture

capture:
  # Simples
  token: "body.access_token"
  user_id: "body.user.id"

  # Arrays
  first_item_name: "body.items[0].name"
  all_ids: "body.data[*].id"

  # Filtros
  active_users: "body.users[?status=='active']"
  premium_products: "body.products[?price > `100`]"

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

  # Funções
  total_items: "length(body.items)"
  max_price: "max(body.products[*].price)"

  # Ordenação
  sorted_by_date: "sort_by(body.events, &timestamp)"

  # Resposta completa para debug
  full_response: "@"

6. Input Interativo (InputConfig)

6.1 Propriedades Base

Nota: options é obrigatório para tipos select e multiselect.

6.2 Tipos de Input

6.3 Options para Select

# Array estático
input:
  type: select
  options:
    - {value: "dev", label: "Development"}
    - {value: "prod", label: "Production"}

# De variável capturada
input:
  type: select
  options: "{{users_list}}"  # Deve ser array de objetos
  value_path: "id"           # Campo para o valor
  label_path: "name"         # Campo para o label

# Expressão JMESPath
input:
  type: select
  options: "{{users[*].{value: id, label: name}}}"

6.4 Input Validation

6.5 Input Dynamic Config

7. Iteração (IterationConfig)

7.1 Array Iteration

steps:
  - name: "Process user {{user.name}}"
    iterate:
      over: "{{test_users}}"
      as: "user"
    request:
      method: POST
      url: "/users/{{user.id}}"
      body:
        name: "{{user.name}}"
        email: "{{user.email}}"

7.2 Range Iteration

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

7.3 Iteration Context (disponível durante iteração)

8. Cenários Condicionais (ConditionalScenario)

8.1 Estrutura

8.2 Ações em Then/Else

scenarios:
  - name: "Admin vs Regular User"
    condition: "body.user.role == 'admin'"
    then:
      assert:
        body:
          permissions: {contains: "admin_access"}
      capture:
        admin_id: "body.user.id"
      variables:
        is_admin: true
    else:
      assert:
        status_code: 403
      variables:
        is_admin: false

  - name: "Success path with nested steps"
    condition: "status_code == `200`"
    then:
      steps:
        - name: "Verify created resource"
          request:
            method: GET
            url: "/resources/{{body.id}}"

8.3 Operadores em Condições JMESPath

Nota: Valores literais em JMESPath devem usar backticks: `200`, 'string'

9. Step Call Cross-Suite (StepCallConfig)

9.1 Propriedades

steps:
  - name: "Execute login flow"
    call:
      test: "../auth/login.yaml"
      step: "login-step"
      variables:
        username: "{{test_user}}"
        password: "{{test_password}}"
      isolate_context: true
      on_error: fail

  # Com contexto não-isolado (variáveis mesclam no escopo pai)
  - name: "Setup auth"
    call:
      test: "common/auth-setup.yaml"
      path_type: "absolute"
      step: "setup"
      isolate_context: false

9.2 Comportamento de Isolamento

10. Tipos de Dados e Valores Especiais

10.1 Tipos Primitivos

10.2 Valores Especiais em Contexto de Resposta

11. Configuração de Retry

# No nível de metadata do step
metadata:
  retry:
    max_attempts: 3
    delay_ms: 1000

# No nível de dependency
depends:
  - path: "./setup.yaml"
    retry:
      max_attempts: 2
      delay_ms: 500

# No nível de 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

14.1 Ordem de Precedência (maior para menor)

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

15. Response Object Structure

Estrutura do objeto de resposta disponível para captures e assertions:

{
  status: number,              // 200, 404, etc.
  status_code: number,         // alias para status
  headers: Record<string, string>,  // {"content-type": "application/json"}
  body: any,                   // Corpo parseado (JSON) ou string
  data: any,                   // Alias para body (axios)
  response_time_ms: number     // Tempo de resposta em milissegundos
}

16. Execution Modes

17. Priority Levels

Pode filtrar execução por prioridade via CLI:

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

18. Tags

Tags são strings arbitrárias para categorização. Exemplos comuns:

Filtrar por tags:

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

19. Exemplos Práticos Completos

19.1 Autenticação com Captura e Uso de Token

suite_name: "Authentication Flow"
node_id: "auth-flow"
base_url: "{{api_base_url}}"

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

exports: ["auth_token", "user_id"]

steps:
  # Login e captura de token
  - name: "User login"
    step_id: "login"
    request:
      method: POST
      url: "/auth/login"
      headers:
        Content-Type: "application/json"
      body:
        username: "{{username}}"
        password: "{{password}}"
    assert:
      status_code: 200
      body:
        token: {exists: true, type: "string"}
        user:
          id: {exists: true, type: "number"}
    capture:
      auth_token: "body.token"
      user_id: "body.user.id"
      token_expiry: "body.expires_at"

  # Usar token capturado
  - name: "Get user profile"
    request:
      method: GET
      url: "/users/{{user_id}}"
      headers:
        Authorization: "Bearer {{auth_token}}"
    assert:
      status_code: 200
      body:
        id: {equals: "{{user_id}}"}

19.2 Iteração com Dados Dinâmicos

suite_name: "Bulk User Creation"
node_id: "bulk-users"
base_url: "{{api_base_url}}"

variables:
  users_to_create:
    - {name: "Alice", role: "admin"}
    - {name: "Bob", role: "user"}
    - {name: "Charlie", role: "moderator"}

exports: ["created_user_ids"]

steps:
  - name: "Create user: {{user.name}}"
    iterate:
      over: "{{users_to_create}}"
      as: "user"
    request:
      method: POST
      url: "/users"
      body:
        name: "{{user.name}}"
        email: "{{$faker.internet.email}}"
        role: "{{user.role}}"
        created_at: "{{$js:new Date().toISOString()}}"
    assert:
      status_code: 201
      body:
        name: {equals: "{{user.name}}"}
        role: {equals: "{{user.role}}"}
    capture:
      "created_user_{{_iteration.index}}": "body.id"

19.3 Cenários Condicionais Avançados

suite_name: "Conditional API Testing"
node_id: "conditional-test"
base_url: "{{api_base_url}}"

steps:
  - name: "Create resource"
    request:
      method: POST
      url: "/resources"
      body:
        name: "Test Resource"
        type: "document"
    capture:
      response_status: "status"
      resource_id: "body.id"
      resource_exists: "body.already_exists"

    scenarios:
      # Recurso criado com sucesso
      - name: "New resource created"
        condition: "response_status == `201` && !resource_exists"
        then:
          assert:
            body:
              id: {exists: true, type: "string"}
              created_at: {exists: true}
          capture:
            new_resource_id: "body.id"
          steps:
            - name: "Verify new resource"
              request:
                method: GET
                url: "/resources/{{new_resource_id}}"

      # Recurso já existe
      - name: "Resource already exists"
        condition: "response_status == `409` || resource_exists"
        then:
          variables:
            use_existing: true
          capture:
            existing_resource_id: "body.existing_id"
          steps:
            - name: "Update existing resource"
              request:
                method: PUT
                url: "/resources/{{existing_resource_id}}"
                body:
                  name: "Updated Resource"

      # Erro genérico
      - name: "Error occurred"
        condition: "response_status >= `400` && response_status != `409`"
        then:
          assert:
            body:
              error: {exists: true}
              message: {exists: true, type: "string"}
          variables:
            creation_failed: true

19.4 Input Interativo com Validação

suite_name: "Interactive API Testing"
node_id: "interactive-test"
base_url: "{{api_base_url}}"
execution_mode: "sequential"

metadata:
  requires_user_input: true

steps:
  # Buscar opções da API
  - name: "Get available environments"
    request:
      method: GET
      url: "/environments"
    capture:
      environments_list: "body.environments"
      default_env: "body.default"

  # Input com opções dinâmicas
  - name: "Select environment"
    input:
      prompt: "Select the target environment:"
      variable: "selected_environment"
      type: "select"
      options: "{{environments_list[*].{value: id, label: name}}}"
      default: "{{default_env}}"
      ci_default: "dev"
      required: true
      style: "boxed"
      validation:
        expressions:
          - name: "Valid environment"
            expression: "contains(environments_list[*].id, selected_environment)"
            message: "Selected environment must be valid"
            severity: "error"

  # Input de texto com validação
  - name: "Enter API key"
    input:
      prompt: "Enter API key for {{selected_environment}}:"
      variable: "api_key"
      type: "password"
      required: true
      validation:
        min_length: 20
        pattern: "^sk-[a-zA-Z0-9_-]+$"
        custom_validation: "value.startsWith('sk-')"
      timeout_seconds: 60
      ci_default: "{{$env.TEST_API_KEY}}"

  # Usar valores do input
  - name: "Test API connection"
    request:
      method: GET
      url: "/test-connection"
      headers:
        X-Environment: "{{selected_environment}}"
        Authorization: "Bearer {{api_key}}"
    assert:
      status_code: 200
      body:
        environment: {equals: "{{selected_environment}}"}
        authenticated: {equals: true}

19.5 Dependências e Reuso entre Suites

File: auth-setup.yaml

suite_name: "Authentication Setup"
node_id: "auth-setup"
base_url: "{{api_base_url}}"

variables:
  test_user: "test@example.com"
  test_password: "SecurePass123!"

exports: ["auth_token", "user_id", "session_id"]

steps:
  - name: "Setup test user"
    step_id: "setup"
    request:
      method: POST
      url: "/auth/login"
      body:
        email: "{{test_user}}"
        password: "{{test_password}}"
    assert:
      status_code: 200
    capture:
      auth_token: "body.access_token"
      user_id: "body.user.id"
      session_id: "body.session_id"

File: main-test.yaml

suite_name: "Main API Tests"
node_id: "main-test"
base_url: "{{api_base_url}}"

# Depende do setup de autenticação
depends:
  - path: "./auth-setup.yaml"
    required: true
    cache: 300  # Cache por 5 minutos
    retry:
      max_attempts: 2
      delay_ms: 1000

steps:
  # Usa token da dependency
  - name: "Create protected resource"
    request:
      method: POST
      url: "/api/resources"
      headers:
        Authorization: "Bearer {{auth-setup.auth_token}}"
      body:
        name: "Protected Resource"
        owner_id: "{{auth-setup.user_id}}"
    assert:
      status_code: 201

19.6 Testes de Performance com Response Time

suite_name: "Performance Tests"
node_id: "performance-test"
base_url: "{{api_base_url}}"

metadata:
  priority: "high"
  tags: ["performance", "sla"]

steps:
  # Teste de endpoint rápido
  - name: "Health check performance"
    request:
      method: GET
      url: "/health"
      timeout: 5000
    assert:
      status_code: 200
      response_time_ms:
        less_than: 100  # SLA: < 100ms
        greater_than: 0
    metadata:
      retry:
        max_attempts: 3
        delay_ms: 500

  # Teste de paginação
  - name: "Pagination performance - Page {{page}}"
    iterate:
      range: "1..10"
      as: "page"
    request:
      method: GET
      url: "/items"
      params:
        page: "{{page}}"
        limit: 50
    assert:
      status_code: 200
      response_time_ms:
        less_than: 2000  # SLA: < 2s
      body:
        items:
          length:
            less_than_or_equal: 50
            greater_than: 0
    capture:
      "page_{{page}}_time": "response_time_ms"
      "page_{{page}}_count": "body.items | length(@)"

19.7 Validação Complexa com Regex e Tipos

suite_name: "Data Validation Tests"
node_id: "validation-test"
base_url: "{{api_base_url}}"

steps:
  - name: "Create user with validation"
    request:
      method: POST
      url: "/users"
      body:
        username: "{{$faker.internet.userName}}"
        email: "{{$faker.internet.email}}"
        phone: "{{$faker.phone.number}}"
        website: "https://{{$faker.internet.domainName}}"
        age: "{{$js:Math.floor(Math.random() * 50) + 18}}"
    assert:
      status_code: 201
      body:
        # Validação de email
        email:
          exists: true
          type: "string"
          regex: "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
          notEmpty: true

        # Validação de username
        username:
          exists: true
          type: "string"
          minLength: 3
          regex: "^[a-zA-Z0-9_-]+$"

        # Validação de telefone
        phone:
          exists: true
          regex: "^[\\+]?[1-9]?[0-9]{7,15}$"

        # Validação de URL
        website:
          exists: true
          regex: "^https?:\\/\\/(www\\.)?[-a-zA-Z0-9@:%._\\+~#=]{1,256}\\.[a-zA-Z0-9()]{1,6}\\b"

        # Validação de idade
        age:
          exists: true
          type: "number"
          greater_than_or_equal: 18
          less_than: 150

        # Validação de ID gerado
        id:
          exists: true
          type: "string"
          regex: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"  # UUID

        # Validação de array de roles
        roles:
          exists: true
          type: "array"
          length:
            greater_than: 0
            less_than: 10

        # Validação de timestamp
        created_at:
          exists: true
          type: "string"
          regex: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}"  # ISO 8601

19.8 Error Handling e Retry

suite_name: "Error Handling Tests"
node_id: "error-handling"
base_url: "{{api_base_url}}"

steps:
  # Teste com retry automático
  - name: "Flaky endpoint with retry"
    request:
      method: GET
      url: "/flaky-endpoint"
      timeout: 5000
    assert:
      status_code: 200
    metadata:
      retry:
        max_attempts: 5
        delay_ms: 2000
      timeout: 10000
      description: "Endpoint conhecido por ser instável"

  # Continue mesmo em falha
  - name: "Optional validation"
    request:
      method: POST
      url: "/optional-feature"
      body:
        feature: "beta_feature"
    continue_on_failure: true
    assert:
      status_code: 200

  # Cenários de erro esperados
  - name: "Test error responses"
    request:
      method: POST
      url: "/protected-resource"
      headers:
        Authorization: "Bearer invalid_token"
    scenarios:
      - name: "Unauthorized access"
        condition: "status == `401`"
        then:
          assert:
            status_code: 401
            body:
              error: {equals: "unauthorized"}
              message: {exists: true}
          variables:
            auth_failed: true

      - name: "Forbidden access"
        condition: "status == `403`"
        then:
          assert:
            status_code: 403
            body:
              error: {equals: "forbidden"}
          variables:
            access_denied: true

20. Guia de Troubleshooting

20.1 Problemas Comuns e Soluções

20.2 Debug Tips

# Capturar resposta completa para debug
capture:
  debug_full_response: "@"
  debug_status: "status"
  debug_headers: "headers"
  debug_body: "body"

# Usar variáveis para debug
computed:
  debug_timestamp: "{{$js:new Date().toISOString()}}"
  debug_random: "{{$js:Math.random()}}"

# Verbose assertions
assert:
  custom:
    - name: "Debug assertion"
      condition: "body"
      message: "Body received: {{body}}"

20.3 Validação de YAML

# Verificar sintaxe YAML
npx flow-test-engine --dry-run tests/my-suite.yaml

# Modo verbose para logs detalhados
npx flow-test-engine --verbose tests/my-suite.yaml

# Verificar apenas descoberta
npx flow-test-engine --list

21. Limitações Conhecidas

21.1 Limitações Técnicas

21.2 Boas Práticas

✅ DO:

• Usar node_id únicos e descritivos
• Definir ci_default para todos os inputs
• Capturar variáveis essenciais com nomes claros
• Usar exports apenas para variáveis realmente compartilháveis
• Adicionar metadata.description para steps complexos
• Validar responses com múltiplas assertions
• Usar continue_on_failure com cautela

❌ DON’T:

• Usar execution_mode: parallel com input
• Criar dependências circulares
• Confiar em ordem de execução em parallel
• Capturar dados sensíveis sem necessidade
• Usar timeouts muito curtos em CI/CD
• Ignorar falhas de assertion sem scenarios
• Misturar lógica de negócio em testes