From a90eef1cb2c0037b038e05e1ee5bed63e04ac5bf Mon Sep 17 00:00:00 2001
From: "jabber.developer2" <jabber.developer2@jabber.space>
Date: Wed, 7 Jan 2026 13:41:24 +0300
Subject: [PATCH] docs: update CONTRIBUTING.md to clarify functional test
 guidelines

---
 CONTRIBUTING.md | 43 ++++++++++++++++++++-----------------------
 1 file changed, 20 insertions(+), 23 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1c66e27f..228cfb4d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -138,37 +138,34 @@ You can run the `make spell` command for this.
 `make doublecheck` will run the code formatter, spell checker and unit tests.
 
 
-### Functional tests: moving away from brittle ID hooks
+### Functional tests
 
-Historically the functional test suite relied on stabber's id based helpers like `stbbr_for_id("prof_presence_1", ...)` to register canned responses that would be sent once Profanity emitted a stanza carrying that exact `id` attribute. This made the tests fragile:
+The functional test suite uses [stabber](https://git.jabber.space/devs/stabber) as a mock XMPP server. Tests are located in `tests/functionaltests/`.
 
-* Changes to stanza id generation (sequence, format) broke tests unexpectedly.
-* Reordering internal requests produced hard-to-debug race conditions when an `id` no longer matched.
-* Parallel additions of new features could shift which stanzas received a given id causing unrelated test failures.
+#### Running functional tests
 
-We have migrated to content based stubbing using direct sends (`stbbr_send`) and query hooks (`stbbr_for_query`). Instead of tying a response to a predicted id we now send the required server stanzas explicitly after initiating actions. Example (see `tests/functionaltests/proftest.c`):
+Functional tests require stabber to be installed. Once installed, tests run as part of `make check`:
 
-```c
-// Old brittle approach
-stbbr_for_id("prof_presence_1", "<presence id='prof_presence_1' ...>");
-
-// New approach: after authentication, send presence directly
-stbbr_send("<presence from='stabber@localhost/profanity' to='stabber@localhost/profanity'>...caps...</presence>");
+```bash
+make check
 ```
 
-Benefits:
+#### Writing functional tests
 
-* Eliminates dependency on internal id sequencing.
-* Clearer intent inside test code ("send presence now" vs "register hook and hope client triggers it").
-* Simplifies adding new tests—no need to inspect logs for generated ids.
+Use content-based stubbing with stabber:
 
-Guidelines when writing new functional tests:
+```c
+// Use stbbr_for_query for IQ queries (roster, disco, etc.)
+stbbr_for_query("jabber:iq:roster", "<iq type='result'>...</iq>");
 
-1. Prefer `stbbr_for_query(namespace, xml)` for IQ roster or disco queries where the namespace is stable.
-2. Use `stbbr_send(xml)` for presence, message, and other push style stanzas.
-3. Avoid `stbbr_for_id` unless the protocol flow genuinely requires correlating a specific request/response pair not covered by a namespace query.
-4. Keep assertions tolerant of ordering when possible; rely on `prof_output_regex()` matches rather than hard-coded positions.
-5. If timing flakiness appears, temporarily raise `prof_timeout()` around the critical expectation and reset it immediately afterwards.
+// Use stbbr_send for presence, message, and push-style stanzas
+stbbr_send("<presence from='buddy@localhost'>...</presence>");
+```
 
-The migration from `stbbr_for_id` is complete. All functional tests now use content-based stubbing. When adding new tests, follow the guidelines above.
+Guidelines:
+
+1. Use `stbbr_for_query(namespace, xml)` for IQ queries where the namespace is stable.
+2. Use `stbbr_send(xml)` for presence, message, and other push-style stanzas.
+3. Keep assertions tolerant of ordering when possible; use `prof_output_regex()` for flexible matching.
+4. If timing issues appear, use `prof_timeout()` around critical expectations and reset afterwards.