43 lines
3 KiB
Markdown
43 lines
3 KiB
Markdown
---
|
||
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_<pid>` 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_<n>_<pid>`) 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 <url> -Atc "select datname from pg_database where datname ~ '^(t|tmpl)_'"`.
|