# rsyslog testbench quick reference
This directory houses the rsyslog Automake test suite. The
[`tests/AGENTS.md`](./AGENTS.md) file gives AI agents authoring guidance and
conventions; this README focuses on operators and contributors who need to run
the suite.
Most scripts validate a single module, but complex end-to-end scenarios are
welcome. For a minimal example, examine `rtinit.c`, which performs a simple
runtime init/deinit cycle.
## Quickstart
Bootstrap the build tree before attempting to run tests:
```sh
./autogen.sh
./configure --enable-testbench
make -j$(nproc)
make check
```
`make check` compiles the helper binaries, prepares fixtures, and then executes
the entire suite. Use <kbd>Ctrl</kbd>+<kbd>C</kbd> to stop an ongoing run.
## Running individual scenarios
```
make <test-name>.log
```
For example, `make imfile-basic.log` produces `imfile-basic.log` and
`imfile-basic.trs`. Remove those files before re-running to clear cached
results. When you need Automake’s logging but do not want to type the `.log`
suffix, use:
```
make check TESTS='imfile-basic.sh'
```
You can also execute scripts directly (`./tests/imfile-basic.sh`) for quicker
iteration, though Automake will not capture transcripts.
## Harness conventions
- Source `diag.sh` at the top of every shell test: `. "$srcdir/diag.sh"`.
- Prefer helpers such as `cmp_exact` and `require_plugin` over ad-hoc shell so
diagnostics stay consistent. See `tests/AGENTS.md` for a longer checklist.
- Name Valgrind-enabled wrappers with the `-vg.sh` suffix and Helgrind-enabled
scripts with `-vgthread.sh`. `tests/timereported-utc-vg.sh` illustrates how to
source the base scenario rather than duplicating it and how to trim emitted
messages when a slow test would otherwise become prohibitively long under
Valgrind. Some legacy wrappers predate this pattern; follow the newer style
when adding or refactoring coverage.
## Environment setup snippets
### MariaDB/MySQL
```
echo "create user 'rsyslog'@'localhost' identified by 'testbench';" | mysql -u root
mysql -u root < ../plugins/ommysql/createDB.sql
echo "grant all on Syslog.* to 'rsyslog'@'localhost';" | mysql -u root
```
### openSUSE tips
Use the graphical `yast2` tool to adjust hostname and firewall rules. SSH
access is disabled in the firewall by default.
## Debugging aids
To pause a test and attach a debugger, add the following guard:
```sh
. "$srcdir/diag.sh" startup
if [ -n "${USE_GDB:-}" ]; then
echo "attach gdb here"
sleep 54321 || :
fi
```
Run the scenario in the background, wait for the prompt, and attach GDB:
```
USE_GDB=1 make mytest.sh.log &
tail -f mytest.sh.log # wait for "attach gdb here"
gdb ../tools/rsyslogd <rsyslogd-pid>
```
After continuing in GDB, terminate the `sleep` with `pkill -f 54321` (or locate
the PID via `ps -ef | grep 54321`).
## Core dump analysis
The harness can inspect core dumps automatically. Ensure the operating system
allows them to be written:
1. Set `ulimit -c unlimited` (you might need to adjust `/etc/security/limits.conf`
to raise `soft core unlimited`).
2. Confirm `/proc/sys/kernel/core_pattern` is set to `core`. Systemd-based
distributions often redirect cores elsewhere; revert to the classic format
with `sudo bash -c 'echo core > /proc/sys/kernel/core_pattern'`.
Avoid applying these tweaks on production hosts.