Skip to content

Guia de Depuração

Depure projetos de anotação do Potato — ative o registro detalhado, use flags de depuração, interprete mensagens de erro comuns e solucione problemas de carregamento de dados e validação de esquemas.

O Potato oferece várias flags de linha de comando e opções de configuração para auxiliar na depuração e nos testes de projetos de anotação. Elas são úteis durante o desenvolvimento e a solução de problemas.

Configuração do servidor

Você pode configurar as definições do servidor diretamente no seu arquivo de configuração YAML:

yaml
server:
  port: 8000        # Port to run on (default: 8000)
  host: "0.0.0.0"   # Host to bind to (default: 0.0.0.0)
  debug: false      # Enable Flask debug mode (default: false)

Observação: As flags de linha de comando têm precedência sobre os valores do arquivo de configuração. Por exemplo, -p 9000 substituirá server.port: 8000.

Flags de depuração

--debug

Inicia o Potato em modo de depuração com autenticação simplificada.

bash
potato start config.yaml --debug

Efeitos:

  • Ignora os requisitos normais de login
  • Ativa o registro detalhado
  • Útil para testar rapidamente mudanças de configuração

--debug-log

Controla a saída de registro de depuração para diferentes partes do sistema.

bash
potato start config.yaml --debug --debug-log=all

Opções:

ValorDescrição
allAtiva o registro tanto para a UI (frontend) quanto para o servidor (backend)
uiAtiva apenas o registro no console JavaScript do frontend
serverAtiva apenas o registro Python do backend
noneDesativa todo o registro de depuração

Exemplos:

bash
# Debug frontend issues (JavaScript errors, UI state)
potato start config.yaml --debug --debug-log=ui
 
# Debug backend issues (API calls, data processing)
potato start config.yaml --debug --debug-log=server
 
# Full debugging (both frontend and backend)
potato start config.yaml --debug --debug-log=all
 
# Quiet mode - minimal output
potato start config.yaml --debug --debug-log=none

--debug-phase

Pule diretamente para uma fase ou página específica sem passar pelas fases anteriores. Isso é útil para testar partes específicas de um fluxo de trabalho de anotação.

bash
potato start config.yaml --debug --debug-phase=annotation

Requer: A flag --debug também precisa estar definida.

Nomes de fase válidos:

  • login - Página de login
  • consent - Formulário de consentimento
  • prestudy - Pesquisa pré-estudo
  • instructions - Página de instruções
  • training - Fase de treinamento
  • annotation - Fase principal de anotação
  • poststudy - Pesquisa pós-estudo
  • done - Página de conclusão

Exemplos:

bash
# Jump directly to annotation (most common use case)
potato start config.yaml --debug --debug-phase=annotation
 
# Test post-study survey
potato start config.yaml --debug --debug-phase=poststudy
 
# Test a specific named page
potato start config.yaml --debug --debug-phase=my_custom_survey

Como funciona:

  • Cria automaticamente e faz login de um usuário chamado debug_user
  • Pula todas as fases anteriores à fase especificada
  • O estado do usuário é definido como se ele tivesse concluído todas as fases anteriores

Combinando flags de depuração

As flags podem ser combinadas para diferentes cenários de depuração:

bash
# Quick annotation testing with minimal noise
potato start config.yaml --debug --debug-phase=annotation --debug-log=none
 
# Full debugging of annotation phase
potato start config.yaml --debug --debug-phase=annotation --debug-log=all
 
# Debug only backend while testing post-study
potato start config.yaml --debug --debug-phase=poststudy --debug-log=server

Outras flags úteis

--verbose / -v

Ativa a saída detalhada para o registro geral de operações.

bash
potato start config.yaml -v

--veryVerbose

Ativa a saída muito detalhada com informações detalhadas do estado interno.

bash
potato start config.yaml --veryVerbose

--port / -p

Executa em uma porta específica (útil ao rodar várias instâncias).

bash
potato start config.yaml -p 8080

Ferramentas de desenvolvedor do navegador

Além das flags de linha de comando, use as ferramentas de desenvolvedor do navegador para depuração:

  1. Console: Veja registros e erros JavaScript (F12 ou Cmd+Option+I)
  2. Network: Monitore as chamadas de API entre frontend e backend
  3. Elements: Inspecione o DOM e a estilização CSS
  4. Application: Verifique o armazenamento de sessão e os cookies

Reativando o registro no console

Se o registro da UI foi desativado via --debug-log=server ou --debug-log=none, reative-o no console do navegador:

javascript
enableUIDebug();

Cenários comuns de depuração

Testando um novo esquema de anotação

bash
# Skip to annotation with full logging
potato start config.yaml --debug --debug-phase=annotation --debug-log=all

Depurando problemas de API

bash
# Server-only logging to focus on backend
potato start config.yaml --debug --debug-log=server

Em seguida, use a aba Network do navegador para inspecionar os dados de requisição/resposta.

Testando o fluxo do usuário

bash
# Start from the beginning with UI logging
potato start config.yaml --debug --debug-log=ui

Testes de desempenho

bash
# Minimal logging overhead
potato start config.yaml --debug --debug-phase=annotation --debug-log=none

Solução de problemas

"debug-phase requires --debug flag"

A opção --debug-phase só funciona quando --debug também é especificada:

bash
# Wrong
potato start config.yaml --debug-phase=annotation
 
# Correct
potato start config.yaml --debug --debug-phase=annotation

Fase não encontrada

Se a fase especificada não existir na sua configuração, verifique:

  • Se o nome da fase está escrito corretamente
  • Se a fase está definida no seu arquivo de configuração YAML
  • Para páginas personalizadas, use o nome exato da página presente na sua configuração

Leitura adicional

Para detalhes de implementação, consulte a documentação de origem.