chores(x2a): run local tests against PostgreSQL (#2656)

Signed-off-by: Marek Libra <marek.libra@gmail.com>

Author: mareklibra

workspaces/x2a/README.md

@@ -282,9 +282,39 @@ The plugin's `KubeService` provides methods to interact with Kubernetes resource
 Loaded Kubernetes configuration from ~/.kube/config
 ```
 
+## Running Tests with PostgreSQL
+
+By default, `yarn test` runs database tests against SQLite only. The backend
+tests are written to also exercise PostgreSQL (via `TestDatabases` from
+`@backstage/backend-test-utils`), but PostgreSQL is skipped locally because the
+Backstage test tooling disables Docker when the `CI` environment variable is not
+set.
+
+### Quick start — testcontainers (Docker/Podman)
+
+Run tests against both SQLite and PostgreSQL with a single command:
+
+```sh
+yarn test:pg          # unit tests (SQLite + PostgreSQL)
+yarn test:all:pg      # full suite including lint, prettier, coverage
+```
+
+These scripts set `CI=true` so that `testcontainers` automatically pulls and
+starts a `postgres:18` container. **Docker or Podman must be running.**
+
+On Fedora/RHEL with Podman, enable the Docker-compatible socket first:
+
+```sh
+systemctl --user enable --now podman.socket
+export DOCKER_HOST=unix:///run/user/$(id -u)/podman/podman.sock
+```
+
+The first run downloads the `postgres:18` image.
+
 ## Additional Commands
 
-- `yarn test` - Run tests
+- `yarn test` - Run tests (SQLite only)
+- `yarn test:pg` - Run tests (SQLite + PostgreSQL via testcontainers)
 - `yarn lint` - Run linter
 - `yarn prettier:fix` - Fix code formatting
 - `yarn build:all` - Build all packages

workspaces/x2a/package.json

@@ -19,14 +19,16 @@
     "tsc:full": "tsc --skipLibCheck true --incremental false",
     "clean": "backstage-cli repo clean",
     "test": "backstage-cli repo test",
+    "test:pg": "CI=true backstage-cli repo test",
     "test:all": "yarn openapi-generate && yarn prettier:check && yarn lint:all && backstage-cli repo test --coverage",
+    "test:all:pg": "yarn openapi-generate && yarn prettier:check && yarn lint:all && CI=true backstage-cli repo test --coverage",
     "test:e2e": "echo Skipping until we have tests: playwright test",
     "fix": "backstage-cli repo fix",
     "lint": "backstage-cli repo lint --since origin/main",
     "lint:all": "backstage-cli repo lint",
     "prettier:check": "prettier --check .",
     "prettier:fix": "prettier --write .",
-    "chores": "yarn prettier:fix && yarn lint:all --fix && yarn tsc:full && yarn build:api-reports && yarn test:all",
+    "chores": "yarn prettier:fix && yarn lint:all --fix && yarn tsc:full && yarn build:api-reports && yarn test:all:pg",
     "new": "backstage-cli new --scope @red-hat-developer-hub",
     "postinstall": "cd ../../ && yarn install"
   },

workspaces/x2a/plugins/x2a-backend/package.json

@@ -29,7 +29,9 @@
     "build": "backstage-cli package build",
     "lint": "backstage-cli package lint",
     "test": "NODE_OPTIONS='--experimental-vm-modules' backstage-cli package test",
+    "test:pg": "NODE_OPTIONS='--experimental-vm-modules' CI=true backstage-cli package test",
     "test:all": "NODE_OPTIONS='--experimental-vm-modules' backstage-cli package test --coverage",
+    "test:all:pg": "NODE_OPTIONS='--experimental-vm-modules' CI=true backstage-cli package test --coverage",
     "clean": "backstage-cli package clean",
     "prepack": "backstage-cli package prepack",
     "postpack": "backstage-cli package postpack",

workspaces/x2a/scripts/start-test-postgres.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Start a disposable PostgreSQL 18 container for local test runs.
+#
+# Usage:
+#   eval "$(./scripts/start-test-postgres.sh)"
+#   yarn test          # now runs against the external PostgreSQL instance
+#
+# The container is removed automatically when stopped:
+#   podman stop x2a-test-postgres   # or: docker stop x2a-test-postgres
+
+set -euo pipefail
+
+CONTAINER_NAME="x2a-test-postgres"
+POSTGRES_PASSWORD="testpassword"
+HOST_PORT="${X2A_TEST_POSTGRES_PORT:-5433}"
+IMAGE="${BACKSTAGE_TEST_DOCKER_REGISTRY:-}postgres:18"
+
+runtime="docker"
+if command -v podman &>/dev/null && ! command -v docker &>/dev/null; then
+  runtime="podman"
+fi
+
+if "$runtime" ps --format '{{.Names}}' 2>/dev/null | grep -qx "$CONTAINER_NAME"; then
+  >&2 echo "Container '$CONTAINER_NAME' is already running on port $HOST_PORT."
+else
+  >&2 echo "Starting PostgreSQL 18 container '$CONTAINER_NAME' on port $HOST_PORT …"
+  "$runtime" run -d --rm \
+    --name "$CONTAINER_NAME" \
+    -e POSTGRES_PASSWORD="$POSTGRES_PASSWORD" \
+    -p "${HOST_PORT}:5432" \
+    "$IMAGE" >/dev/null
+
+  >&2 echo "Waiting for PostgreSQL to accept connections …"
+  for _ in $(seq 1 30); do
+    if "$runtime" exec "$CONTAINER_NAME" pg_isready -U postgres &>/dev/null; then
+      break
+    fi
+    sleep 1
+  done
+fi
+
+echo "export BACKSTAGE_TEST_DATABASE_POSTGRES18_CONNECTION_STRING=\"postgresql://postgres:${POSTGRES_PASSWORD}@localhost:${HOST_PORT}/postgres\""