Interface web para o Doc Detective

Este projeto é uma interface web para o projeto Doc Detective, disponível aqui.

Como usar

Guia de uso e casos de uso para o Doc Detective.

Estratégias para Documentação Existente

1. Teste de Links (Mais Simples e Útil)

Este é o teste mais básico e útil para qualquer documentação:

{
  "tests": [
    {
      "steps": [
        {
          "checkLink": {
            "url": "https://developerhub.nayax.com/reference/overview"
          }
        },
        {
          "checkLink": {
            "url": "https://developerhub.nayax.com/reference/get-actor-by-actorid"
          }
        },
        {
          "checkLink": {
            "url": "https://developerhub.nayax.com/reference/get-cards"
          }
        }
      ]
    }
  ]
}

Como criar:

Extraia todos os links da sua documentação
Crie um arquivo .spec.json com testes checkLink
Execute: npx doc-detective --input links-test.spec.json

2. Teste de Estrutura da Página

Para verificar se elementos importantes estão presentes:

{
  "tests": [
    {
      "steps": [
        {
          "goTo": {
            "url": "https://sua-documentacao.com"
          }
        },
        {
          "find": {
            "elementText": "Getting Started"
          }
        },
        {
          "find": {
            "elementText": "API Reference"
          }
        },
        {
          "find": {
            "selector": "nav"
          }
        }
      ]
    }
  ]
}

3. Teste de APIs (Para Documentação de API)

{
  "tests": [
    {
      "steps": [
        {
          "httpRequest": {
            "url": "https://api.exemplo.com/v1/users",
            "method": "GET",
            "statusCodes": [200]
          }
        },
        {
          "httpRequest": {
            "url": "https://api.exemplo.com/v1/health",
            "method": "GET",
            "statusCodes": [200]
          }
        }
      ]
    }
  ]
}

4. Teste de Navegação

{
  "tests": [
    {
      "steps": [
        {
          "goTo": {
            "url": "https://sua-docs.com"
          }
        },
        {
          "click": {
            "elementText": "Getting Started"
          }
        },
        {
          "find": {
            "elementText": "Installation"
          }
        },
        {
          "screenshot": {
            "path": "getting-started.png"
          }
        }
      ]
    }
  ]
}

Fluxo de Trabalho Recomendado

Passo 1: Análise da Documentação

Identifique todos os links externos e internos
Liste as seções principais
Identifique procedimentos críticos
Mapeie APIs mencionadas

Passo 2: Criação de Testes por Prioridade

Prioridade 1 - Links (Mais Rápido):

# Crie um teste apenas para links
npx doc-detective --input links-test.spec.json

Prioridade 2 - Estrutura:

# Teste se as seções principais existem
npx doc-detective --input structure-test.spec.json

Prioridade 3 - Funcionalidade:

# Teste procedimentos críticos
npx doc-detective --input procedures-test.spec.json

Passo 3: Automação com CI/CD

Crie um .github/workflows/docs-test.yml:

name: Test Documentation

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test-docs:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - uses: actions/setup-node@v3
      with:
        node-version: '20'
    - run: npm install -g doc-detective
    - run: npx doc-detective --input docs-tests/

Casos de Uso Mais Comuns na Prática

1. README.md - Projeto Open Source

Cenário: Validar links, badges, e comandos de instalação

{
  "tests": [
    {
      "description": "Validar README do projeto",
      "steps": [
        {
          "checkLink": { "url": "https://github.com/seu-usuario/projeto" }
        },
        {
          "checkLink": { "url": "https://npmjs.com/package/seu-pacote" }
        },
        {
          "checkLink": { "url": "https://travis-ci.org/seu-usuario/projeto" }
        },
        {
          "runShell": {
            "command": "npm",
            "args": ["--version"]
          }
        }
      ]
    }
  ]
}

2. Documentação de Instalação/Setup

Cenário: Testar se os comandos e links de download funcionam

{
  "tests": [
    {
      "description": "Validar processo de instalação",
      "steps": [
        {
          "checkLink": { "url": "https://nodejs.org/download" }
        },
        {
          "checkLink": { "url": "https://github.com/projeto/releases/latest" }
        },
        {
          "runShell": {
            "command": "which",
            "args": ["node"]
          }
        },
        {
          "runShell": {
            "command": "which",
            "args": ["npm"]
          }
        }
      ]
    }
  ]
}

3. Tutorial Step-by-Step

Cenário: Validar cada passo de um tutorial prático

{
  "tests": [
    {
      "description": "Tutorial - Criar primeira aplicação",
      "steps": [
        {
          "goTo": { "url": "https://tutorial.exemplo.com/getting-started" }
        },
        {
          "find": { "elementText": "Create New Project" }
        },
        {
          "click": { "elementText": "Create New Project" }
        },
        {
          "find": { "selector": "input[name='projectName']" }
        },
        {
          "type": { "keys": ["meu-projeto-teste"] }
        },
        {
          "click": { "elementText": "Create" }
        },
        {
          "find": { "elementText": "Project created successfully" }
        },
        {
          "screenshot": { "path": "projeto-criado.png" }
        }
      ]
    }
  ]
}

4. Documentação de API - Casos Reais

Cenário: Testar endpoints críticos e autenticação

{
  "tests": [
    {
      "description": "API - Endpoints críticos",
      "steps": [
        {
          "httpRequest": {
            "url": "https://api.exemplo.com/health",
            "method": "GET",
            "statusCodes": [200]
          }
        },
        {
          "httpRequest": {
            "url": "https://api.exemplo.com/v1/auth/login",
            "method": "POST",
            "requestHeaders": {
              "Content-Type": "application/json"
            },
            "requestBody": {
              "email": "test@exemplo.com",
              "password": "senha123"
            },
            "statusCodes": [200, 401]
          }
        },
        {
          "checkLink": { "url": "https://docs.exemplo.com/api/authentication" }
        }
      ]
    }
  ]
}

5. FAQ e Base de Conhecimento

Cenário: Verificar se respostas comuns estão acessíveis

{
  "tests": [
    {
      "description": "FAQ - Perguntas mais comuns",
      "steps": [
        {
          "goTo": { "url": "https://help.exemplo.com/faq" }
        },
        {
          "find": { "elementText": "Como resetar senha?" }
        },
        {
          "find": { "elementText": "Como cancelar conta?" }
        },
        {
          "find": { "elementText": "Política de reembolso" }
        },
        {
          "find": { "selector": "input[type='search']" }
        },
        {
          "type": { "keys": ["pagamento"] }
        },
        {
          "click": { "elementText": "Buscar" }
        }
      ]
    }
  ]
}

6. Documentação de Integração

Cenário: Validar SDKs, webhooks e integrações terceirizadas

{
  "tests": [
    {
      "description": "Integrações - SDKs e Webhooks",
      "steps": [
        {
          "checkLink": { "url": "https://github.com/empresa/sdk-javascript" }
        },
        {
          "checkLink": { "url": "https://github.com/empresa/sdk-python" }
        },
        {
          "checkLink": { "url": "https://webhook.site" }
        },
        {
          "httpRequest": {
            "url": "https://api.exemplo.com/webhooks/test",
            "method": "POST",
            "requestHeaders": {
              "X-API-Key": "$API_KEY"
            },
            "statusCodes": [200, 204]
          }
        }
      ]
    }
  ]
}

7. Changelog e Release Notes

Cenário: Verificar se atualizações estão documentadas

{
  "tests": [
    {
      "description": "Changelog - Últimas versões",
      "steps": [
        {
          "goTo": { "url": "https://github.com/projeto/releases" }
        },
        {
          "find": { "elementText": "Latest" }
        },
        {
          "checkLink": { "url": "https://github.com/projeto/blob/main/CHANGELOG.md" }
        },
        {
          "goTo": { "url": "https://docs.projeto.com/changelog" }
        },
        {
          "find": { "elementText": "Version" }
        }
      ]
    }
  ]
}

8. Documentação de Troubleshooting

Cenário: Validar soluções para problemas comuns

{
  "tests": [
    {
      "description": "Troubleshooting - Problemas comuns",
      "steps": [
        {
          "goTo": { "url": "https://docs.exemplo.com/troubleshooting" }
        },
        {
          "find": { "elementText": "Error 500" }
        },
        {
          "find": { "elementText": "Connection timeout" }
        },
        {
          "find": { "elementText": "Authentication failed" }
        },
        {
          "click": { "elementText": "Error 500" }
        },
        {
          "find": { "elementText": "Solution" }
        }
      ]
    }
  ]
}

9. Documentação de Deploy/DevOps

Cenário: Validar scripts e comandos de deploy

{
  "tests": [
    {
      "description": "Deploy - Scripts e comandos",
      "steps": [
        {
          "checkLink": { "url": "https://hub.docker.com/r/empresa/app" }
        },
        {
          "runShell": {
            "command": "docker",
            "args": ["--version"]
          }
        },
        {
          "runShell": {
            "command": "kubectl",
            "args": ["version", "--client"]
          }
        },
        {
          "checkLink": { "url": "https://github.com/empresa/helm-charts" }
        }
      ]
    }
  ]
}

10. Portal do Desenvolvedor

Cenário: Validar console de desenvolvimento e ferramentas

{
  "tests": [
    {
      "description": "Portal Dev - Console e ferramentas",
      "steps": [
        {
          "goTo": { "url": "https://console.exemplo.com" }
        },
        {
          "find": { "elementText": "API Keys" }
        },
        {
          "find": { "elementText": "Documentation" }
        },
        {
          "find": { "elementText": "Sandbox" }
        },
        {
          "click": { "elementText": "API Keys" }
        },
        {
          "find": { "elementText": "Generate New Key" }
        },
        {
          "screenshot": { "path": "console-api-keys.png" }
        }
      ]
    }
  ]
}

Exemplos Práticos para Diferentes Tipos de Documentação

API Documentation (Como a Nayax)

{
  "tests": [
    {
      "steps": [
        {
          "checkLink": { "url": "https://api.exemplo.com/docs" }
        },
        {
          "httpRequest": {
            "url": "https://api.exemplo.com/v1/status",
            "method": "GET",
            "statusCodes": [200]
          }
        },
        {
          "goTo": { "url": "https://api.exemplo.com/docs" }
        },
        {
          "find": { "elementText": "Authentication" }
        }
      ]
    }
  ]
}

Tutorial/Guia do Usuário

{
  "tests": [
    {
      "steps": [
        {
          "goTo": { "url": "https://docs.exemplo.com/tutorial" }
        },
        {
          "find": { "elementText": "Prerequisites" }
        },
        {
          "find": { "elementText": "Step 1" }
        },
        {
          "find": { "elementText": "Step 2" }
        },
        {
          "screenshot": { "path": "tutorial-overview.png" }
        }
      ]
    }
  ]
}

Documentação de Produto

{
  "tests": [
    {
      "steps": [
        {
          "goTo": { "url": "https://help.exemplo.com" }
        },
        {
          "find": { "selector": "input[type='search']" }
        },
        {
          "type": { "keys": ["login"] }
        },
        {
          "click": { "elementText": "Search" }
        },
        {
          "find": { "elementText": "How to login" }
        }
      ]
    }
  ]
}

Dicas Importantes

✅ Faça:

Comece com testes simples de links
Teste os procedimentos mais críticos primeiro
Use screenshots para documentar o estado esperado
Execute testes regularmente

❌ Evite:

Começar com testes muito complexos
Testar cada detalhe mínimo
Ignorar testes que falham (investigue o motivo)
Criar testes muito frágeis (dependentes de elementos que mudam)

Templates Prontos para Usar

Template 1: Teste Básico de Website/Blog

{
  "tests": [
    {
      "description": "Website básico - links e estrutura",
      "steps": [
        {
          "goTo": { "url": "https://SEU-SITE.com" }
        },
        {
          "find": { "selector": "nav" }
        },
        {
          "find": { "elementText": "Sobre" }
        },
        {
          "find": { "elementText": "Contato" }
        },
        {
          "checkLink": { "url": "https://SEU-SITE.com/sobre" }
        },
        {
          "checkLink": { "url": "https://SEU-SITE.com/contato" }
        },
        {
          "screenshot": { "path": "homepage.png" }
        }
      ]
    }
  ]
}

Template 2: E-commerce - Fluxo de Compra

{
  "tests": [
    {
      "description": "E-commerce - navegação básica",
      "steps": [
        {
          "goTo": { "url": "https://LOJA.com" }
        },
        {
          "find": { "selector": "input[type='search']" }
        },
        {
          "type": { "keys": ["produto teste"] }
        },
        {
          "click": { "elementText": "Buscar" }
        },
        {
          "find": { "elementText": "Carrinho" }
        },
        {
          "find": { "elementText": "Login" }
        },
        {
          "checkLink": { "url": "https://LOJA.com/ajuda" }
        }
      ]
    }
  ]
}

Template 3: SaaS - Dashboard de Usuário

{
  "tests": [
    {
      "description": "SaaS - dashboard público",
      "steps": [
        {
          "goTo": { "url": "https://app.SERVICO.com" }
        },
        {
          "find": { "elementText": "Entrar" }
        },
        {
          "find": { "elementText": "Criar conta" }
        },
        {
          "checkLink": { "url": "https://SERVICO.com/pricing" }
        },
        {
          "checkLink": { "url": "https://docs.SERVICO.com" }
        },
        {
          "checkLink": { "url": "https://status.SERVICO.com" }
        }
      ]
    }
  ]
}

Template 4: Biblioteca/Framework - Documentação Técnica

{
  "tests": [
    {
      "description": "Biblioteca - docs técnicos",
      "steps": [
        {
          "checkLink": { "url": "https://github.com/USUARIO/BIBLIOTECA" }
        },
        {
          "checkLink": { "url": "https://npmjs.com/package/BIBLIOTECA" }
        },
        {
          "goTo": { "url": "https://BIBLIOTECA.dev/docs" }
        },
        {
          "find": { "elementText": "Installation" }
        },
        {
          "find": { "elementText": "Quick Start" }
        },
        {
          "find": { "elementText": "API Reference" }
        },
        {
          "find": { "elementText": "Examples" }
        }
      ]
    }
  ]
}

Template 5: Aplicativo Mobile - Landing Page

{
  "tests": [
    {
      "description": "App mobile - landing page",
      "steps": [
        {
          "goTo": { "url": "https://APP.com" }
        },
        {
          "find": { "elementText": "Download" }
        },
        {
          "checkLink": { "url": "https://apps.apple.com/app/APP" }
        },
        {
          "checkLink": { "url": "https://play.google.com/store/apps/details?id=com.APP" }
        },
        {
          "find": { "elementText": "Privacy Policy" }
        },
        {
          "find": { "elementText": "Terms of Service" }
        }
      ]
    }
  ]
}

Checklist de Implementação Rápida

🚀 Em 15 minutos:

Identifique 5-10 links principais da sua documentação
Crie um arquivo links-test.spec.json usando o template básico
Execute: npx doc-detective --input links-test.spec.json
Analise os resultados

📋 Em 1 hora:

Mapeie as seções críticas da documentação
Crie testes para 3-5 fluxos principais
Configure arquivo de configuração .doc-detective.json
Execute todos os testes
Documente os resultados

⚙️ Em 1 dia:

Configure CI/CD para execução automática
Crie alertas para falhas
Estabeleça cronograma de execução
Treine equipe nos resultados
Implemente processo de correção

Problemas Comuns e Soluções

❌ Problema: "Element not found"

Causa: Elemento mudou ou página carregou devagar

// ❌ Problemático
{
  "find": { "elementText": "Texto exato" }
}

// ✅ Melhor abordagem
{
  "wait": { "duration": 2000 }
},
{
  "find": { 
    "elementText": "Texto", 
    "timeout": 10000 
  }
}

❌ Problema: Links retornando 403/401

Causa: Autenticação necessária ou bloqueio geográfico

// ✅ Solução: Teste apenas status de conectividade
{
  "httpRequest": {
    "url": "https://api.protegida.com",
    "method": "GET",
    "statusCodes": [200, 401, 403]
  }
}

❌ Problema: Testes muito lentos

Causa: Muitos testes de navegação

// ❌ Lento
{
  "goTo": { "url": "https://site.com/page1" }
},
{
  "goTo": { "url": "https://site.com/page2" }
}

// ✅ Mais rápido
{
  "checkLink": { "url": "https://site.com/page1" }
},
{
  "checkLink": { "url": "https://site.com/page2" }
}

❌ Problema: Screenshots diferentes

Causa: Elementos dinâmicos (anúncios, datas)

// ✅ Solução: Capture área específica
{
  "screenshot": {
    "path": "area-especifica.png",
    "selector": ".content-main"
  }
}

💡 Dicas de Performance

Agrupe testes por domínio

{
  "tests": [
    {
      "description": "Todos os testes do mesmo site",
      "steps": [
        { "goTo": { "url": "https://site.com" } },
        { "find": { "elementText": "Menu" } },
        { "click": { "elementText": "Sobre" } },
        { "find": { "elementText": "Nossa História" } }
      ]
    }
  ]
}

Use checkLink para validação rápida

{
  "tests": [
    {
      "description": "Validação rápida de links",
      "steps": [
        { "checkLink": { "url": "https://site1.com" } },
        { "checkLink": { "url": "https://site2.com" } },
        { "checkLink": { "url": "https://site3.com" } }
      ]
    }
  ]
}

Configure timeouts apropriados

{
  "tests": [
    {
      "description": "Com timeouts otimizados",
      "steps": [
        {
          "goTo": { 
            "url": "https://site-lento.com",
            "timeout": 30000
          }
        },
        {
          "find": { 
            "elementText": "Conteúdo",
            "timeout": 15000
          }
        }
      ]
    }
  ]
}

Estratégias por Tipo de Projeto

🏢 Documentação Corporativa

Foco: Links, estrutura, conformidade

{
  "tests": [
    {
      "description": "Compliance corporativo",
      "steps": [
        { "find": { "elementText": "Privacy Policy" } },
        { "find": { "elementText": "Terms of Service" } },
        { "find": { "elementText": "GDPR" } },
        { "checkLink": { "url": "https://empresa.com/legal" } }
      ]
    }
  ]
}

🔧 Documentação Técnica

Foco: Comandos, APIs, exemplos funcionais

{
  "tests": [
    {
      "description": "Comandos e APIs funcionais",
      "steps": [
        { "runShell": { "command": "npm", "args": ["--version"] } },
        { "httpRequest": { "url": "https://api.com/health", "method": "GET" } },
        { "checkLink": { "url": "https://github.com/projeto/releases" } }
      ]
    }
  ]
}

📚 Base de Conhecimento

Foco: Busca, navegação, conteúdo acessível

{
  "tests": [
    {
      "description": "Funcionalidade de busca",
      "steps": [
        { "find": { "selector": "input[type='search']" } },
        { "type": { "keys": ["erro comum"] } },
        { "click": { "elementText": "Buscar" } },
        { "find": { "elementText": "Resultados" } }
      ]
    }
  ]
}

🚀 Produto SaaS

Foco: Onboarding, funcionalidades principais, status

{
  "tests": [
    {
      "description": "Status e onboarding",
      "steps": [
        { "checkLink": { "url": "https://status.produto.com" } },
        { "checkLink": { "url": "https://app.produto.com/signup" } },
        { "find": { "elementText": "Free Trial" } },
        { "find": { "elementText": "Getting Started" } }
      ]
    }
  ]
}

Scripts Úteis

Extrair Links de Documentação

# Bash script para extrair links de arquivos markdown
grep -r "http" docs/ | grep -o 'https://[^)]*' | sort | uniq > links.txt

Gerar Teste de Links Automaticamente

# Python script para gerar JSON de teste a partir de lista de links
python3 -c "
import json
with open('links.txt') as f:
    links = [line.strip() for line in f]

test = {
    'tests': [{
        'steps': [{'checkLink': {'url': link}} for link in links]
    }]
}

with open('auto-links-test.spec.json', 'w') as f:
    json.dump(test, f, indent=2)
"

Monitoramento Contínuo

Agende execuções: Use cron ou GitHub Actions
Alertas: Configure notificações quando testes falharem
Relatórios: Mantenha histórico dos resultados
Métricas: Acompanhe percentual de links funcionando

Resultados Esperados

Após implementar esses testes, você terá:

✅ Detecção automática de links quebrados
✅ Validação de estrutura da documentação
✅ Testes de funcionalidades críticas
✅ Screenshots automáticos para comparação visual
✅ Relatórios detalhados em JSON
✅ Integração com CI/CD

O mais importante: Você pode fazer isso SEM MODIFICAR sua documentação existente!

🎯 Conclusão: Start Simple, Scale Smart

Comece hoje mesmo:

5 minutos: Teste 3-5 links principais
30 minutos: Adicione teste de estrutura
2 horas: Configure CI/CD automático
1 semana: Monitore e refine os testes

Benefícios garantidos:

🔍 Detecção precoce de problemas
⚡ Economia de tempo em revisões manuais
📊 Métricas de qualidade da documentação
🤖 Automação completa do processo
💯 Confiança na documentação publicada

Lembre-se:

Comece simples com checkLink
Expanda gradualmente
Automatize tudo
Monitore resultados
Ajuste conforme necessário

Doc Detective = Documentação sempre confiável! 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 795 Commits
.github		.github
.vscode		.vscode
dev		dev
examples		examples
samples		samples
scripts		scripts
src		src
test		test
web-interface		web-interface
.gitignore		.gitignore
CONTRIBUTIONS.md		CONTRIBUTIONS.md
LICENSE		LICENSE
README.md		README.md
doc-detective.svg		doc-detective.svg
icon.png		icon.png
index.js		index.js
package-lock.json		package-lock.json
package.json		package.json
web-gui.md		web-gui.md

Folders and files

Latest commit

History

Repository files navigation

Interface web para o Doc Detective

Como usar

Estratégias para Documentação Existente

1. Teste de Links (Mais Simples e Útil)

2. Teste de Estrutura da Página

3. Teste de APIs (Para Documentação de API)

4. Teste de Navegação

Fluxo de Trabalho Recomendado

Passo 1: Análise da Documentação

Passo 2: Criação de Testes por Prioridade

Passo 3: Automação com CI/CD

Casos de Uso Mais Comuns na Prática

1. README.md - Projeto Open Source

2. Documentação de Instalação/Setup

3. Tutorial Step-by-Step

4. Documentação de API - Casos Reais

5. FAQ e Base de Conhecimento

6. Documentação de Integração

7. Changelog e Release Notes

8. Documentação de Troubleshooting

9. Documentação de Deploy/DevOps

10. Portal do Desenvolvedor

Exemplos Práticos para Diferentes Tipos de Documentação

API Documentation (Como a Nayax)

Tutorial/Guia do Usuário

Documentação de Produto

Dicas Importantes

✅ Faça:

❌ Evite:

Templates Prontos para Usar

Template 1: Teste Básico de Website/Blog

Template 2: E-commerce - Fluxo de Compra

Template 3: SaaS - Dashboard de Usuário

Template 4: Biblioteca/Framework - Documentação Técnica

Template 5: Aplicativo Mobile - Landing Page

Checklist de Implementação Rápida

🚀 Em 15 minutos:

📋 Em 1 hora:

⚙️ Em 1 dia:

Problemas Comuns e Soluções

❌ Problema: "Element not found"

❌ Problema: Links retornando 403/401

❌ Problema: Testes muito lentos

❌ Problema: Screenshots diferentes

💡 Dicas de Performance

Estratégias por Tipo de Projeto

🏢 Documentação Corporativa

🔧 Documentação Técnica

📚 Base de Conhecimento

🚀 Produto SaaS

Scripts Úteis

Extrair Links de Documentação

Gerar Teste de Links Automaticamente

Monitoramento Contínuo

Resultados Esperados

🎯 Conclusão: Start Simple, Scale Smart

Comece hoje mesmo:

Benefícios garantidos:

Lembre-se:

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages