rsyslog/tests

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