From c3bf9e88e465af9f29a675ad6e9e7dfcb51a07f6 Mon Sep 17 00:00:00 2001 From: eelke Date: Sun, 18 Oct 2026 12:09:54 +0200 Subject: [PATCH] Add framework for executing tests against multiple postgresql versions using docker compose. --- .junie/skills/pg-integration-tests/SKILL.md | 43 +++++++ AGENTS.md | 1 + tests/CMakeLists.txt | 2 + tests/integration/CMakeLists.txt | 43 +++++++ tests/integration/docker-compose.yml | 16 +++ tests/integration/fixtures/schema.sql | 6 + tests/integration/main.cpp | 10 ++ tests/integration/tst_Smoke.cpp | 63 ++++++++++ tests/pgintegration/CMakeLists.txt | 21 ++++ tests/pgintegration/DbTest.cpp | 55 +++++++++ tests/pgintegration/DbTest.h | 26 ++++ tests/pgintegration/PgTestEnvironment.cpp | 125 ++++++++++++++++++++ tests/pgintegration/PgTestEnvironment.h | 46 +++++++ 13 files changed, 457 insertions(+) create mode 100644 .junie/skills/pg-integration-tests/SKILL.md create mode 100644 tests/integration/CMakeLists.txt create mode 100644 tests/integration/docker-compose.yml create mode 100644 tests/integration/fixtures/schema.sql create mode 100644 tests/integration/main.cpp create mode 100644 tests/integration/tst_Smoke.cpp create mode 100644 tests/pgintegration/CMakeLists.txt create mode 100644 tests/pgintegration/DbTest.cpp create mode 100644 tests/pgintegration/DbTest.h create mode 100644 tests/pgintegration/PgTestEnvironment.cpp create mode 100644 tests/pgintegration/PgTestEnvironment.h diff --git a/.junie/skills/pg-integration-tests/SKILL.md b/.junie/skills/pg-integration-tests/SKILL.md new file mode 100644 index 0000000..9cc3328 --- /dev/null +++ b/.junie/skills/pg-integration-tests/SKILL.md @@ -0,0 +1,43 @@ +--- +name: pg-integration-tests +description: Write and run pgLab tests against a real PostgreSQL server (14–17) using the pgintegration harness (DbTest fixture, template database, REQUIRE_PG_AT_LEAST). Use whenever a test needs a live server, e.g. catalog introspection, generated SQL that must be executed, version-specific behaviour, or when the user mentions integration tests, IntegrationTests, docker-compose Postgres or TEST_DATABASE_URL. +--- + +# Integration tests against real PostgreSQL + +Build/run commands live in `AGENTS.md` (Build and test); don't duplicate them here. + +## When to use +Use for behaviour that depends on a real server: catalog queries, `pg_get_*` output, executing generated SQL, version differences. Pure string/logic tests belong in `PgsqlTests` / `pglabtests` instead. + +## Layout +- `tests/pgintegration/` – static lib: `PgEnv` (global environment, builds template DB `tmpl_` from `fixtures/schema.sql`), `DbTest` fixture, helpers. +- `tests/integration/` – `IntegrationTests` executable, `tst_*.cpp`, `fixtures/schema.sql`, `docker-compose.yml`. +- The binary only reads `TEST_DATABASE_URL`; unset means every `DbTest` skips. + +## Writing a test +```cpp +#include "DbTest.h" +#include "PgTestEnvironment.h" +class MyFeature : public pgtest::DbTest {}; + +TEST_F(MyFeature, Works) +{ + REQUIRE_PG_AT_LEAST(15); // skip on older servers + auto r = conn().query("SELECT 1"); // Pgsql::Connection, throws on SQL error + EXPECT_EQ(r.rows(), 1); +} +``` +- Derive from `pgtest::DbTest`. Each test gets a fresh database (`t__`) cloned from the template and dropped afterwards, so never rely on state from another test and freely modify data/schema. +- `conn()` is the test connection, `dbUrl()` gives a URL for code under test that opens its own connection (close those before the test ends; teardown uses `DROP DATABASE ... WITH (FORCE)`). +- Gate version-specific features with `REQUIRE_PG_AT_LEAST(v)`; use `pgtest::serverVersionNum()` for finer checks. Also test graceful behaviour on PG 14. +- `query()` throws on error; use `EXPECT_THROW` for expected failures. + +## Adding things +- New test file: add it to the `add_executable(IntegrationTests ...)` list in `tests/integration/CMakeLists.txt` (no globbing). +- Shared schema: extend `tests/integration/fixtures/schema.sql` (plain multi-statement SQL, loaded once per process into the template). Keep it small; it must work on all of 14–17. Version-specific schema should be created inside the test. +- Cluster-wide objects (roles, tablespaces) are not isolated by cloning: use unique names (include `pgtest::processId()`) and drop them in `TearDown`. + +## Running and checking +- One version manually: set `TEST_DATABASE_URL` and use `--gtest_filter` (see AGENTS.md); start servers with `docker compose -f tests/integration/docker-compose.yml up -d --wait pg16`, stop with `down -v`. +- After a run no `t_*` or `tmpl_*` databases should remain: `psql -Atc "select datname from pg_database where datname ~ '^(t|tmpl)_'"`. diff --git a/AGENTS.md b/AGENTS.md index b9c08b0..3244f6a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,6 +18,7 @@ cmake --build build ctest --test-dir build --output-on-failure ``` - Run one suite: `./build/tests/pglabtests/pglabtests --gtest_filter='SqlLexer*'` (same for `PgsqlTests`). +- Integration tests against real PostgreSQL 14–17 (`IntegrationTests`, label `integration`): configure with `-DPGLAB_INTEGRATION_TESTS=ON` (needs Docker), then `ctest --test-dir build -L integration -j4`. This starts `tests/integration/docker-compose.yml` (ports 54314–54317), runs the binary once per version and tears it down. Manual run against any server: `TEST_DATABASE_URL=postgresql://postgres:test@localhost:54316/postgres ./build/tests/integration/IntegrationTests --gtest_filter='Smoke*'`. Without the variable the tests skip. Developer-facing only, no reno note. See the `pg-integration-tests` skill. - `-DBUILD_TESTS=OFF` skips tests. `build/` is git-ignored; the first configure builds dependencies and is slow. - Run the app headless with `QT_QPA_PLATFORM=offscreen ./build/pglab/pglab`. It needs a PostgreSQL server for anything useful. diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index a02ee3c..645cac5 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -3,3 +3,5 @@ find_package(GTest CONFIG REQUIRED) add_subdirectory(mygtestutils) add_subdirectory(PgsqlTests) add_subdirectory(pglabtests) +add_subdirectory(pgintegration) +add_subdirectory(integration) diff --git a/tests/integration/CMakeLists.txt b/tests/integration/CMakeLists.txt new file mode 100644 index 0000000..42c908b --- /dev/null +++ b/tests/integration/CMakeLists.txt @@ -0,0 +1,43 @@ +add_executable(IntegrationTests + main.cpp + tst_Smoke.cpp + ) + +target_link_libraries(IntegrationTests PRIVATE + pgintegration + GTest::gtest + Qt6::Core + ) + +target_compile_definitions(IntegrationTests PRIVATE + PGTEST_FIXTURE_DIR="${CMAKE_CURRENT_SOURCE_DIR}/fixtures" + ) + +set_target_properties(IntegrationTests PROPERTIES + CXX_STANDARD 20 + CXX_STANDARD_REQUIRED ON + ) + +option(PGLAB_INTEGRATION_TESTS "Register Docker based PostgreSQL integration tests" OFF) + +if (PGLAB_INTEGRATION_TESTS) + set(PGTEST_COMPOSE_FILE ${CMAKE_CURRENT_SOURCE_DIR}/docker-compose.yml) + + add_test(NAME db_up + COMMAND docker compose -f ${PGTEST_COMPOSE_FILE} up -d --wait) + add_test(NAME db_down + COMMAND docker compose -f ${PGTEST_COMPOSE_FILE} down -v) + set_tests_properties(db_up PROPERTIES FIXTURES_SETUP pgcluster LABELS integration) + set_tests_properties(db_down PROPERTIES FIXTURES_CLEANUP pgcluster LABELS integration) + + foreach (v 14 15 16 17) + add_test(NAME integration_pg${v} COMMAND IntegrationTests) + set_tests_properties(integration_pg${v} PROPERTIES + FIXTURES_REQUIRED pgcluster + LABELS integration + ENVIRONMENT "TEST_DATABASE_URL=postgresql://postgres:test@localhost:543${v}/postgres") + endforeach () +else () + add_test(NAME IntegrationTests COMMAND IntegrationTests) + set_tests_properties(IntegrationTests PROPERTIES LABELS integration) +endif () diff --git a/tests/integration/docker-compose.yml b/tests/integration/docker-compose.yml new file mode 100644 index 0000000..e90e8dc --- /dev/null +++ b/tests/integration/docker-compose.yml @@ -0,0 +1,16 @@ +x-pg: &pg + environment: { POSTGRES_PASSWORD: test } + tmpfs: [/var/lib/postgresql/data] + command: > + postgres -c fsync=off -c synchronous_commit=off + -c full_page_writes=off -c max_connections=200 + healthcheck: + test: ["CMD-SHELL", "pg_isready -U postgres"] + interval: 1s + retries: 30 + +services: + pg14: { <<: *pg, image: "postgres:14", ports: ["54314:5432"] } + pg15: { <<: *pg, image: "postgres:15", ports: ["54315:5432"] } + pg16: { <<: *pg, image: "postgres:16", ports: ["54316:5432"] } + pg17: { <<: *pg, image: "postgres:17", ports: ["54317:5432"] } diff --git a/tests/integration/fixtures/schema.sql b/tests/integration/fixtures/schema.sql new file mode 100644 index 0000000..ee8554f --- /dev/null +++ b/tests/integration/fixtures/schema.sql @@ -0,0 +1,6 @@ +CREATE TABLE fixture_item ( + id integer PRIMARY KEY, + name text NOT NULL +); + +INSERT INTO fixture_item (id, name) VALUES (1, 'one'), (2, 'two'); diff --git a/tests/integration/main.cpp b/tests/integration/main.cpp new file mode 100644 index 0000000..60bed8d --- /dev/null +++ b/tests/integration/main.cpp @@ -0,0 +1,10 @@ +#include + +#include "PgTestEnvironment.h" + +int main(int argc, char *argv[]) +{ + ::testing::InitGoogleTest(&argc, argv); + ::testing::AddGlobalTestEnvironment(new pgtest::PgEnv(PGTEST_FIXTURE_DIR)); + return RUN_ALL_TESTS(); +} diff --git a/tests/integration/tst_Smoke.cpp b/tests/integration/tst_Smoke.cpp new file mode 100644 index 0000000..900a278 --- /dev/null +++ b/tests/integration/tst_Smoke.cpp @@ -0,0 +1,63 @@ +#include "DbTest.h" +#include "PgTestEnvironment.h" +#include "Pgsql_Result.h" + +using namespace pgtest; + +namespace { + +int scalarInt(Pgsql::Connection &c, const char *sql) +{ + Pgsql::Result r = c.query(sql); + EXPECT_EQ(r.rows(), 1); + return QString::fromUtf8(r.val(0, 0)).toInt(); +} + +} // namespace + +class Smoke : public DbTest {}; + +TEST_F(Smoke, SelectOne) +{ + EXPECT_EQ(scalarInt(conn(), "SELECT 1"), 1); +} + +TEST_F(Smoke, RunsOnClonedDatabase) +{ + Pgsql::Result r = conn().query("SELECT current_database()"); + ASSERT_EQ(r.rows(), 1); + EXPECT_EQ(QString::fromUtf8(r.val(0, 0)), dbName()); + EXPECT_TRUE(dbName().startsWith("t_")); +} + +TEST_F(Smoke, ServerVersionAtLeast14) +{ + EXPECT_GE(serverVersionNum(), 140000); +} + +TEST_F(Smoke, FixtureSchemaPresent) +{ + EXPECT_EQ(scalarInt(conn(), "SELECT count(*) FROM fixture_item"), 2); +} + +// The two tests below each modify the database and expect the pristine +// fixture state, in whichever order they run. +TEST_F(Smoke, IsolationA) +{ + EXPECT_EQ(scalarInt(conn(), "SELECT count(*) FROM fixture_item"), 2); + conn().query("INSERT INTO fixture_item VALUES (100, 'a')"); + EXPECT_EQ(scalarInt(conn(), "SELECT count(*) FROM fixture_item"), 3); +} + +TEST_F(Smoke, IsolationB) +{ + EXPECT_EQ(scalarInt(conn(), "SELECT count(*) FROM fixture_item"), 2); + conn().query("DELETE FROM fixture_item"); + EXPECT_EQ(scalarInt(conn(), "SELECT count(*) FROM fixture_item"), 0); +} + +TEST_F(Smoke, VersionGate) +{ + REQUIRE_PG_AT_LEAST(15); + EXPECT_GE(serverVersionNum(), 150000); +} diff --git a/tests/pgintegration/CMakeLists.txt b/tests/pgintegration/CMakeLists.txt new file mode 100644 index 0000000..96f623a --- /dev/null +++ b/tests/pgintegration/CMakeLists.txt @@ -0,0 +1,21 @@ +add_library(pgintegration STATIC + PgTestEnvironment.h + PgTestEnvironment.cpp + DbTest.h + DbTest.cpp + ) + +target_link_libraries(pgintegration PUBLIC + pgsql + GTest::gtest + Qt6::Core + ) + +target_include_directories(pgintegration PUBLIC + ${CMAKE_CURRENT_SOURCE_DIR} + ) + +set_target_properties(pgintegration PROPERTIES + CXX_STANDARD 20 + CXX_STANDARD_REQUIRED ON + ) diff --git a/tests/pgintegration/DbTest.cpp b/tests/pgintegration/DbTest.cpp new file mode 100644 index 0000000..5e80dc4 --- /dev/null +++ b/tests/pgintegration/DbTest.cpp @@ -0,0 +1,55 @@ +#include "DbTest.h" +#include "PgTestEnvironment.h" + +#include +#include + +namespace pgtest { + +namespace { +std::atomic g_counter{0}; +} + +QString DbTest::dbUrl() const +{ + return urlForDb(dbName_); +} + +void DbTest::SetUp() +{ + if (!available()) + GTEST_SKIP() << "TEST_DATABASE_URL not set or template database unavailable"; + + dbName_ = QString("t_%1_%2").arg(g_counter++).arg(processId()); + try { + { + Pgsql::Connection admin; + admin.connect(*baseUrl()); + admin.query(QString("CREATE DATABASE %1 TEMPLATE %2") + .arg(quoteIdent(dbName_), quoteIdent(templateDbName()))); + } + conn_ = std::make_unique(); + conn_->connect(dbUrl()); + } + catch (const std::exception &e) { + FAIL() << "Creating test database failed: " << e.what(); + } +} + +void DbTest::TearDown() +{ + conn_.reset(); + if (dbName_.isEmpty()) + return; + try { + Pgsql::Connection admin; + admin.connect(*baseUrl()); + admin.query(QString("DROP DATABASE IF EXISTS %1 WITH (FORCE)").arg(quoteIdent(dbName_))); + } + catch (const std::exception &e) { + ADD_FAILURE() << "Dropping test database failed: " << e.what(); + } + dbName_.clear(); +} + +} // namespace pgtest diff --git a/tests/pgintegration/DbTest.h b/tests/pgintegration/DbTest.h new file mode 100644 index 0000000..26fc457 --- /dev/null +++ b/tests/pgintegration/DbTest.h @@ -0,0 +1,26 @@ +#pragma once + +#include +#include +#include + +#include "Pgsql_Connection.h" + +namespace pgtest { + +/// Fixture giving every test its own database cloned from the template. +class DbTest : public ::testing::Test { +protected: + void SetUp() override; + void TearDown() override; + + Pgsql::Connection& conn() { return *conn_; } + QString dbName() const { return dbName_; } + QString dbUrl() const; + +private: + QString dbName_; + std::unique_ptr conn_; +}; + +} // namespace pgtest diff --git a/tests/pgintegration/PgTestEnvironment.cpp b/tests/pgintegration/PgTestEnvironment.cpp new file mode 100644 index 0000000..9a82dd2 --- /dev/null +++ b/tests/pgintegration/PgTestEnvironment.cpp @@ -0,0 +1,125 @@ +#include "PgTestEnvironment.h" + +#include +#include +#include +#include +#include + +#include "Pgsql_Connection.h" +#include "Pgsql_Result.h" + +namespace pgtest { + +namespace { + +bool g_available = false; +int g_versionNum = 0; + +} // namespace + +std::optional baseUrl() +{ + QByteArray v = qgetenv("TEST_DATABASE_URL"); + if (v.isEmpty()) + return std::nullopt; + return QString::fromUtf8(v); +} + +QString urlForDb(const QString &db) +{ + auto base = baseUrl(); + if (!base) + throw std::runtime_error("TEST_DATABASE_URL is not set"); + QUrl url(*base); + url.setPath("/" + db); + return url.toString(); +} + +bool available() +{ + return g_available; +} + +int serverVersionNum() +{ + return g_versionNum; +} + +qint64 processId() +{ + return QCoreApplication::applicationPid(); +} + +QString templateDbName() +{ + return QString("tmpl_%1").arg(processId()); +} + +QString quoteIdent(const QString &name) +{ + QString r = name; + r.replace('"', "\"\""); + return "\"" + r + "\""; +} + +void PgEnv::SetUp() +{ + auto base = baseUrl(); + if (!base) { + std::cerr << "TEST_DATABASE_URL not set, integration tests will be skipped\n"; + return; + } + + const QString tmpl = templateDbName(); + try { + { + Pgsql::Connection admin; + admin.connect(*base); + Pgsql::Result r = admin.query("SHOW server_version_num"); + if (!r || r.rows() != 1) + throw std::runtime_error("could not query server_version_num"); + g_versionNum = QString::fromUtf8(r.val(0, 0)).toInt(); + admin.query(QString("DROP DATABASE IF EXISTS %1 WITH (FORCE)").arg(quoteIdent(tmpl))); + admin.query(QString("CREATE DATABASE %1").arg(quoteIdent(tmpl))); + } + { + QFile f(fixtureDir_ + "/schema.sql"); + if (!f.open(QIODevice::ReadOnly)) + throw std::runtime_error("cannot open " + f.fileName().toStdString()); + QByteArray sql = f.readAll(); + + Pgsql::Connection c; + c.connect(urlForDb(tmpl)); + c.query(sql.constData()); + } + g_available = true; + } + catch (const std::exception &e) { + ADD_FAILURE() << "Setting up template database failed: " << e.what(); + try { + Pgsql::Connection admin; + admin.connect(*base); + admin.query(QString("DROP DATABASE IF EXISTS %1 WITH (FORCE)").arg(quoteIdent(tmpl))); + } + catch (const std::exception &) { + } + } +} + +void PgEnv::TearDown() +{ + if (!g_available) + return; + try { + Pgsql::Connection admin; + admin.connect(*baseUrl()); + admin.query(QString("DROP DATABASE IF EXISTS %1 WITH (FORCE)").arg(quoteIdent(templateDbName()))); + } + catch (const std::exception &e) { + ADD_FAILURE() << "Dropping template database failed: " << e.what(); + } + g_available = false; +} + +} // namespace pgtest diff --git a/tests/pgintegration/PgTestEnvironment.h b/tests/pgintegration/PgTestEnvironment.h new file mode 100644 index 0000000..b8782f0 --- /dev/null +++ b/tests/pgintegration/PgTestEnvironment.h @@ -0,0 +1,46 @@ +#pragma once + +#include +#include +#include + +namespace pgtest { + +/// Value of the TEST_DATABASE_URL environment variable, if set and non-empty. +std::optional baseUrl(); + +/// Same as baseUrl() but with the database name replaced. +QString urlForDb(const QString &db); + +/// True when a server is configured and the template database was created. +bool available(); + +/// server_version_num of the server under test (0 when unavailable). +int serverVersionNum(); + +/// Portable process id. +qint64 processId(); + +/// Name of the template database for this process. +QString templateDbName(); + +/// Quotes an identifier for use in SQL. +QString quoteIdent(const QString &name); + +/// Global environment, register it in main(): +/// ::testing::AddGlobalTestEnvironment(new pgtest::PgEnv(PGTEST_FIXTURE_DIR)); +/// Creates a template database from /schema.sql once per process. +class PgEnv : public ::testing::Environment { +public: + explicit PgEnv(QString fixtureDir) : fixtureDir_(std::move(fixtureDir)) {} + void SetUp() override; + void TearDown() override; + +private: + QString fixtureDir_; +}; + +} // namespace pgtest + +#define REQUIRE_PG_AT_LEAST(v) \ + if (pgtest::serverVersionNum() < (v) * 10000) GTEST_SKIP() << "needs PG " #v