Testing Your Installation

pg_health_framework ships with its own automated test suite. You don't need to run it to use the framework, but it's a useful way to confirm your build works before relying on it, and it's exactly what runs automatically on every change to the project itself.

make test

This single command:

1. Provisions a throwaway PostgreSQL cluster of its own — a fresh, temporary data directory and a Unix socket connection with no network port bound, so it can't collide with a PostgreSQL server you already have running.
2. Installs the extension into that throwaway cluster and seeds the built-in catalog.
3. Runs test/validate.sql — 46 sections that exercise essentially every feature this site documents: the full catalog and suite lifecycle, run hooks, thresholds, debounce (see How Threshold Evaluation Works), blackout windows, minimum report intervals, the alert-status projection, notifications — on_change and on_state, the durable outbox, and on-event per-occurrence firing, p_critical_only (see Scheduling Health Checks), pghf.friendly_time(), evaluator_routine's invocation-count guarantee, inactivating namespaces and checks, resetting to defaults, retention, the access-control rules, and the reporting functions — all with the pg_relay extension deliberately absent, since that's the common deployment shape.
4. Only after all of that passes, and only where this PostgreSQL build has pg_relay available (skipped with a notice otherwise): installs pg_relay and runs the parallel-execution integration tests — real enqueueing, worker-side execution, and a live end-to-end run against a concurrently-running worker (the real pg_relay Processor daemon where a built binary is available, as in the project's own CI; a simulated worker loop otherwise).
5. Tears the throwaway cluster down again afterwards, whether the tests passed or failed.

Because make test depends on make install, running it is always a complete "build, install, and test" cycle in one command.

How the test suite reports results

Unlike some test frameworks that compare output against a saved expected file, test/validate.sql computes a real assertion for each of its 46 sections directly in SQL, and reports PASS N: ... when a section's assertion holds, or halts immediately with FAIL N: ... the moment one doesn't. This matters here because most of what the framework produces — unique identifiers, timestamps — is different every single run, so there is no fixed "expected output" to diff against in the first place.

One assumption the test suite makes

test/validate.sql assumes three PostgreSQL extensions are already available on the test server: pg_stat_statements, amcheck, and pg_visibility. test/run_tests.sh installs all three automatically before running the tests, and several of the test suite's assertions hardcode result counts that are only correct when all three are present. If you're reading the test file directly, this is worth knowing — it isn't a general requirement of the framework itself, just of the test suite that verifies it.

Continue to Core Concepts.