Skip to content

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 — 23 sections that exercise essentially every feature this site documents: the full catalog and suite lifecycle, thresholds, debounce (see How Threshold Evaluation Works), inactivating namespaces and checks, resetting to defaults, retention, the access-control rules, and the reporting functions.
  4. 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 23 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.