tests/README - main - githubmirror/rsyslog

tests/README
132 строки5 KB
Rainer Gerhards
testbench: detect tcpflood aborts
28 июн 2026, 15:09
28 июн 2026, 15:09bba7b50
# 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

Core files are best-effort diagnostics, not the test oracle. The harness tries
to enable them with `ulimit -c unlimited`, but crash collectors such as
`systemd-coredump`, `apport`, container policy, file permissions, or size limits
may redirect or suppress local files. On failure, `diag.sh` prints the active
core policy (`kernel.core_pattern`, `kernel.core_uses_pid`, and
`fs.suid_dumpable` when available).

The harness analyzes a core only when it can attribute the file to the expected
process by pid/executable metadata, or when the filename is clearly
test-specific via `RSYSLOG_DYNNAME`. Generic `core.*` files from parallel or
stale tests are ignored unless ownership is proven. If `core_pattern` pipes
crashes to an external collector, generic local core scanning is skipped.
Valgrind `vgcore.*` files are handled separately because they belong to the
supervised Valgrind run and remain a Valgrind failure signal.

For local debugging you may still switch a disposable development host to a
classic core pattern such as `core.%e.%p`, but avoid applying such changes on
production hosts.

The `tcpflood` shell helper configures and validates a per-invocation
proper-termination marker. Direct `./tcpflood` invocations can use `-q <file>`
for the same final-exit marker when the test needs tcpflood abort detection.
Tests that intentionally trigger a tcpflood send failure should call
`tcpflood --check-only` and assert the rsyslog-side result.