mcp-lab-agent 2.1.4 → 2.1.10

package/README.md

@@ -4,321 +4,289 @@
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18-green)](https://nodejs.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-**Executor + Consultor Inteligente de QA.**
+**Assistente de teste que aprende com falhas.** Reduz tempo de debug, elimina flaky e mantém seletores estáveis. Executa testes, analisa causas de falha, corrige automaticamente e aprende padrões que melhoram as próximas gerações. Integra ao Cursor, Cline, Windsurf ou Slack.
 
-Não é só um executor de testes. É um agente que:
-- **Executa:** Roda testes, gera, corrige
-- **Analisa:** "login falha 30% das vezes"
-- **Prevê:** "checkout vai ficar flaky"
-- **Recomenda:** "faça isso agora: 1, 2, 3"
-- **Aprende:** Taxa de sucesso aumenta com o tempo
+```bash
+npx mcp-lab-agent auto "login flow" --max-retries 5
+```
 
 **1 comando. Análise completa.**
 
+> Teste falhou? Em 30 segundos: o que aconteceu, por que e como corrigir. O mcp-lab-agent analisa causas, corrige e acumula conhecimento.
+
+**Foco:** [Top 3 problemas de QA](docs/TOP3_QA_PROBLEMAS_E_ROADMAP.md) — flaky, "por que falhou?", manutenção de seletores.
+
 ---
 
-## O diferencial
+## O que é
 
-| Outras ferramentas | **mcp-lab-agent** |
-|-------------------|-------------------|
-| Só executam | **Executa + Analisa + Recomenda** |
-| "teste falhou" | **"login falha 30% das vezes (timing)"** |
-| Sem contexto | **"src/payment/ sem testes (RISCO ALTO)"** |
-| Você decide o que fazer | **"Faça isso agora: 1, 2, 3"** |
-| Sem aprendizado | **Taxa de sucesso aumenta com o tempo** |
+O **mcp-lab-agent** é um sistema de inteligência em qualidade de software — não uma ferramenta de teste isolada. Ele entende o seu projeto, identifica frameworks (Cypress, Playwright, Jest, Appium, Robot, pytest e outros), gera testes com base em contexto e memória, executa, analisa falhas e aplica correções automaticamente. O valor central está no **learning**: cada correção bem-sucedida é salva e usada nas próximas gerações, aumentando a taxa de sucesso na primeira tentativa.
 
-**Modo autônomo:**
+Com o **Learning Hub**, os aprendizados são centralizados e agregados entre projetos e — em deploy compartilhado — entre times e empresas, formando uma base de conhecimento em qualidade que escala além do repositório.
 
-```bash
-npx mcp-lab-agent auto "login flow" --max-retries 5
-```
+---
 
-O agente:
-1. Detecta seu projeto (Cypress, Playwright, Jest, etc.)
-2. Gera o teste com base em aprendizados anteriores
-3. Executa o teste
-4. Se falhar: analisa, corrige e tenta de novo
-5. Aprende com cada correção para melhorar nas próximas
+## Para quem
+
+| Perfil | Benefício |
+|--------|-----------|
+| **QAs e SDETs** | Geração assistida de testes, análise de falhas com sugestões de correção, detecção de flakiness |
+| **Desenvolvedores** | "Por que falhou?", análise de arquivos e métodos, integração direta no IDE |
+| **Tech leads** | Visão de risco por área, métricas de estabilidade, relatórios para decisão |
+| **Empresas** | Learning Hub centralizado, escala entre squads e organizações, CI/CD, Ollama (offline), Slack para QA via chat |
+
+---
 
-**Resultado:** Testes que passam na primeira tentativa aumentam com o tempo.
+## Comparação
+
+| Outras ferramentas | mcp-lab-agent |
+|--------------------|---------------|
+| Só executam testes | Executa, analisa causa da falha e sugere correção |
+| Saída genérica "teste falhou" | Diagnóstico: "login falha 30% das vezes (timing)" |
+| Sem visão de risco | Identifica áreas sem testes e classifica risco (alto/médio/baixo) |
+| Sem memória entre execuções | Learning system: cada padrão de falha vira correção aplicada nas próximas gerações |
+| Uma ferramenta por tarefa | Sistema de inteligência: geração, execução, análise, relatórios, predição, learning |
+
+---
+
+## Learning System
+
+**Como aprende:** O agente detecta o padrão de falha em cada execução (regex + contexto) e armazena a correção aplicada na memória. Nas próximas gerações, esses aprendizados são injetados no prompt do LLM e nas práticas obrigatórias.
+
+**Baseado em quê:** Tipo de erro (classificado automaticamente), framework, trecho de correção e resultado (passou ou não).
+
+**Melhora quanto:** Taxa de sucesso na primeira tentativa (%), rastreável em `mcp-lab-agent stats` e `get_learning_report`. Quanto mais correções bem-sucedidas, maior a tendência de os próximos testes passarem de primeira.
+
+**Exemplos de padrões aprendidos:**
+
+| Padrão detectado | Correção aplicada |
+|------------------|-------------------|
+| `element_not_visible` | `waitForDisplayed()`, `should('be.visible')` antes de interagir |
+| `element_not_rendered` | `waitForSelector`, `waitFor({ state: 'attached' })` |
+| `selector` instável | Sugestão de `data-testid`, `role`, seletores acessíveis |
+| `timing` | Retry automático, waits explícitos, timeout ajustado |
+| `element_stale` | Re-localizar elemento antes de cada ação |
+| `mobile_mapping_invisible` | Mapeamento visível no topo do spec (Page Object) |
+
+Cada correção bem-sucedida aumenta a taxa de sucesso futura.
 
 ---
 
 ## Quick Start
 
-### Análise Completa (CLI)
+### CLI — Análise completa
 
 ```bash
-# Análise completa: executa, analisa, prevê e recomenda
+# Análise completa: executa testes, analisa estabilidade, prevê riscos e recomenda ações
 npx mcp-lab-agent analyze
 
-# Modo autônomo: gera, roda, corrige e aprende
+# Modo autônomo: gera, roda, corrige e aprende (até passar ou max_retries)
 npx mcp-lab-agent auto "login flow" --max-retries 5
 
-# Ver métricas de aprendizado
+# Métricas de aprendizado e taxa de sucesso
 npx mcp-lab-agent stats
-```
 
-### Slack Bot (sem clonar o projeto)
-
-```bash
-npx mcp-lab-agent slack-bot
+# Relatório de evolução com recomendações para aprimorar o código
+npx mcp-lab-agent report --full
 ```
 
-Configure `~/.cursor/mcp.json` com `"qa-lab-agent": { "slack": { "botToken": "xoxb-...", "signingSecret": "..." } }`. O bot roda localmente; use ngrok para expor em desenvolvimento.
+### IDE — Cursor, Cline, Windsurf
 
-### Integração com IDE (Cursor/Cline/Windsurf)
-
-**1. Configure o MCP** (`~/.cursor/mcp.json`):
+Adicione ao `~/.cursor/mcp.json`:
 
 ```json
 {
   "mcpServers": {
     "qa-lab-agent": {
       "command": "npx",
-      "args": ["-y", "mcp-lab-agent"],
+      "args": ["-y", "mcp-lab-agent@latest"],
       "cwd": "${workspaceFolder}"
     }
   }
 }
 ```
 
-**2. Use no chat:**
+Use no chat: *"Detecte a estrutura do meu projeto"*, *"Gere teste para login"*, *"Por que o teste falhou?"*, *"Avalie http://localhost:3000 no browser"*.
+
+**run_tests com device e auto-fix:** Ao pedir *"Roda o teste X"*, o agente detecta o device (de `qa-lab-agent.config.json`, `wdio.conf` ou `.detoxrc`), executa o fluxo e, se falhar por seletor, aplica correção automaticamente e tenta novamente.
+
+### Slack Bot
 
+```bash
+npx mcp-lab-agent slack-bot
 ```
-"Detecte a estrutura do meu projeto"
-"Modo autônomo: gere teste para login"
-"Rode os testes"
-"Por que o teste falhou?"
-"Avalie http://localhost:3000 no browser"
-"Mostre as estatísticas de aprendizado"
+
+Funciona em ambiente corporativo (Socket Mode, sem URL pública). Configure `botToken` e `appToken` em `~/.cursor/mcp.json`. Onde obter: [slack-bot/CREDENTIALS.md](slack-bot/CREDENTIALS.md). Detalhes: [slack-bot/README.md](slack-bot/README.md).
+
+### Learning Hub — Inteligência centralizada
+
+```bash
+npx mcp-lab-agent learning-hub
 ```
 
----
+API e Dashboard em `http://localhost:3847`. Configure no `.env` do projeto:
 
-## Architecture
+```
+LEARNING_HUB_URL=http://localhost:3847
+LEARNING_HUB_PROJECT_ID=meu-projeto
+```
 
-O diagrama abaixo mostra como o agente autônomo funciona:
+O agente envia learnings automaticamente. O Hub agrega padrões e fornece recomendações. Detalhes: [learning-hub/README.md](learning-hub/README.md).
 
-```mermaid
-flowchart TB
-    subgraph IDE["🖥️ IDE (Cursor, Cline, Windsurf)"]
-        Chat[Chat do usuário]
-    end
+---
 
-    subgraph CLI["💻 CLI (Terminal)"]
-        Auto["mcp-lab-agent auto"]
-        Stats["mcp-lab-agent stats"]
-    end
+## Arquitetura
 
-    subgraph MCP["MCP Protocol (stdio)"]
-        Transport[Stdio Transport]
+```mermaid
+flowchart TB
+    subgraph Input["Entrada"]
+        CLI[CLI: auto, stats, report]
+        IDE[IDE: Cursor, Cline, Windsurf]
+        Slack[Slack Bot]
     end
 
     subgraph Agent["mcp-lab-agent"]
         Router[qa_route_task]
-        AutoTool["qa_auto<br/>(Loop autônomo)"]
-        
-        subgraph Agents["Agentes Especializados"]
-            D[detection<br/>detect_project, read_project, list_test_files]
-            E[execution<br/>run_tests, watch_tests, get_test_coverage]
-            G[generation<br/>generate_tests, write_test]
-            A[analysis<br/>analyze_failures, por_que_falhou, suggest_selector_fix]
-            B[browser<br/>web_eval_browser]
-            R[reporting<br/>create_bug_report, get_business_metrics]
-            L[learning<br/>qa_learning_stats]
-        end
-
-        subgraph Brain["🧠 Núcleo Inteligente"]
-            MR[Model Router<br/>simples → Groq/Flash | complexo → 70B/Pro]
-            PM[Project Memory<br/>.qa-lab-memory.json]
-            FD[Flaky Detection<br/>timing, selector, network]
-            LS[Learning System<br/>salva correções bem-sucedidas]
-        end
+        Auto[qa_auto]
+        MR[Model Router]
+        FD[Flaky Detection]
+        PM[Project Memory]
+        LS[Learning System]
     end
 
-    subgraph External["Externo"]
-        LLM[LLM: Groq / Gemini / OpenAI]
-        PW[Playwright optional]
-        Proj[Seu projeto]
+    subgraph Tools["Ferramentas"]
+        D[detect_project, list_test_files]
+        G[generate_tests, write_test, map_mobile_elements]
+        E[run_tests, get_test_coverage]
+        A[analyze_failures, suggest_fix, por_que_falhou]
+        R[create_bug_report, get_learning_report]
     end
 
-    Chat --> Transport
-    Transport --> Router
-    Router --> AutoTool
-    Router --> D & E & G & A & B & R & L
-
-    Auto --> AutoTool
-    Stats --> L
-
-    AutoTool --> G
-    AutoTool --> E
-    AutoTool --> A
-    AutoTool --> LS
-
-    D & E & G & A & R --> Proj
-    B --> PW
-    B --> Proj
-
-    G & A --> MR
-    MR --> LLM
-    G & A & AutoTool --> PM
-    A & AutoTool --> FD
-    AutoTool --> LS
-    LS --> PM
-```
-
-**Fluxo autônomo (qa_auto):**
-1. **Detecta** projeto (frameworks, pastas, fluxos)
-2. **Gera** teste usando LLM + memória de aprendizados
-3. **Executa** o teste
-4. **Se falhar:** analisa (flaky detection), corrige e tenta de novo
-5. **Aprende:** salva correções bem-sucedidas na memória
-6. **Repete** até passar ou atingir max_retries
-
-**Fluxo resumido (IDE):**
-1. **Usuário** fala no chat do IDE
-2. **MCP** entrega a mensagem ao `mcp-lab-agent`
-3. **qa_route_task** sugere o agente certo (detection, execution, generation, etc.)
-4. **Ferramentas** executam no projeto (detectar, rodar, gerar, analisar)
-5. **Model Router** escolhe o modelo: tarefas simples → barato; complexas → mais capaz
-6. **Project Memory** guarda padrões e fluxos para próximas gerações
-7. **Flaky Detection** identifica testes intermitentes e sugere correções
+    subgraph Ext["Externo"]
+        LLM[LLM: Groq, Gemini, OpenAI, Ollama]
+        Hub[Learning Hub]
+    end
 
----
+    Input --> Router
+    Router --> Auto
+    Auto --> G & E & A
+    G & A --> MR --> LLM
+    A --> FD
+    Auto --> LS --> PM
+    PM -.-> Hub
+    Router --> D & G & E & A & R
+```
 
-## Features
-
-| Categoria | O que faz |
-|-----------|-----------|
-| **🤖 Autônomo** | `qa_auto` — loop completo: gera, roda, corrige, aprende (até passar ou max_retries) |
-| **📊 Learning** | Salva correções bem-sucedidas, taxa de sucesso na 1ª tentativa, métricas de aprendizado |
-| **Detecção** | Cypress, Playwright, WebdriverIO, Jest, Vitest, Mocha, Robot, pytest, Behave, Appium, Detox |
-| **Execução** | run_tests, watch, coverage (Jest/Vitest) |
-| **Geração** | Testes via LLM (Groq, Gemini, OpenAI), templates |
-| **Análise** | analyze_failures, por_que_falhou, suggest_fix, suggest_selector_fix |
-| **Browser** | web_eval_browser — screenshots, network, console (Playwright opcional) |
-| **Relatórios** | Bug reports em Markdown, métricas de negócio |
-| **Flaky-aware** | Detecta timing, selector, network; sugere retries |
-| **Model routing** | Tarefas simples → modelo barato; complexas → modelo forte |
-| **Memória** | Cache em .qa-lab-memory.json, qa-lab-flows.json |
+**Fluxo `qa_auto`:**
+1. Detecta projeto (frameworks, pastas, fluxos)
+2. Gera teste com LLM + memória de aprendizados
+3. Executa o teste
+4. Se falhar: analisa (flaky detection), corrige e tenta novamente
+5. Aprende e salva correções na memória
+6. Repete até passar ou atingir `max_retries`
 
 ---
 
-## CLI
-
-```bash
-mcp-lab-agent [comando]
-```
+## Capacidades
 
-| Comando | Descrição |
-|---------|-----------|
-| *(sem args)* | Inicia o servidor MCP (modo padrão para o IDE) |
-| `auto <descrição> [--max-retries N]` | **[NOVO]** Modo autônomo: gera, roda, corrige e aprende (default: 3 tentativas) |
-| `stats` | **[NOVO]** Mostra estatísticas de aprendizado (taxa de sucesso, correções, etc.) |
-| `detect [--json]` | Detecta frameworks e estrutura do projeto |
-| `route <tarefa>` | Sugere qual ferramenta usar |
-| `list` | Lista agentes e ferramentas disponíveis |
-| `--help` | Mostra ajuda |
-
-**Exemplos:**
-```bash
-mcp-lab-agent auto "login flow" --max-retries 5
-mcp-lab-agent stats
-mcp-lab-agent detect
-mcp-lab-agent route "rodar os testes"
-mcp-lab-agent list
-```
+### Automação e geração
 
-Referência completa do CLI: `mcp-lab-agent --help`
+- **Modo autônomo** (`qa_auto`): gera, executa, analisa, corrige e aprende em loop
+- **Geração com LLM**: Groq, Gemini, OpenAI ou Ollama (100% offline)
+- **Mapeamento mobile** (`map_mobile_elements`): elementos em Appium/Detox
+- **Templates**: waits inteligentes e assert final obrigatório em todo teste gerado
 
----
+### Análise e diagnóstico
 
-## Escalabilidade
+- **Detecção de falhas**: timing, selector, element_not_rendered, element_not_visible, element_stale, mobile_mapping_invisible
+- **Mensagens contextualizadas**: cada tipo de erro tem explicação e sugestão específica
+- **Análise de estabilidade**: taxa de falha por teste, identificação de flaky
+- **Predição de flakiness** (`qa_predict_flaky`): risco antes de o problema aparecer
+- **Análise de métodos** (`analyze_file_methods`): varredura por método do arquivo
 
-### Como o mcp-lab-agent escala para empresas
+### Relatórios e métricas
 
-**1. Multi-projeto:**
-- Cada projeto tem sua própria memória (`.qa-lab-memory.json`)
-- Aprendizados são isolados por contexto
-- Suporte a monorepos (detecta múltiplos frameworks)
+- **Bug reports** em Markdown
+- **Métricas de negócio** (se `qa-lab-flows.json` configurado)
+- **Relatório de evolução** (`get_learning_report`): padrões por tipo, recomendações
+- **Benchmark** (`qa_compare_with_industry`): comparação com padrões do mercado
 
-**2. CI/CD:**
-```yaml
-# .github/workflows/qa.yml
-- run: npx mcp-lab-agent auto "smoke tests" --max-retries 2
-- run: npx mcp-lab-agent stats
-```
+### Memória e Learning Hub
 
-**3. Métricas exportáveis:**
-- `.qa-lab-memory.json` pode ser lido por dashboards
-- `stats` retorna JSON estruturado
-- Integração com Grafana/DataDog via script
+- **Memória local**: `.qa-lab-memory.json` por projeto
+- **Learning Hub**: API central (`POST /learning`, `GET /patterns`), Dashboard, sync automático entre projetos
 
-**4. Aprendizado compartilhado (roadmap):**
-- Exportar/importar memórias entre projetos
-- Central de aprendizados da empresa
-- Padrões globais + overrides locais
+### Frameworks suportados
 
-**5. Customização:**
-- `qa-lab-flows.json` para fluxos de negócio específicos
-- Variáveis de ambiente para modelos customizados
-- Extensível via MCP tools
+11+ frameworks: Cypress, Playwright, WebdriverIO, Jest, Vitest, Mocha, Robot Framework, pytest, Behave, Appium, Detox.
 
 ---
 
-## Configuração
+## CLI
 
-### Opção 1: APIs Externas (Groq, Gemini, OpenAI)
+| Comando | Descrição |
+|---------|-----------|
+| *(sem args)* | Inicia servidor MCP (modo IDE) |
+| `learning-hub` | API + Dashboard (porta 3847) |
+| `slack-bot` | Bot Slack (Socket Mode) |
+| `analyze` | Análise completa do projeto |
+| `auto <descrição> [--max-retries N]` | Modo autônomo (default: 3 tentativas) |
+| `stats` | Estatísticas de aprendizado |
+| `report [--full]` | Relatório de evolução |
+| `detect [--json]` | Detecta frameworks e estrutura |
+| `route <tarefa>` | Sugere ferramenta |
+| `list` | Lista agentes e ferramentas |
 
 ```bash
-# .env
-GROQ_API_KEY=sua-key  # Gratuito: https://console.groq.com/keys
+# Exemplos de uso
+mcp-lab-agent learning-hub          # Inicia Hub (porta 3847)
+mcp-lab-agent analyze              # Análise completa
+mcp-lab-agent auto "login flow"     # Modo autônomo
+mcp-lab-agent stats                 # Taxa de sucesso, aprendizados
+mcp-lab-agent report --full        # Relatório com recomendações
 ```
 
-### Opção 2: Ollama (Local, Sem Internet) ⭐ Recomendado para empresas
-
-```bash
-# 1. Instale o Ollama
-brew install ollama  # macOS
-# ou: curl -fsSL https://ollama.com/install.sh | sh  # Linux
-
-# 2. Baixe o modelo
-ollama pull llama3.1:8b
-
-# 3. Inicie
-ollama serve
+---
 
-# 4. Pronto! O agente detecta automaticamente
-npx mcp-lab-agent auto "login flow"
-```
+## Escalabilidade e uso em produção
 
-**100% offline. Sem APIs externas. Ideal para ambientes corporativos.**
+- **Por projeto**: memória local (`.qa-lab-memory.json`) isolada por repositório
+- **Entre times**: Learning Hub agrega padrões por `projectId`; Dashboard compartilhado
+- **Entre empresas**: um Hub pode servir múltiplas organizações; padrões cross-org (ex.: "Playwright + selector instável" em 15 projetos) viram recomendações globais
+- **CI/CD**: integração em GitHub Actions, GitLab CI, Jenkins
+- **Métricas exportáveis**: JSON estruturado para Grafana, DataDog, dashboards internos
+- **Ollama**: 100% offline; adequado para ambientes corporativos restritivos
+- **LLM interno**: endpoint customizado da empresa
 
-### Opção 3: LLM Interno da Empresa
+---
 
-```bash
-# .env
-QA_LAB_LLM_BASE_URL=https://llm-interno.empresa.com/v1
-QA_LAB_LLM_API_KEY=sua-key-interna
-```
+## Configuração
 
-### Variáveis de ambiente (todas opcionais)
+### Variáveis de ambiente (opcionais)
 
 | Variável | Uso |
 |----------|-----|
-| `GROQ_API_KEY` | Groq (gratuito, rápido) |
+| `GROQ_API_KEY` | Groq |
 | `GEMINI_API_KEY` | Google Gemini |
 | `OPENAI_API_KEY` | OpenAI |
-| `OLLAMA_BASE_URL` | Ollama customizado (default: http://localhost:11434) |
-| `QA_LAB_LLM_BASE_URL` | Endpoint LLM customizado (empresa) |
-| `QA_LAB_LLM_API_KEY` | API key para LLM customizado |
+| `OLLAMA_BASE_URL` | Ollama (default: http://localhost:11434) |
+| `QA_LAB_LLM_BASE_URL` | LLM customizado (empresa) |
+| `QA_LAB_LLM_API_KEY` | API key do LLM |
 | `QA_LAB_LLM_SIMPLE` | Modelo para tarefas simples |
 | `QA_LAB_LLM_COMPLEX` | Modelo para tarefas complexas |
+| `LEARNING_HUB_URL` | URL do Learning Hub |
+| `LEARNING_HUB_PROJECT_ID` | ID do projeto no Hub |
+
+### Ollama (offline)
 
-### Modo browser (opcional)
+```bash
+brew install ollama
+ollama pull llama3.1:8b
+ollama serve
+npx mcp-lab-agent auto "login flow"
+```
 
-Para `web_eval_browser`:
+### Modo browser (Playwright)
 
 ```bash
 npm install playwright
@@ -328,7 +296,9 @@ npm install playwright
 
 ## Documentação
 
-- **[CHANGELOG.md](CHANGELOG.md)** — Histórico de versões
+- [CHANGELOG.md](CHANGELOG.md) — Histórico de versões
+- [slack-bot/README.md](slack-bot/README.md) — Slack Bot
+- [learning-hub/README.md](learning-hub/README.md) — Learning Hub
 
 ---
 
@@ -344,7 +314,7 @@ npm test
 
 | Script | Descrição |
 |--------|-----------|
-| `npm run build` | Build com tsup |
+| `npm run build` | Build (tsup) |
 | `npm test` | Testes (Vitest) |
 | `npm run test:coverage` | Cobertura |
 | `npm run dev` | Build em watch |