mirror of
https://github.com/rsyslog/rsyslog.git
synced 2025-12-13 04:50:41 +01:00
b83b56500b
* AI: align AGENTS.md and README; expand harness tips This refines testbench docs for both AI agents and human operators. Goal: clearer authoring guidance and a smoother quickstart so agents produce higher-quality tests and contributors run them reliably. Before/After: scattered guidance across files -> cross-linked docs with explicit helper usage, Valgrind wrapper patterns, and quickstart. Non-technical rationale: This improves maintainability and AI readiness by giving agents concrete patterns and reducing duplicate boilerplate. It also aligns operator docs with the harness so CI and local runs behave consistently. With the help of AI Agents: ChatGPT, gemini
106 lines
3.3 KiB
Plaintext
106 lines
3.3 KiB
Plaintext
# 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.
|