O TazHelper transforma testadores em relatórios de bugs precisos. Em uma ISO cooking do SliTaz, ele verifica o hardware e o sistema sozinho, pede ao testador para experimentar alguns aplicativos e então envia um relatório curto e anônimo para os servidores do SliTaz. Os desenvolvedores leem os relatórios, corrigem o que está quebrado e os marcam como concluídos.
- Visão Geral
- Para testadores
- O que um relatório contém
- Para desenvolvedores: triagem
- Escrevendo um teste
- Linha de comando
- Configuração
- Servidor
- Arquivos
- Código-fonte e licença
Visão Geral
Testes aleatórios encontram bugs aleatórios. O TazHelper dá a cada
testador a mesma lista curta: o que mais importa para a próxima versão,
na ordem que os desenvolvedores precisam. As respostas voltam em um
formato de texto simples, então um desenvolvedor pode ordenar centenas
delas com grep.
| Parte | Função |
|---|---|
tazhelper |
O motor, em shell POSIX: executa os testes, armazena as respostas, constrói e envia o relatório. Também é a interface de linha de comando. |
tazhelper-gtk |
A janela GTK3 que os testadores usam. Não contém lógica:
cada clique executa tazhelper. |
tests/ |
Um arquivo por teste. Adicionar um teste é apenas colocar um arquivo ali. |
tazhelper.cgi |
Recebe os relatórios em lab.slitaz.org e os arquiva. |
tazhelper-reports |
Permite que desenvolvedores listem, leiam, contem e fechem os relatórios no servidor ou em sua própria máquina. |
A privacidade faz parte do design: nenhum nome, endereço de rede, número de série jamais sai do computador, o testador lê o relatório inteiro antes de enviá-lo e nada é enviado sem um clique em Enviar.
Para testadores
Inicie o TazHelper pelo menu (Ferramentas do Sistema) ou de um terminal:
$ tazhelper
Uma janela abre com três etapas, mostradas no topo. Você pode ir e voltar entre elas a qualquer momento: cada resposta é mantida assim que você a dá, mesmo se fechar a janela e abri-la novamente mais tarde na mesma sessão.
1. Verificações
As verificações automáticas não precisam de nada de você: rede, tela, som, hardware sem driver, programas travados e erros do kernel. Cada linha recebe um ✓ verde (funciona), um ! laranja (funciona parcialmente) ou um ✗ vermelho (problema encontrado) com uma explicação curta. Tudo mostrado aqui vai para o relatório: você não precisa descrever novamente. Check again executa-as mais uma vez, por exemplo depois de conectar um cabo de rede.
2. Aplicativos
Cada cartão pede para você tentar um aplicativo. Clique em Abrir, use-o por um minuto como o cartão sugere, depois escolha:
- Funciona: tudo que você tentou estava bem.
- Parcialmente: funciona, mas algo está errado ou feio.
- Quebrado: não inicia, trava ou não consegue fazer seu trabalho.
Depois de Parcialmente ou Quebrado, um campo de
texto abre: algumas palavras sobre o que você viu ajudam muito os
desenvolvedores (a página fica em branco
, sem som nos vídeos
).
Clique no botão escolhido novamente para retirar sua resposta.
Pule o que não puder testar: um aplicativo não testado é simplesmente
deixado de fora do relatório.
O cartão do instalador apenas pede para você percorrer o instalador. Execute uma instalação real apenas em um disco sobressalente ou em uma máquina virtual.
3. Enviar
Adicione um comentário geral se quiser, leia o relatório, depois clique em
Enviar relatório (send report). Em caso de sucesso, o TazHelper
agradece e mostra uma referência como cooking/20261003-081512-3fa9c2d1:
cite-a no fórum se quiser discutir seu relatório.
Sem rede? Salve o relatório
Uma rede que não funciona é exatamente o tipo de problema que vale a pena relatar. Se o envio falhar, o TazHelper mantém o relatório em sua caixa de saída e o envia com o próximo relatório que passar. Para enviá-lo de outro computador, clique em Salvar em arquivo (Save do file) e escolha uma chave USB. Depois, em qualquer SliTaz com rede funcionando:
$ tazhelper send /media/usb/tazhelper-report-20261003-0815.txt
Em um computador sem SliTaz, abra filature.slitaz.org/report e cole o conteúdo do arquivo.
Sem área de trabalho gráfica
Sem o servidor gráfico X, tazhelper executa as mesmas
etapas no terminal: mostra os resultados das verificações, pergunta
sobre cada aplicativo (l para lançar, o, p
ou f para funciona, parcialmente ou quebrado, Enter para pular),
imprime o relatório e pergunta antes de enviá-lo.
O que um relatório contém
Um relatório é texto simples, um chave=valor por linha,
no máximo 16 KB. As linhas do sistema vêm primeiro, depois uma linha
por resultado de teste, depois os comentários:
tazhelper_version=0.1 date=2026-10-03 release=cooking flavor=core iso_date=20261011 arch=x86_64 kernel=6.12.89-slitaz boot=efi live=yes media=live-usb virt=none packages=402 cpu=Intel(R) Core(TM) i5-3320M CPU @ 2.60GHz cpu_cores=4 ram_mb=7841 gpu=8086:0166 i915 locale=fr_FR.UTF-8 test.network=ok test.network.info=wlan0 wireless iwlwifi, mirror reachable test.browser=partial test.browser.comment=Pages load, but fonts look blurry comment=Thanks for 5.1, boots fast on my old ThinkPad
| Chave | Significado |
|---|---|
date | Dia do teste, UTC, sem hora |
release | De /etc/slitaz-release |
flavor, iso_date | A ISO da qual o sistema vem, live ou instalado: linhas 1 e 2 de /etc/slitaz/flavor, escritas por tazlito e metier (unknown se ausente) |
boot, live | efi ou bios; yes quando executando do live CD |
media | install-hd ou install-usb: o disco que contém o sistema; live-cd, live-usb ou live-unknown: uma melhor suposição, a mídia live não está montada |
virt | none em hardware real, senão qemu, virtualbox, vmware, hyperv, xen ou other |
packages | Número de pacotes instalados |
gpu | PCI fornecedor:dispositivo do controlador de vídeo e seu driver |
test.<id> | ok, partial ou fail |
test.<id>.info | O que um teste automático encontrou |
test.<id>.comment | O que o testador escreveu sobre um aplicativo |
comment | O comentário geral |
triage.* | Adicionado por desenvolvedores quando o relatório é tratado (veja abaixo) |
Novas chaves podem aparecer em versões posteriores: ferramentas que leem relatórios devem ignorar as chaves que não conhecem.
Privacidade
O TazHelper nunca coleta um endereço MAC, hostname, nome de usuário,
endereço IP ou número de série. Como rede de segurança, todo valor
também passa por um filtro que apaga endereços MAC e IPv4, caminhos
/home/, o nome de usuário e o hostname, incluindo no que
o testador digita. O servidor também não armazena o endereço IP do
remetente e o servidor web não registra requisições para o endereço
do relatório.
Para desenvolvedores: triagem
Relatórios chegam em foyer, em /home/slitaz/vhosts/lab.slitaz.org/tazhelper-reports/,
um diretório por versão. O estado de um relatório é o diretório em
que ele está: sem banco de dados, sem atualização perdida.
tazhelper-reports/
├── cooking/ ← caixa de entrada: relatórios para tratar
│ ├── 20261003-081512-3fa9c2d1.txt
│ ├── 20261003-094401-b71e0a44.txt
│ └── done/ ← relatórios tratados
│ └── 20261002-230023-57db9d9d.txt
└── 5.1-rc1/
└── ...
O nome de um relatório começa com a data e hora UTC em que foi recebido,
então uma listagem simples está em ordem cronológica. Os arquivos
pertencem ao grupo devs: todo desenvolvedor com uma
conta em foyer pode ler e fazer a triagem deles.
Em foyer
$ ssh foyer-vps $ tazhelper-reports list 20261003-081512-3fa9c2d1 cooking x86_64 core fail:network "No wifi on my Dell..." 20261003-094401-b71e0a44 cooking i486 core partial:browser 2 report(s) $ tazhelper-reports show 20261003-0815 $ tazhelper-reports done 20261003-0815 rtw88 firmware added, wok r28600
Um id pode ser abreviado para qualquer início único.
done (feito) move o relatório para done/ e
anexa quem o fechou, quando e sua nota:
triage.date=2026-10-03 triage.by=pankso triage.note=rtw88 firmware added, wok r28600
Escreva a correção na nota (uma revisão de wok ou ferramenta, um link
do fórum): é o que o próximo desenvolvedor procurará. Um relatório
fechado por engano volta com reopen (reabrir); relatórios
de spam ou teste vão embora com delete.
Em sua própria máquina
Para sessões longas, trabalhe em uma cópia: pull traz
cada relatório para ~/tazhelper-reports (privado, modo 700)
em uma conexão ssh. Ler, contar e pesquisar acontecem localmente;
done (feito), reopen (reabrir) e delete
(deletar) são executados em foyer através de ssh, depois a
cópia é atualizada. Isso precisa do alias ssh foyer-vps,
o mesmo usado para fazer push para hg.
$ tazhelper-reports pull 12 report(s) to deal with in /home/tux/tazhelper-reports $ tazhelper-reports stats 12 report(s) Test ok partial fail browser 9 2 1 network 7 0 5 ... arch=i486 4 arch=x86_64 8 flavor=core 7 flavor=firefox 5 $ tazhelper-reports grep 'test.network=fail' $ tazhelper-reports grep 'gpu=10de:' --all
foyer bloqueia um endereço que abre muitas conexões ssh em pouco tempo:
prefira um pull e leitura local sobre muitos comandos
remotos, ou compartilhe uma conexão: abra-a com
ssh -fN -o ControlMaster=yes -o ControlPath=/tmp/fy.sock foyer-vps
e defina TAZHELPER_SSH="ssh -o ControlPath=/tmp/fy.sock".
Uma rotina de triagem
pull, depoisstats: qual teste falha mais, em qual arch e flavor? Corrija o maior problema primeiro.grep 'test.<id>=fail'para ler todos os relatórios de um problema juntos: as linhas.infoe.commentgeralmente apontam para o pacote.- Corrija, cozinhe, faça push como de costume. Depois feche cada
relatório daquele problema com
donee a revisão na nota. - Um relatório que não precisa de correção (erro do usuário, já conhecido) também é fechado, com uma nota curta dizendo por quê.
Escrevendo um teste
Um teste é um arquivo pequeno em tests/auto/ (sem ação
do usuário) ou tests/manual/ (o testador tenta um
aplicativo). Coloque um arquivo ali e ele aparece na janela, linha
de comando e relatórios: nenhuma outra mudança são necessárias.
O arquivo é um fragmento de shell, carregado em um subshell:
| Variável | Significado |
|---|---|
ID | Nome único, apenas a-z 0-9 _ -: é a chave do relatório |
TITLE | Nome curto mostrado ao testador |
PRIORITY | 1 = mais importante. Testes são ordenados por prioridade, depois por ID |
DESC | Uma ou duas frases: o que fazer, o que observar |
run() | Teste automático: imprime uma linha, retorna 0 (ok), 1 (fail) ou 2 (partial) |
LAUNCH | Teste manual: comando iniciado pelo botão Abrir |
NEEDS | Opcional: comandos que devem estar instalados, senão o teste não é mostrado (sem teste de navegador em uma flavor sem navegador web) |
TIME | Opcional: tempo limite de um teste automático em segundos, para um teste lento (reprise). Padrão: TIMEOUT, 20 s |
Um teste automático
# Sound: ALSA sees at least one sound card.
ID="sound"
TITLE="Sound card"
PRIORITY="2"
DESC="Checks that the kernel found a sound card (ALSA)."
run() {
if [ ! -f /proc/asound/cards ]; then
echo "no ALSA support in the kernel"
return 1
fi
cards="$(sed -n 's/^ *[0-9]* \[[^]]*\]: //p' /proc/asound/cards)"
if [ -z "$cards" ]; then
echo "no sound card found"
return 1
fi
echo "$cards"
}
Um teste manual
# Manual: the hard disk installer. Never install on the tester's disk. ID="installer" TITLE="Installer" PRIORITY="2" DESC="Walk through the installer up to the last step. Only run the installation on a spare disk or in a virtual machine." LAUNCH="subox tazinst-gtk" NEEDS="tazinst-gtk"
Regras para um bom teste
- Shell POSIX para busybox ash, sem bash: o teste deve rodar na máquina i486 mais antiga suportada.
run()executa como o testador, sem root em seu próprio shell e é parado após 20 segundos. Não deve mudar o sistema.- Apenas a primeira linha impressa é mantida: faça-a dizer o que foi encontrado, não apenas erro. Mantenha-a abaixo de 500 caracteres.
- Nunca imprima dados pessoais. O filtro de privacidade é uma rede de segurança, não uma licença.
partialé para funciona, mas: um driver de fallback ou um erro não fatal. Mantenhafailpara o que um usuário chamaria de quebrado.- Verifique um novo teste com
tazhelper autoemake checkantes de fazer commit.
Linha de comando
tazhelper
| Comando | Ação |
|---|---|
tazhelper | Abre a janela ou o modo interativo sem X |
tazhelper cli | Modo interativo no terminal |
tazhelper auto | Executa os testes automáticos e imprime os resultados |
tazhelper list | Lista os testes disponíveis |
tazhelper mark <id> <ok|partial|fail|none> [comment] | Armazena a resposta para um teste manual (none a retira) |
tazhelper comment <text> | Define o comentário geral |
tazhelper report | Imprime o relatório exatamente como será enviado |
tazhelper send [file] | Envia o relatório ou um relatório salvo anteriormente |
tazhelper save [file] | Salva o relatório em um arquivo |
tazhelper reset | Esquece todas as respostas desta sessão |
tazhelper launch <id> | Inicia o aplicativo de um teste manual |
tazhelper tests, resultscode> | Listas legíveis por máquina usadas pela janela |
tazhelper-reports
| Comando | Ação |
|---|---|
list [--done|--all] | Relatórios para tratar, mais antigos primeiro: id, release, arch, flavor, testes falhos e parciais, comentários |
show <id> | Imprime um relatório |
stats [--all] | Resultados por teste, depois relatórios por arch e flavor |
grep <regex> [--all] | Relatórios com uma linha correspondendo à regex |
done <id> [note] | Fecha um relatório com uma nota |
reopen <id> | Coloca um relatório fechado de volta na caixa de entrada |
delete <id> | Remove um relatório para sempre (spam, teste) |
pull | Copia todos os relatórios de foyer para a cópia local |
Configuração
/etc/slitaz/tazhelper.conf:
# Onde os relatórios são enviados (HTTP POST, text/plain). URL="https://filature.slitaz.org/report" # Segundos antes de desistir de um teste ou do envio. TIMEOUT="20"
| Variável | Uso |
|---|---|
TAZHELPER_URL, TAZHELPER_TIMEOUT | Sobrescrevem o arquivo de configuração |
TAZHELPER_STATE | Onde as respostas da sessão são mantidas (padrão ~/.cache/tazhelper, em RAM em um live CD) |
TESTS_DIR | Diretório de testes (padrão /usr/share/tazhelper/tests) |
TAZHELPER_REPORTS | tazhelper-reports: o diretório de relatórios para trabalhar |
TAZHELPER_REMOTE | tazhelper-reports: host ssh do servidor (padrão foyer-vps, vazio para uma cópia standalone) |
TAZHELPER_SSHcode> | tazhelper-reports: comando ssh usado para o servidor reutilizar uma conexão compartilhada |
Executado de um checkout de código-fonte, ./tazhelper usa o
lib/, tests/ e etc/ do checkout
e a janela construída em gui/: útil para testar um novo
teste antes de instalar qualquer coisa.
Servidor
tazhelper.cgi é um pequeno CGI em shell. Trata tudo que
recebe como hostil: o corpo é medido, verificado com grep
e movido para um arquivo, nunca carregado, avaliado ou executado.
Um relatório é recusado quando é maior que 16 KB, contém qualquer
coisa além de linhas chave=valor, um caractere de controle
ou uma linha maior que 1024 bytes ou não começa com
tazhelper_version=. Um nome de release incomum é arquivado
em unknown/. A resposta é OK <release>/<id>
ou ERROR <reason>.
Filature
Relatórios vão para Filature, em https://filature.slitaz.org/report,
que aceita este formato como está. Desenvolvedores os revisam com
fil reports ou a página Relatórios para revisão do Filature;
uma vez aceitos, são públicos em /tazhelper.
Até outubro de 2026 uma cópia deste CGI rodava em lab.slitaz.org.
Ela foi aposentada; os relatórios que recebeu foram importados para o
Filature com fil tazhelper-import e permanecem em
tazhelper-reports/ em foyer, onde tazhelper-reports
ainda pode lê-los. server/tazhelper.cgi permanece para
uma configuração standalone.
Testando o CGI localmente
make check alimenta relatórios bons e ruins para o CGI
sem nenhum servidor web. Para testar toda a cadeia com busybox httpd
(com um arquivo de configuração vazio: o padrão do SliTaz quebra
scripts CGI dados por caminho relativo):
$ mkdir -p www/cgi-bin && cp server/tazhelper.cgi www/cgi-bin/ $ : > httpd.conf $ TAZHELPER_REPORTS=$PWD/reports busybox httpd -f -c httpd.conf \ -p 127.0.0.1:8099 -h $PWD/www & $ TAZHELPER_URL=http://127.0.0.1:8099/cgi-bin/tazhelper.cgi tazhelper send
Arquivos
| Caminho | Conteúdo |
|---|---|
/usr/bin/tazhelper | Motor e linha de comando |
/usr/bin/tazhelper-gtk | Janela GTK3 |
/usr/lib/tazhelper/libtazhelper.sh | Testes, relatório, envio |
/usr/share/tazhelper/tests/{auto,manual}/ | Arquivos de teste |
/etc/slitaz/tazhelper.conf | Configuração |
~/.cache/tazhelper/ | Respostas da sessão, último relatório enviado |
/usr/share/doc/tazhelper/ | Este manual |
Código-fonte e licença
TazHelper é software livre sob a licença BSD. Código-fonte: hg.slitaz.org/tazhelper. Perguntas e ideias são bem-vindas no fórum do SliTaz.