Por que isso é importante

Testes automatizados podem ser mais complexos que a própria implementação.700 linhas de código testando módulo Node.js + Node-RED + Google Sheets via TCP.Lições valiosas para qualquer projeto complexo.

Alguns projetos exigem estratégias de teste que vão muito além do convencional. Quando você precisa testar aplicações low-code interagindo com APIs externas, a complexidade explode exponencialmente.

Este é o relato de como criar uma suíte robusta testando Node-RED, Google Sheets API, usando Playwright, Docker, TCP e BDD em produção.

O Contexto: Módulo Node.js para Google Sheets

Problema a resolver: processar planilhas enormes do Google Sheets sem travar o Node.js. Solução: módulo open-source que processa dados sob demanda, respeitando o ciclo de vida do Node.

Funcionalidades Implementadas

Processamento Inteligente

• 100 linhas por batch

• Progresso visual em tempo real

• Centenas de milhares de itens processados

• Sem travar instância Node.js

UX Melhorada

• Autocompletar nomes de planilhas

• Detectar linhas e colunas com dados

• Seleção específica de colunas

• Configuração sem digitação manual

Desafio Técnico: Testar Low-Code

Como testar módulo que funciona dentro de Node-RED (plataforma visual/low-code)?Não é possível usar testes unitários tradicionais.Solução: simular interação humana completa.

Arquitetura de Testes: Docker + Playwright + TCP

Stack completa para ambiente de testes isolado e reproduzível. Cada teste simula usuário real interagindo com Node-RED via browser.

Setup do Ambiente

Docker Compose sobe Node-RED na porta 1880

Build e instalação do módulo via npm no container

Playwright executa testes como usuário real

TCP server/client captura dados processados

Commands Package.json

• npm run start - Inicia Docker + Node-RED

• npm run install-module - Build e instala módulo

• npm run test:dev - Roda testes com credentials locais

• npm run test:ci - Roda testes no GitHub Actions

BDD e Gherkin Style: Testes Orientados a Comportamento

Nomenclatura seguindo padrão BDD (Behavior-Driven Development). Cada teste descreve comportamento esperado em linguagem natural.

Estrutura Gherkin Aplicada

Exemplo de Teste BDD

Dado que eu inseri um arquivo de configuração válido

Quando eu atualizo a página e adiciono configuração do Google

Então a lista de planilhas deve ser carregada automaticamente

Vantagens do BDD para Testes Complexos

Legibilidade

• Testes em linguagem natural

• Fácil entendimento por não-devs

• Documentação viva do sistema

• Especificação executável

Manutenção

• Cenários reutilizáveis

• Menos acoplamento ao código

• Testes focados no negócio

• Validação de comportamento

Hackeando a API do Node-RED

Node-RED não foi feito para automação. Precisou hackear as APIs internas para simular drag-and-drop, criação de flows e deploy programático.

Engenharia Reversa da Interface

Desafio: Posicionamento de Elementos

Como saber onde usuário vai clicar para posicionar componente? Telas diferentes = coordenadas diferentes.

Solução: Interceptar requests via Network tab, replicar payload com coordenadas fixas pelo meio da tela.

APIs Descobertas via F12

Deploy Flow

• POST /flows

• Payload com flows completos

• Coordenadas X,Y dos elementos

• Tab ID para organização

Gestão Flows

• DELETE /flows/:id

• PUT /flows (update)

• GET /flows (list all)

• POST /flows (create)

Configurações

• PUT /settings

• POST /auth/token

• GET /nodes (modules)

• DELETE /nodes/:id

TCP Client/Server: Capturando Dados em Tempo Real

Como validar que módulo está processando planilha corretamente? Solução: servidor TCP interno para capturar dados que fluem pelo Node-RED.

Arquitetura de Captura

Fluxo de Dados Testado

1. Módulo Google Sheets processa linha da planilha

2. Node Transform converte dados para JSON

3. TCP Client Node envia dados para servidor de teste

4. Teste Playwright valida dados recebidos via TCP

Timeout e Robustez

Gambiarra do Bem: Timeout Estratégico

Timeout configurado porque API externa (Google Sheets) pode falhar.Teste não pode ficar esperando indefinidamente.Máximo de X segundos para resposta, depois considera falha.

Playwright: Traces e Debug Visual

Playwright gera traces visuais de cada teste. Debug incrível: vê exatamente onde clicou, que dados inseriu, estado da aplicação.

Recursos de Debug Utilizados

Modo Visual

• Browser aberto durante execução

• Vê interações em tempo real

• Debug step-by-step

• Screenshots automáticos

Modo Headless

• Execução em background

• Performance máxima

• GitHub Actions ready

• Traces HTML gerados

Experiência de Debug

Traces permitem "navegar" pelos passos do teste. Clica em qualquer etapa e vê: screenshot, DOM state, network requests, console logs.Debug level: incrível.

Cross-Platform: Mac vs Linux

Desenvolvendo no Mac, rodando no GitHub Actions (Linux). Diferenças nos modificadores de teclado quebraram testes em produção.

Solução Multi-Plataforma

Detecção de OS

macOS: Command key (Meta) para shortcuts

Linux: Ctrl key para shortcuts

Código: process.platform === 'darwin' ? 'Meta' : 'Control'

GitHub Actions: CI/CD Completo

Mesma suíte rodando localmente e na nuvem. GitHub Actions executa todos os testes em máquina Linux limpa.

Pipeline de CI/CD

Setup Node.js + Docker no runner Linux

Install dependencies + Playwright browsers

Docker Compose up com Node-RED

Build + install módulo no container

Execução completa da suíte de testes

Upload de traces em caso de falha

Lições Aprendidas: 700 Linhas de Sabedoria

Algumas vezes, testar uma aplicação pode ser mais difícil que implementá-la. Mas o resultado vale cada linha de código escrita.

Pontos-Chave para Projetos Complexos

O Que Funcionou

• BDD para testes complexos

• Playwright para aplicações web

• TCP para captura de dados

• Docker para ambiente isolado

• Traces para debug visual

Armadilhas Evitadas

• Coordenadas hardcoded

• Dependência de APIs externas

• Diferenças entre OS

• Timeouts infinitos

• Testes não isolados

Nem Sempre É Necessário

Raramente você precisará chegar neste nível de complexidade. Mas quando precisar, é possível testar qualquer coisacom as ferramentas certas e estratégia adequada.

Checklist: Testes Automatizados Complexos

✓Ambiente isolado com Docker

✓BDD para testes de comportamento

✓Playwright para automação web

✓TCP/HTTP para captura de dados

✓Timeouts para APIs externas

✓Cross-platform compatibility

✓CI/CD com GitHub Actions

✓Traces para debug visual