Componentes Reutilizáveis

Os Componentes Reutilizáveis permitem transformar um trecho de automação em um bloco reaproveitável. Em vez de copiar os mesmos nós de login, preparação de massa, consulta auxiliar ou validação comum em vários cenários, você cria um componente uma vez, define suas entradas e saídas, publica e usa esse componente dentro dos cenários.

Pense em um componente como um subfluxo com contrato:

• o componente recebe valores de entrada;
• executa uma sequência própria de nós;
• devolve uma saída para o cenário que o chamou.

Quando Usar

Use componentes quando houver uma sequência que se repete em muitos cenários, por exemplo:

• autenticar em um sistema;
• criar uma massa de dados padrão;
• consultar dados em API ou banco e normalizar o resultado;
• executar uma validação de negócio comum;
• encapsular uma automação web pequena que serve de preparação para outros testes.

Evite componentes para ações muito específicas de um único cenário. Se a lógica só aparece uma vez, manter os nós diretamente no cenário costuma ser mais simples.

Onde Encontrar

No menu lateral, acesse Componentes.

A listagem permite:

• criar um novo componente;
• buscar por nome;
• filtrar por categoria;
• filtrar por status Publicado ou Rascunho;
• copiar o nome ou ID do componente;
• excluir componentes, respeitando as permissões do usuário.

Quando um componente está sendo usado por cenários, o QANode avisa antes da exclusão para evitar remoções acidentais.

Criando um Componente

1. Acesse Componentes.
2. Clique em Novo Componente.
3. Informe:
   • Nome: nome exibido na lista e no editor de cenários;
   • Categoria: grupo usado para organizar a paleta de componentes;
   • Cor: cor visual do componente no canvas.
4. Clique para criar.

O QANode abre o editor do componente. Ele usa a mesma base visual do editor de fluxos, mas em modo de componente.

Editor do Componente

Todo componente possui dois nós especiais:

Esses nós são protegidos no editor. Eles fazem parte do contrato do componente e não devem ser removidos.

Entre o Input e o Output, você adiciona os nós normais do QANode: Web, API, banco de dados, utilitários, controle de fluxo e outros nós disponíveis no seu ambiente.

Entradas do Componente

No nó Input, configure os campos que o componente espera receber.

Exemplo de entradas:

Durante a execução do componente, os nós internos podem usar essas entradas por expressão, como qualquer outro output de nó.

Exemplo:

{{ steps.Input.outputs.email }}

Dê nomes simples e estáveis para os campos. Isso facilita o uso do componente em cenários e evita expressões difíceis de manter.

Saída do Componente

No nó Output, configure o que o componente devolve ao cenário.

Exemplo:

Nome: token
Tipo: string
Valor: {{ steps.login.outputs.json.token }}

O cenário que chama o componente poderá usar a saída como output do nó de componente.

Nesta versão, o componente trabalha com uma saída principal no nó Output. Se precisar retornar mais de um dado, use um objeto como saída, por exemplo { token, userId, role }.

Testando o Componente

Antes de publicar, teste o componente no próprio editor.

1. Preencha Dados de Teste nos campos obrigatórios do nó Input.
2. Clique em Testar Componente.
3. Acompanhe a execução no painel de runs do editor.

As execuções de teste servem para validar o componente isoladamente. Elas não substituem as execuções oficiais dos cenários que usarão o componente.

Se um campo obrigatório não tiver dado de teste, o QANode bloqueia a execução do teste do componente até o valor ser informado.

Salvando e Publicando

Ao salvar o componente, o QANode registra:

• o fluxo interno do componente;
• o contrato de entrada;
• o contrato de saída;
• nome, categoria e cor.

Para que o componente apareça na paleta dos cenários, ele precisa estar Publicado.

Regras importantes:

• componentes em rascunho não aparecem para uso em cenários;
• ao alterar o fluxo interno, entradas ou saída, o componente volta a exigir revisão/publicação;
• publicar confirma que o contrato atual está pronto para ser usado por outros cenários.

Usando em um Cenário

No editor de cenários:

1. Abra a aba Componentes na paleta lateral.
2. Localize o componente publicado.
3. Arraste o componente para o canvas.
4. Conecte-o aos outros nós.
5. Preencha os campos de entrada no painel de propriedades.

As entradas aceitam valores literais e expressões:

email: {{ variables.USUARIO_TESTE }}
senha: {{ variables.SENHA_TESTE }}
perfil: admin

Durante a execução, o QANode executa o componente como parte do cenário. Se uma entrada obrigatória estiver vazia, o cenário é bloqueado antes de rodar para evitar falha difícil de diagnosticar.

Usando Outputs do Componente

Depois que o componente roda, sua saída fica disponível como output do nó no cenário.

Exemplo:

{{ steps.loginComponente.outputs.token }}

Se a saída principal for um objeto:

{{ steps.prepararUsuario.outputs.result.userId }}
{{ steps.prepararUsuario.outputs.result.email }}

Permissões

Em ambientes com controle de acesso, os componentes respeitam permissões próprias:

Boas Práticas

• Use componentes para lógicas realmente compartilhadas.
• Mantenha o contrato pequeno e claro.
• Nomeie entradas e saídas com termos de negócio, não detalhes técnicos internos.
• Use categorias para organizar componentes por domínio, como Login, Massa de dados, Pedidos ou CRM.
• Teste o componente isoladamente antes de publicar.
• Ao alterar um componente usado por muitos cenários, valide pelo menos um cenário consumidor antes de liberar para o time.
• Prefira retornar um objeto quando a saída precisa carregar vários valores relacionados.

Limitações e Cuidados

• Componentes publicados podem ser usados por vários cenários; mudanças no contrato podem exigir ajuste nos cenários consumidores.
• Componentes em rascunho não aparecem na paleta do editor de cenários.
• O nó Input e o nó Output são parte da estrutura do componente e não devem ser tratados como nós comuns.
• Se o componente depende de sessão web, credenciais ou variáveis, documente isso no nome, categoria ou no padrão de uso do time.