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.

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.