1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
|
# pgagroal Test Suite Instructions
## Overview
This document explains how to run the pgagroal test suite, generate code coverage, and use containerized testing. All testing is now performed using the `check.sh` script with containerized PostgreSQL (recommended and default for all development and CI).
### Running Specific Test Cases or Suites
You can run a specific test case or suite using the following environment variables:
- `CK_RUN_CASE=<test_case_name> ./check.sh` — runs a single test case
- `CK_RUN_SUITE=<test_suite_name> ./check.sh` — runs a single test suite
Alternatively, you can export the environment variable before running the script:
```sh
export CK_RUN_CASE=<test_case_name>
./check.sh
```
The environment variables will be automatically unset when the test is finished or aborted.
## Quick Start (Containerized - Recommended)
## Containerized Testing (`check.sh`) (Recommended)
The `check.sh` script is the main and recommended way to run the pgagroal test suite. It works on any system with Docker or Podman (Linux, macOS, FreeBSD, Windows/WSL2). It automatically builds a PostgreSQL 17 container, sets up the test environment, runs all tests, and generates coverage reports and logs. No local PostgreSQL installation is required.
### Key Features
- **No local PostgreSQL required**: Uses Docker/Podman containers
- **Consistent environment**: Same PostgreSQL version (17) across all systems
- **Automatic cleanup**: Containers are removed after tests
- **Integrated coverage**: Coverage reports generated automatically
- **Isolated testing**: No interference with local PostgreSQL installations
- **Multiple configurations**: Supports running tests on multiple pgagroal configurations
- **Easy setup**: `./check.sh setup` installs all dependencies and builds the PostgreSQL image
- **Flexible CI support**: Used in CI for Linux, and will be used for all platforms after migration
### Usage
```sh
./check.sh [sub-command]
```
**Subcommands:**
- `setup` Install dependencies and build PostgreSQL image (one-time setup)
- `clean` Clean up test suite environment and remove PostgreSQL image
- `run-configs` Run the testsuite on multiple pgagroal configurations (containerized)
- `ci` Run in CI mode (local PostgreSQL, no container)
- `run-configs-ci` Run multiple configuration tests using local PostgreSQL (like ci + run-configs)
- `ci-nonbuild` Run in CI mode (local PostgreSQL, skip build step)
- `run-configs-ci-nonbuild` Run multiple configuration tests using local PostgreSQL, skip build step
- (no sub-command) Default: run all tests in containerized mode
> **For local development, use only the `run-configs` and default (no sub-command) modes. Other modes (`ci`, `run-configs-ci`, etc.) are intended for CI and may interfere with your local PostgreSQL setup if used locally.**
### Artifacts and Logs
After running containerized tests, you will find:
- Test logs: `/tmp/pgagroal-test/log/`
- PostgreSQL logs: `/tmp/pgagroal-test/pg_log/`
- Coverage reports: `/tmp/pgagroal-test/coverage/`
### Adding New Test Cases
- Add new `.c` and `.h` files in `test/testcases/`.
- Register your test suite in `test/testcases/runner.c`.
- Add your test source to `test/CMakeLists.txt`:
```cmake
set(SOURCES
testcases/common.c
testcases/your_new_test.c
testcases/runner.c
)
```
### Prerequisites
- **Docker or Podman** installed and running
- The `check` library installed for C unit tests
- **LLVM/clang** and **llvm-cov**/**llvm-profdata** installed (for coverage reports)
> **Note:** The `check.sh` script always builds the project with Clang in Debug mode for coverage and testability.
### Notes
- The containerized approach automatically handles cleanup on exit.
- Use `./check.sh clean` to manually remove containers and test data.
- PostgreSQL container logs are available with debug5 level for troubleshooting.
- The script automatically detects and uses either Docker or Podman.
- It is recommended to **ALWAYS** run tests before raising a PR.
- Coverage reports are generated using LLVM tooling (clang, llvm-cov, llvm-profdata).
- For local development, use only the `run-configs` and default (no sub-command) modes. Other modes (`ci`, `run-configs-ci`, etc.) are intended for CI and may interfere with your local PostgreSQL setup if used locally.
|
