Run the database tests

SOP SYS-04 · Technical systems manual

1 Purpose

Prove that every rule the database enforces still works, by running the test suite that tries to break each one.

2 Applies to

The person responsible for the shop’s database: after any change to the files in sql/, before a change is merged, and whenever a rule seems not to be working.

3 Before you begin

The shop’s app is running. See SYS-03 Start, stop and check the shop’s app.

4 What the tests are

The database refuses anything that breaks a shop rule, such as grooming a dog whose rabies has run out. A rule that works leaves nothing to look at, so the only way to know it still works is to try to break it and confirm the database said no.

The tests live in the tests/ folder, one file per family of rules. They are written with pgTAP, a testing tool for Postgres databases, and run by pg_prove. Each test runs on its own test database (grooming_test), filled with made-up dogs from sql/seed/fixture.sql. The tests never touch the shop’s database or any real paperwork.

The README’s Testing section lists what each test file proves.

5 Procedure

5.1 Set up the test database (first time only)

Open the Technical workbench at http://localhost:8501.
In the left menu, click Run & test.
Click the Database tab.
Click Set up the database. If the button cannot be clicked, the test database is already set up: go to step 5.

The output appears below the button. It finishes with the fixture loaded.

5.2 Run the tests

Click the Checks tab.
Click Database test suite (pg_prove). The output appears below as each test file runs.
Read the last lines. A passing run ends with Result: PASS, after the number of files and tests.

5.3 Run them from a terminal instead

The same tests, without the Technical workbench. In a terminal in the dog-groomer-platform folder:

docker compose exec db pg_prove -U postgres -d grooming_test tests/*.sql

5.4 Run the other two checks

The shop screens’ connection to the database has its own tests, and so does the AI’s scoring. Run both after changing them:

Harness self-check: on the Checks tab, click Harness self-check. It ends with every check passing. It needs no API key and sends nothing to the AI.
The shop screens’ tests: in a terminal in the dog-groomer-platform folder:
```
docker compose exec -w /repo/api api python -m pytest -q
```
It ends with the number of tests passed and none failed.

6 Result

The test run ends with Result: PASS. Every rule is proven to refuse what it should and to allow what it should.

7 If something goes wrong

7.1 Result: FAIL

At least one rule did not behave as its test expects. Scroll up to the lines that start with not ok: each names the test file and the test that failed. Do not merge the change that caused it. The test file’s number matches the rule family in the README’s Testing section.

7.2 Parse errors: Bad plan. You planned … tests but ran 0.

The test database holds an older copy of the rules than the tests expect: usually the newest test files show Tests: 0. This happens after pulling changes to sql/. Reset the test database (see SYS-07 Reset the test or demo database) and run the tests again.

Resetting deletes the test database’s made-up dogs and any AI runs loaded into it with the Technical workbench. The runs themselves stay on disk: load them again on the Run & test screen, Scoring tab, with Load into the database. The shop’s database is not touched.