Document P0 webhook fix + test seam; ship :54; track EVALUATION.md

docs/guides/testing.md

@@ -37,21 +37,24 @@ purchase returning 500 on `:52`) shipped this way because the new merchant-profi
 resolution path had no passing test. When adding/altering a repo query, add a test
 that actually executes it. See [payments](payments.md).
 
-## Known-failing tests (3 in tests/api.rs)
+## Driving the purchase / settle path — the provider seam
 
-Test-debt from the `:52` payments transition; the backend is sound, these are a
-test-strategy decision, not bugs:
+Integration tests are a separate crate, so `#[cfg(test)]` doesn't reach the lib
+and `payment::build_provider` only ever makes real BTCPay/Zaprite clients. To
+drive the real resolver (`resolve_provider_for_profile_rail` /
+`payment_provider_by_id`) with a `MockPaymentProvider`, set the always-compiled
+`AppState::provider_override` field (`None` in production; honored by
+`provider_from_row`). `install_mock_provider` / `make_test_state_with_mock_provider`
+wire a mock into BOTH that field AND the legacy `state.payment` singleton (the
+back-compat `/v1/{kind}/webhook` route reads the singleton), and seed a real
+`payment_providers` row on the default profile so profile/rail/row resolution
+still runs for real. `MockPaymentProvider::new_unconfirmed()` /
+`new_status_unavailable()` vary the `get_invoice_status` answer to exercise the
+webhook settle-confirmation guard (see [payments](payments.md)).
 
-- `paid_purchase_creates_invoice_via_provider`, `paid_purchase_in_usd_records_listed_currency_and_rate`
-  — fail with a legitimate 400 ("no payment providers connected"); the fixture
-  seeds no provider. Reaching 200 needs the mock wired through
-  `resolve_provider_for_profile_rail` (`build_provider` only makes real clients;
-  `#[cfg(test)]` does not apply to integration tests against the lib).
-- `payment_provider_preference_round_trip` — inserts into the dropped
-  `btcpay_config`/`zaprite_config`; superseded by
-  `merchant_profile_provider_resolution_queries_round_trip` (delete or rewrite).
-
-The other 43 api tests + all other suites pass.
+The 3 `:52`-era known-failing tests are **resolved**: the two `paid_purchase_*`
+greened via the seam, the dead `payment_provider_preference_round_trip` deleted.
+api suite is now **47 pass / 0 fail**; all other suites green.
 
 ## Cross-language wire-format tests