How do I test a feature after implementation?

These three steps are non-negotiable and run in this order, every time — do not skip to step 4 (writing the scenario) on the assumption "the environment is probably fine already". A stale build or a database that predates the change under test invalidates everything that follows.

1. Ask the user whether a new build is necessary before doing anything else. If the change is docs-only, or the user just built and nothing has changed since, skip straight to step 2. Otherwise:

   ./compass.sh build --preset <preset>
   ./compass.sh build rat --preset <preset>
   

   The rat target runs the full test suite; treat any failure as a blocker, not something to defer to review. See How do I run the tests? for per-component targets and logging knobs.

2. Validate SQL schemas — if the feature touched any table, trigger, or function:

   ./projects/ores.sql/utility/validate_schemas.sh
   

   If the feature is a codegen entity, also run:

   ./projects/ores.codegen/validate_docs.sh
   

3. Ready the environment — confirm the database is recent (recreate only if it's not) and the Acme Corporation tenant is provisioned, per How do I ready up an environment? steps 1-5. Skip that recipe's step 6 (client start) here — step 5 below starts the client itself, with the scenario preloaded, so a separate bare client start would just be extra work to throw away.

   The login credentials for the test scenario's connection step come from the provisioning script that recipe runs — read the provision system=/=login lines in how_do_i_provision_the_system_with_acme_corporation_holding_group.ores rather than hardcoding them into the scenario doc, since they can change independently of this recipe (usernames for generated staff accounts are randomised per run — see How do I provision the system with Acme Corporation (holding group)?).

1. Create a test scenario for the new feature, scaffolded via compass add:

   ./projects/ores.compass/compass.sh add test_scenario \
     --slug verify_<feature> \
     --parent-dir doc/agile/versions/<version>/<sprint>/<story-slug> \
     --title "Test Scenario: Verify <feature>" \
     --description "<one sentence: what this scenario checks>." \
     --story-id <story-uuid> --story-title "<story title>" \
     --parent-id <task-uuid> --parent-title "<task title>"
   

   The #+description: you pass, plus the scenario's opening paragraph, is the reader's overview — before any steps, it must state plainly what feature this scenario verifies and what "pass" means for it. Do not leave this generic; a tester picking up the scenario cold should know from the description alone what they are about to check, without reading every step first.

   Fill in the * Scenario Info table before writing steps:

   • Target dialog — the Qt dialog class(es) under test, and the exact menu path to reach them (e.g. "DayCountFractionTypeDetailDialog — Menu: Reference Data > Trading Conventions > Day Count Fraction Types"). A bare class name forces the tester to hunt through menus to find a screen that may not exist yet in their muscle memory; the menu path is the whole reason this field exists.
   • Clients — genuinely empty (no placeholder text at all, not even "single client") for one client; list every colour/label a multi-client scenario needs (e.g. "blue, red") only when the scenario truly needs several running client instances at once. This field is not just documentation: the QA Validation Runner treats any non-empty value here as "multi-client" and then only looks for steps nested one level deeper, under a per-client ** heading — a stray placeholder (even something as reasonable-looking as "single client") with flat ** steps silently loads zero steps, no error shown. Leave the cell blank unless you are actually writing the nested per-client structure to match.

   Fill in * Steps per Archetype: doc_test_scenario.org.mustache, following two conventions every step must meet:

   • Step titles are short — five to seven words, so the whole title fits on one line in the QA Validation Runner's step list without wrapping or truncating. "Edit and save the record", not "Edit an existing record's fields and save the changes to verify they persist correctly."
   • Step bodies are bullet points, not prose paragraphs — a checklist giving the tester every piece of context needed to execute that one step without looking anything up elsewhere: what UI state must already exist, exactly what to click or type, and exactly what outcome confirms the step passed.

   The first step under every client (not just the first client, if the scenario has more than one) must be its own connect/login step: the exact account and password to log in as (from step 3's provisioning script) and which party/tenant to select — never leave the tester to guess starting state, and never assume a second client instance inherits the first one's session.

   The scenario must cover every aspect of the feature that needs testing, not just the happy path. For an entity/CRUD feature that means, at minimum, one step per item below, in order — do not drop any of them without an explicit reason recorded in the task:

   • Create: add a new record via the list window's Add action; verify it appears in the list and the detail dialog shows the saved values.
   • Read: reopen the detail dialog for the created record; verify all fields round-trip correctly.
   • Update: edit a field and save; verify the list refreshes with the new value and the change reason is recorded.
   • Delete: delete the record; verify it disappears from the list.
   • History: open the History dialog for the record; verify create/update/delete are all present with correct change reasons.
   • Eventing: with a second client instance running (see the Clients field in the scenario's * Scenario Info), perform an operation in the first instance and verify the change lands as a NATS notification and refreshes the second instance's list without a manual reload — this is what actually exercises the LISTEN/NOTIFY-to-NATS relay end to end, not just the repository layer that ctest already covers.

   For a non-CRUD feature (a workflow, a report, a background job), list its own equivalent set of "aspects that need testing" up front — every distinct code path or UI state the implementation introduced — before writing steps, the same way CRUD/eventing/ history above is the fixed checklist for an entity feature.

2. Start the client with the scenario pre-loaded and hand it to the user — do not execute the scenario yourself, since it verifies a Qt UI a human needs to drive. --open-scenario requires an absolute path — a relative one silently fails to load the scenario, so resolve it explicitly rather than typing a doc/agile/...-style relative path by hand:

   ./projects/ores.compass/compass.sh client start --colour <colour> \
     --open-scenario "$(realpath doc/agile/versions/<version>/<sprint>/<story-slug>/verify_<feature>.org)"
   

   Tell the user the scenario is loaded in Scenario Runner (System > Testing) and ask them to execute it, ticking each step as they go — see Devops Run Client for the --open-scenario mechanics and why it must be an absolute path.