TazHelper Manual

TazHelper turns testers into precise bug reports. On a SliTaz cooking ISO it checks the hardware and the system on its own, asks the tester to try a few applications, then sends one short anonymous report to the SliTaz servers. Developers read the reports, fix what breaks and mark them as done.

Overview

Random testing finds random bugs. TazHelper gives every tester the same short list: what matters most for the next release, in the order the developers need it. The answers come back in one plain text format, so a developer can sort hundreds of them with grep.

PartRole
tazhelper The engine, in POSIX shell: runs the tests, stores the answers, builds and sends the report. Also the command line interface.
tazhelper-gtk The GTK3 window testers use. It holds no logic: every click runs tazhelper.
tests/ One file per test. Adding a test is dropping a file there.
tazhelper.cgi Receives the reports on lab.slitaz.org and files them.
tazhelper-reports Lets developers list, read, count and close the reports, on the server or on their own machine.

Privacy is part of the design: no name, no network address, no serial number ever leaves the computer, the tester reads the whole report before sending it, and nothing is sent without a click on Send.

For testers

Start TazHelper from the menu (System Tools) or from a terminal: 

$ tazhelper

A window opens with three steps, shown at the top. You can go back and forth between them at any time: every answer is kept as soon as you give it, even if you close the window and open it again later in the same session.

1. Checks

Step 1: automatic checks
The automatic checks run as soon as the window opens.

The automatic checks need nothing from you: network, screen, sound, hardware without a driver, crashed programs and kernel errors. Each line gets a green ✓ (works), an orange ! (works partly) or a red ✗ (problem found), with a short explanation. Everything shown here goes into the report: you do not need to describe it again. Check again runs them once more, for example after plugging in a network cable.

2. Applications

Step 2: applications to try
Open each application, use it a little, then say how it went.

Each card asks you to try one application. Click Open, use it for a minute as the card suggests, then choose:

After Partly or Broken, a text field opens: a few words about what you saw help the developers a lot (the page stays blank, no sound in videos). Click the chosen button again to take your answer back. Skip what you cannot test: an untested application is simply left out of the report.

The installer card only asks you to walk through the installer. Run a real installation only on a spare disk or in a virtual machine.

3. Send

Step 3: review and send
The report is shown exactly as it will be sent.

Add a general comment if you like, read the report, then click Send report. On success TazHelper thanks you and shows a reference such as cooking/20261003-081512-3fa9c2d1: quote it on the forum if you want to discuss your report.

No network? Save the report

A network that does not work is exactly the kind of problem worth reporting. If sending fails, click Save to file and choose a USB key. Later, on any SliTaz with a working network: 

$ tazhelper send /media/usb/tazhelper-report-20261003-0815.txt

Without a graphical desktop

Without X, tazhelper runs the same steps in the terminal: it shows the check results, asks about each application (l to launch it, o, p or f for works, partly or broken, Enter to skip), prints the report and asks before sending it.

What a report contains

A report is plain text, one key=value per line, at most 16 KB. System lines come first, then one line per test result, then the comments: 

tazhelper_version=0.1
date=2026-10-03
release=cooking
flavor=core
arch=x86_64
kernel=6.12.89-slitaz
boot=efi
live=yes
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
KeyMeaning
dateDay of the test, UTC, no time
release, flavorFrom /etc/slitaz-release and /etc/slitaz/flavor (unknown if absent)
boot, liveefi or bios; yes when running from the live CD
gpuPCI vendor:device of the display controller and its driver
test.<id>ok, partial or fail
test.<id>.infoWhat an automatic test found
test.<id>.commentWhat the tester wrote about an application
commentThe general comment
triage.*Added by developers when the report is dealt with (see below)

New keys may appear in later versions: tools reading reports must ignore the keys they do not know.

Privacy

TazHelper never collects a MAC address, a hostname, a user name, an IP address or a serial number. As a safety net, every value also goes through a filter that blanks MAC and IPv4 addresses, /home/ paths, the user name and the host name, including in what the tester types. The server does not store the IP address of the sender either, and the web server does not log requests to the report address.

For developers: triage

Reports land on foyer, in /home/slitaz/vhosts/lab.slitaz.org/tazhelper-reports/, one directory per release. The state of a report is the directory it sits in: no database, no lost update. 

tazhelper-reports/
├── cooking/                          ← inbox: reports to deal with
│   ├── 20261003-081512-3fa9c2d1.txt
│   ├── 20261003-094401-b71e0a44.txt
│   └── done/                         ← reports dealt with
│       └── 20261002-230023-57db9d9d.txt
└── 5.1-rc1/
    └── ...

A report name starts with the UTC date and time it was received, so a plain listing is in chronological order. The files belong to the devs group: every developer with an account on foyer can read and triage them.

On 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

An id can be shortened to any unique start. done moves the report to done/ and appends who closed it, when, and your note: 

triage.date=2026-10-03
triage.by=pankso
triage.note=rtw88 firmware added, wok r28600

Write the fix in the note (a wok or tool revision, a forum link): it is what the next developer will look for. A report closed by mistake goes back with reopen; spam or test reports go away with delete.

On your own machine

For long sessions, work on a copy: pull brings every report to ~/tazhelper-reports (private, mode 700) in one ssh connection. Reading, counting and searching then happen locally; done, reopen and delete are run on foyer through ssh, then the copy is refreshed. This needs the foyer-vps ssh alias, the one used to push to 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 blocks an address that opens many ssh connections in a short time: prefer one pull and local reading over many remote commands, or share one connection: open it with ssh -fN -o ControlMaster=yes -o ControlPath=/tmp/fy.sock foyer-vps and set TAZHELPER_SSH="ssh -o ControlPath=/tmp/fy.sock".

A triage routine

  1. pull, then stats: which test fails most, on which arch and flavor? Fix the biggest problem first.
  2. grep 'test.<id>=fail' to read all the reports of one problem together: the .info and .comment lines usually point to the package.
  3. Fix, cook, push as usual. Then close every report of that problem with done and the revision in the note.
  4. A report that needs no fix (user error, already known) is closed too, with a short note saying why.

Writing a test

A test is one small file in tests/auto/ (no user action) or tests/manual/ (the tester tries an application). Drop a file there and it shows up in the window, the command line and the reports: no other change is needed. The file is a shell fragment, sourced in a subshell:

VariableMeaning
IDUnique name, a-z 0-9 _ - only: it is the report key
TITLEShort name shown to the tester
PRIORITY1 = most important. Tests are sorted by priority, then by ID
DESCOne or two sentences: what to do, what to look at
run()Automatic test: prints one line, returns 0 (ok), 1 (fail) or 2 (partial)
LAUNCHManual test: command started by the Open button

An automatic test

# 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"
}

A manual test

# 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"

Rules for a good test

Command line

tazhelper

CommandAction
tazhelperOpen the window, or the interactive mode without X
tazhelper cliInteractive mode in the terminal
tazhelper autoRun the automatic tests and print the results
tazhelper listList the available tests
tazhelper mark <id> <ok|partial|fail|none> [comment]Store the answer for a manual test (none takes it back)
tazhelper comment <text>Set the general comment
tazhelper reportPrint the report exactly as it will be sent
tazhelper send [file]Send the report, or a report saved earlier
tazhelper save [file]Save the report to a file
tazhelper resetForget all answers of this session
tazhelper launch <id>Start the application of a manual test
tazhelper tests, resultsMachine readable lists used by the window

tazhelper-reports

CommandAction
list [--done|--all]Reports to deal with, oldest first: id, release, arch, flavor, failed and partial tests, comment
show <id>Print a report
stats [--all]Results per test, then reports per arch and flavor
grep <regex> [--all]Reports with a line matching the regex
done <id> [note]Close a report, with a note
reopen <id>Put a closed report back in the inbox
delete <id>Remove a report for good (spam, test)
pullCopy all reports from foyer to the local copy

Configuration

/etc/slitaz/tazhelper.conf: 

# Where reports are sent (HTTP POST, text/plain).
URL="https://lab.slitaz.org/tazhelper/report.cgi"

# Seconds before giving up on a test or on sending.
TIMEOUT="20"
VariableUse
TAZHELPER_URL, TAZHELPER_TIMEOUTOverride the configuration file
TAZHELPER_STATEWhere answers of the session are kept (default ~/.cache/tazhelper, in RAM on a live CD)
TESTS_DIRTest directory (default /usr/share/tazhelper/tests)
TAZHELPER_REPORTStazhelper-reports: the report directory to work on
TAZHELPER_REMOTEtazhelper-reports: ssh host of the server (default foyer-vps, empty for a standalone copy)
TAZHELPER_SSHtazhelper-reports: ssh command used for the server, to reuse a shared connection

Run from a source checkout, ./tazhelper uses the lib/, tests/ and etc/ of the checkout, and the window built in gui/: handy to try a new test before installing anything.

Server

tazhelper.cgi is a small shell CGI. It treats everything it receives as hostile: the body is measured, checked with grep and moved to a file, never sourced, evaluated or executed. A report is refused when it is larger than 16 KB, holds anything but key=value lines, a control character or a line longer than 1024 bytes, or does not start with tazhelper_version=. An unusual release name is filed under unknown/. The answer is OK <release>/<id> or ERROR <reason>.

On foyer

Testing the CGI locally

make check feeds good and bad reports to the CGI without any web server. To try the whole chain with busybox httpd (with an empty configuration file: the SliTaz default one breaks CGI scripts given by relative path): 

$ 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

Files

PathContent
/usr/bin/tazhelperEngine and command line
/usr/bin/tazhelper-gtkGTK3 window
/usr/lib/tazhelper/libtazhelper.shTests, report, sending
/usr/share/tazhelper/tests/{auto,manual}/Test files
/etc/slitaz/tazhelper.confConfiguration
~/.cache/tazhelper/Answers of the session, last report sent
/usr/share/doc/tazhelper/This manual

Source and license

TazHelper is free software under the BSD license. Source: hg.slitaz.org/tazhelper. Questions and ideas are welcome on the SliTaz forum.