# 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.
The `tests/` subtree is the single Automake-owned test area for rsyslog. The
shell-driven testbench remains here, and fast C unit-test sources for isolated
helpers are organized in [`tests/unit/`](./unit/README.md) but are built and
run by [`tests/Makefile.am`](./Makefile.am).
## 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, including the unit tests sourced from `tests/unit/`. 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.
To run the linkedlist unit test through the shared harness from the repository
root:
```
make check TESTS='runtime_unit_linkedlist'
```
## Harness conventions
- Include `diag.sh` at the top of every shell test using the POSIX `.` command: `. "$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
include the base scenario using the `.` command 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.