testing the test database

README.md

@@ -228,4 +228,43 @@ Your tests run against this clean, isolated "flyer-crawler-test" database.
 Teardown (sql/test_teardown.sql):
 
 After tests complete (whether they pass or fail), the if: always() step in your workflow ensures that sql/test_teardown.sql is executed.
-This script terminates any lingering connections to the test database, drops the "flyer-crawler-test" database completely, and drops the test_runner role.
+This script terminates any lingering connections to the test database, drops the "flyer-crawler-test" database completely, and drops the test_runner role.
+
+Part 3: Test Database Setup (for CI/CD and Local Testing)
+Your Gitea workflow and local test runner rely on a permanent test database. This database needs to be created once on your server. The test runner will automatically reset the schema inside it before every test run.
+
+Step 1: Create the Test Database
+On your server, switch to the postgres system user to get superuser access.
+
+bash
+sudo -u postgres psql
+Inside the psql shell, create a new database. We will assign ownership to the same flyer_crawler_user that your application uses. This user needs to be the owner to have permission to drop and recreate the schema during testing.
+
+sql
+-- Create the test database and assign ownership to your existing application user
+CREATE DATABASE "flyer-crawler-test" WITH OWNER = flyer_crawler_user;
+
+-- Exit the psql shell
+\q
+
+Step 2: Configure Gitea Secrets for Testing
+Your CI pipeline needs to know how to connect to this test database. Ensure the following secrets are set in your Gitea repository settings:
+
+DB_HOST: The hostname of your database server (e.g., localhost).
+DB_PORT: The port for your database (e.g., 5432).
+DB_USER: The user for the database (e.g., flyer_crawler_user).
+DB_PASSWORD: The password for the database user.
+The workflow file (.gitea/workflows/deploy.yml) is configured to use these secrets and will automatically connect to the "flyer-crawler-test" database when it runs the npm test command.
+
+How the Test Workflow Works
+The CI pipeline no longer uses sudo or creates/destroys the database on each run. Instead, the process is now:
+
+Setup: The vitest global setup script (src/tests/setup/global-setup.ts) connects to the permanent "flyer-crawler-test" database.
+
+Schema Reset: It executes sql/drop_tables.sql (which runs DROP SCHEMA public CASCADE) to completely wipe all tables, functions, and triggers.
+
+Schema Application: It then immediately executes sql/master_schema_rollup.sql to build a fresh, clean schema and seed initial data.
+
+Test Execution: Your tests run against this clean, isolated schema.
+
+This approach is faster, more reliable, and removes the need for sudo access within the CI pipeline.