pgCluu regression tests
=======================

Run all tests:

	perl Makefile.PL && make && make test

or directly:

	prove t/

Requirements: Perl with Test::More and JSON::PP (core modules), the CGI
module for the pgcluu.cgi tests (libcgi-pm-perl on Debian/Ubuntu) and node
for the javascript syntax test. Tests whose requirements are missing are
skipped.

The scripts are never modified by the tests: they are run as commands, or
some of their functions are extracted from the source and evaluated alone.


Tests
-----

  01_syntax.t          compilation of the scripts, --help, --version and
                       --list-metric.
  02_collectd_sql.t    SQL queries generated by pgcluu_collectd for each
                       PostgreSQL version from 9.6 to 19 (snapshot) and
                       version specific rules (pg_stat_io, pg_aios, ...).
  03_report.t          pgcluu reports generated from the fixtures, compared
                       with the expected results, and deterministic output.
  04_report_js.t       javascript syntax of every report page (node).
  05_incremental.t     cache built in two passes (pgcluu -C) compared with a
                       report built at once.
  06_sysinfo.t         parsing of the PostgreSQL version in sysinfo.txt and
                       backend_minimum_version(), pgcluu and pgcluu.cgi.
  07_cgi.t             every action of pgcluu.cgi from the csv files and from
                       the cache files, compared with the expected results
                       and with the static report for the pg_stat_io pages.
  08_cgi_action_map.t  each CGI action loads the cache files it needs.
  09_collectd_live.t   collect on a running PostgreSQL server and report
                       generation. Skipped unless PGCLUU_TEST_LIVE is set,
                       uses the PGHOST, PGPORT, PGUSER, PGPASSWORD and
                       PGDATABASE variables, the user must be superuser or
                       member of pg_monitor. Example:

	PGCLUU_TEST_LIVE=1 PGHOST=/tmp PGPORT=5432 PGUSER=postgres prove -v t/09_collectd_live.t

                       Set PGCLUU_TEST_SAME_HOST=1 when the server processes
                       are visible from the host running the test (not in a
                       container) to also test the postmaster limits.

  10_kernel.t          cgroup files parsing and kernel_stats.csv format of
                       pgcluu_collectd, formatting of the postmaster limits,
                       kernel pages of the reports, shmmax/shmall not shown.
  11_install.t         custom source installation and Apache configuration
                       activation in a temporary tree (requires make).
  12_cluster_total.t   cluster totals (database and tablespace sizes,
                       connections, prepared transactions, buffercache,
                       conflicts) are the sum of the per database values
                       and the conflicts are not counted twice when a csv
                       line is read twice or two lines have the same
                       timestamp: duplicated timestamps, overlapping runs of
                       pgcluu -C, trailing slash in the CGI INPUT_DIR.
  13_cache_lock.t      only one pgcluu -C at a time, cache files replaced
                       atomically, readers wait while they are replaced,
                       normalization of the input directory in pgcluu and
                       pgcluu.cgi (the csv files are not read again).
  14_pidstat.t         pidstat reports from t/pidstat (sysstat 12.6.1
                       output): columns read by name, values summed over the
                       processes, older format, cache built in several
                       passes with a sample cut in the middle of a line and
                       lines read again, samples with the same timestamp,
                       pgcluu.cgi from the csv and the cache files.

Known limitations are reported as TODO tests: they are shown by prove but
do not make the tests fail. They are listed in %KNOWN_DIFF (05_incremental.t)
and %KNOWN_CSV_DIFF (07_cgi.t).


Fixtures and expected results
-----------------------------

t/fixtures/pg16, pg17, pg18: statistics collected by pgcluu_collectd during
about one minute on PostgreSQL 16, 17 and 18 with small shared_buffers and
temp_buffers under a mixed workload (bulk load, sequential scans, updates,
vacuum, temporary tables, checkpoints). sar and pidstat
are not collected.

The pg18 fixture also contains the system information (sysinfo.txt) with the
kernel parameters and the limits of the postmaster, and kernel_stats.csv.
Paths, mount points, processes and packages of the collect host were
replaced by usual values of a PostgreSQL server. In kernel_stats.csv the host
counters are real values collected separately and aligned on the snapshots
of the fixture, the cgroup counters are synthetic (no cgroup v2 controller
was available on the collect host).

t/expected/*.json: expected results. Report pages are reduced to their graph
titles, series labels, data points and table rows (sorted), generation dates
and the menu are ignored.

When a change of the output is intended, regenerate the expected results and
review them before committing:

	PGCLUU_REGEN=1 prove t/
	git diff t/expected/

Set PGCLUU_KEEP_TMP=1 to keep the temporary directories of a run.
