Add test/install foundation for update+upgrade testing (fresh/update/existing)

[jnasbyupgrade]

Rebase note

Rebased onto add-test-build (this stack is now sync-pgxntool-2.3.0 -> add-test-build -> this PR -> #23; coordinator is handling gh stack link separately). add-test-build (#26) deleted test/sql/install.sql and trimmed the leading dependency-check block from test/sql/pgtap.sql (moved to test/build/install.sql); this PR's own mode-gating touched both of those same files, so real conflicts had to be resolved with judgment rather than a mechanical merge:

• test/sql/install.sql no longer exists after Add test/build: extension-metadata tests + raw SQL syntax checks #26, so this PR's mode-gating commit for that file is now a no-op -- dropped rather than resurrecting the file. The alternate expected file test/expected/install_1.out is correspondingly removed too (nothing left for it to be an alternate of).
• test/sql/pgtap.sql: kept Add test/build: extension-metadata tests + raw SQL syntax checks #26's trim (no dependency-check block, no SET search_path = tap) and re-derived the \if :is_existing gating around it -- the \else (fresh/update) branch is Add test/build: extension-metadata tests + raw SQL syntax checks #26's already-trimmed content; the existing-mode branch is unchanged (it never had the dependency-check block to begin with).
• test/CLAUDE.md updated to stop referencing the now-deleted test/sql/install.sql and the now-three-file-turned-two-file alternate-expected-output list.

A real, pre-existing bug found and fixed during this rebase's own local verification (not introduced by the rebase itself -- present in this PR's original design regardless): TEST_LOAD_SOURCE=update crashed in test/sql/pgtap.sql. test/install/load.sql's update mode installs test_factory only, never test_factory_pgtap; pgtap.sql's non-existing-mode branch calls test/helpers/create_extension.sql for test_factory (a no-op since it's already installed) and then unconditionally DROP TABLEs pre_install_role/post_install_role -- which that no-op never created. Guarded the same way test/helpers/create.sql already guards its own read of those tables (to_regclass(...) IS NOT NULL), rather than inventing a new pattern. This wasn't caught before because no CI job drives update mode yet (per this PR's own "what's skipped" section below) -- found by testing it locally anyway while verifying the rebase.

Re-verified all three modes locally after resolving conflicts: fresh (default), update (now doesn't crash), and existing against a real pre-populated database (tap schema + pgtap installed first, then test_factory_pgtap CASCADE) -- zero raw not ok TAP lines in the fresh and existing legs, output byte-identical to the pre-recorded _1.out alternates.

---

Summary

First of a small stack implementing the advanced update+upgrade (U&U)
testing pattern for this repo, modeled on Postgres-Extensions/cat_tools
PR #16 and what has landed on its master since (PR #44 test-harness
overhaul, PR #46 update-path convergence, PR #48 PG-major single source of
truth). This PR is the foundation piece: the test/install/load.sql
load-mode switch, the dependency guard, and single-sourcing the test role
name. A follow-up PR will restructure CI on top of this (docs-only gate,
PG-major single source of truth, all-checks-passed, the push/
pull_request double-trigger fix, and a binary pg_upgrade job).

Now stacked on add-test-build (#26) -> sync-pgxntool-2.3.0, in turn built on current master (pgxntool 2.3.0, which is what provides PGXNTOOL_ENABLE_TEST_INSTALL/test/install/ in the first place).

What this adds

• TEST_LOAD_SOURCE=fresh|update|existing (Makefile), propagated as
  test_factory.test_load_mode/test_update_from/test_update_to GUCs,
  validated at both make-parse-time ($(error ...)) and read time (no
  missing_ok, reject unknown values).
• test/install/load.sql: pgxntool's PGXNTOOL_ENABLE_TEST_INSTALL
  feature runs this once, committed, before the regular test files, so its
  state survives into every one of them. fresh (default) leaves
  test/sql/*.sql to install the extension themselves exactly as before;
  update does CREATE EXTENSION VERSION :from + ALTER EXTENSION UPDATE;
  existing only asserts the extensions are present at the current
  version and never drops/creates.
• test/helpers/create_extension.sql now skips CREATE EXTENSION when
  load.sql already installed it (update/existing), while fresh mode keeps
  its original behavior unchanged (no IF NOT EXISTS, so a stale/unexpected
  install still errors loudly instead of silently testing wrong state).
• Dependency guard (existing mode only): a view depending on
  tf.tap(text,text) blocks a stray non-CASCADE DROP EXTENSION test_factory_pgtap. test_factory itself doesn't need an artificial
  guard -- test_factory_pgtap's own control file (requires = 'pgtap, test_factory') already blocks a non-CASCADE DROP EXTENSION test_factory
  as long as test_factory_pgtap is installed, and load.sql proves that
  natural protection still holds too. This matters because the
  install-ordering half of pgtap.sql is exactly the kind of thing the
  guard exists to catch if it ran under existing mode -- so it's skipped
  under test_load_mode=existing instead. (Packaging/dependency-declaration
  checks that used to additionally live in test/sql/install.sql were
  moved to test/build/install.sql by Add test/build: extension-metadata tests + raw SQL syntax checks #26, stacked below this PR.)
• test/roles.sql: single source of truth for the test_role name,
  \i'd via test/helpers/deps.sql (test files) and load.sql (which now
  owns creating the role idempotently, once, instead of each test file
  doing its own unguarded CREATE ROLE).
• Alternate expected output
  (test/expected/{base,pgtap}_1.out) for the existing-mode leg,
  which legitimately produces different-but-correct output (skipped
  sections, a skipped role-restore check) -- pg_regress's native numbered
  alternate-file convention, generated from real existing-mode runs.

Verification

Ran on both PG12 and PG17:

• make test (fresh, default) -- unchanged, byte-identical expected output.
• make test TEST_LOAD_SOURCE=update -- doesn't error (currently a no-op;
  see below).
• make test TEST_LOAD_SOURCE=existing CONTRIB_TESTDB=<db> EXTRA_REGRESS_OPTS=--use-existing PGXNTOOL_ENABLE_TEST_BUILD=no against a
  real pre-populated database (extension installed, tap schema set up
  first) -- passes cleanly with zero raw not ok TAP lines in either leg.
• make check-stale-expected -- clean (it already recognizes pg_regress's
  _N.out alternate-file convention).

What's skipped, and why (per the doc's "ultimate goal" -- this record is

meant to help decide what's generic enough for pgxntool itself)

• No CI job drives TEST_LOAD_SOURCE=update yet. test_factory has only
  ever shipped one version (0.5.0), so there's no historical update script
  to exercise -- CREATE EXTENSION VERSION '0.5.0' + ALTER EXTENSION UPDATE is a no-op today and wouldn't prove anything fresh-mode CI
  doesn't already cover. The mechanism is built now (per the doc's
  checklist items 3-5) so it's ready the moment a second version ships.
• TEST_SCHEMA (doc §3a) is not implemented. test_factory is
  non-relocatable with hardcoded internal schema names (tf, _tf,
  _test_factory_test_data -- see sql/test_factory.sql), not
  search_path-relative. The ambient-search_path failure mode TEST_SCHEMA
  exists to catch (code accidentally assuming public) structurally cannot
  occur here. This is a genuine divergence, not an oversight.
• The bridge-update/multi-origin machinery from PR Add CI-monitoring instruction to CLAUDE.md #16 is not ported.
  That's cat_tools-specific technical debt (recovering from old
  pg_upgrade-unsafe releases cut before this testing existed); nothing
  test_factory has shipped needs it.
• pg-upgrade-stepwise (every-major climb) and pg_tle testing are left
  for a possible follow-up, not this PR -- no evidence test_factory
  targets pg_tle/RDS deployment, and test_factory has no catalog-touching
  views (checked sql/test_factory--0.5.0.sql) so the per-major-boundary
  risk pg-upgrade-stepwise protects against is low.
• A found-and-worth-flagging pgxntool gotcha (not fixed here, out of
  scope for an extension-level PR): test/install/*.sql's actual output and
  its "expected" comparison target resolve to the same physical path
  (test/install/<name>.out, since --inputdir's expected/../install/
  and --outputdir's results/../install/ both collapse to install/).
  In practice this means pg_regress can never detect a real regression in a
  test/install/*.sql file via output diffing -- it always overwrites and
  "passes". Worth a hard failure via RAISE EXCEPTION-style assertions
  instead of relying on diffed output for anything that must actually catch
  a regression (what load.sql does throughout this PR).

Convergence with cat_tools PR #16

• Independently converged on the same techniques: the load-mode GUC-
  propagation mechanism (TEST_LOAD_SOURCE -> GUC -> current_setting(),
  no missing_ok), the dependency-guard technique (plant a stable-member
  view, prove drop is blocked, re-prove after every step), and "factor the
  install->guard->assert flow into the install script itself" instead of
  inline duplication.
• Adapted rather than copied verbatim: cat_tools's guard targets an enum
  type grown via ADD VALUE; test_factory has no enum, so it targets
  tf.tap(text,text) instead (and gets test_factory's own protection for
  free via test_factory_pgtap's requires clause -- cat_tools has no
  equivalent second extension, so it needed an explicit guard for
  everything).

---

Recreated from #22 (fork-headed) as an upstream-branch PR so it can be part of a formal GitHub stack (gh stack link), which refuses fork PRs. Same content/commits, same CI results.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: cf8305e4-b076-48f8-9f4b-29a909057839

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}