refactor(tests): improve functional test documentation and cleanup

- Add detailed documentation about test isolation in functionaltests.c
- Improve comments in proftest.c: buffer size explanation, stabber sync TODO
- Add reference to stabber issue #1 for stbbr_wait_stopped() API
- Document prof_output_regex() usage rationale in test_muc.c
- Enhance ping_server test comments for clarity
- Update CONTRIBUTING.md: fix function names (prof_output_regex, prof_timeout)
- Remove redundant commented-out test configurations from ci-build.sh
- Remove obsolete stabber recv suppressions from prof.supp (issue fixed)
- Add clear explanation for disabled assertion in test_chat_session.c
- Add comment explaining /connect max args in cmd_defs.c

CONTRIBUTING.md

@@ -167,8 +167,8 @@ Guidelines when writing new functional tests:
 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 `exp_expectl` regex matches rather than hard-coded positions.
+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 `exp_timeout` around the critical expectation and reset it immediately afterwards.
+5. If timing flakiness appears, temporarily raise `prof_timeout()` around the critical expectation and reset it immediately afterwards.
 
 During the migration it's acceptable for a test file to mix old and new styles; opportunistically refactor brittle sections when touching a test for other reasons.
 

ci-build.sh

@@ -61,24 +61,6 @@ case "$ARCH" in
         "--disable-plugins --disable-c-plugins --disable-python-plugins"
         # 5. Default configuration
         ""
-        # --- Additional configurations (uncomment if needed) ---
-        # "--enable-notifications --enable-otr --enable-pgp --enable-omemo
-        # --enable-plugins --enable-c-plugins --enable-python-plugins"
-        # "--enable-notifications --enable-otr"
-        # "--enable-notifications --enable-otr --enable-pgp"
-        # "--enable-notifications --enable-otr --enable-pgp --enable-omemo"
-        # "--enable-notifications --enable-otr --enable-pgp --enable-omemo --enable-omemo-qrcode"
-        # "--enable-notifications --enable-otr --enable-pgp --enable-omemo --enable-omemo-qrcode
-        # --enable-icons-and-clipboard"
-        # "--enable-notifications --enable-otr --enable-pgp --enable-omemo --enable-omemo-qrcode
-        # --enable-icons-and-clipboard --enable-gdk-pixbuf"
-        # "--enable-notifications --enable-otr --enable-pgp --enable-omemo --enable-omemo-qrcode
-        # --enable-icons-and-clipboard --enable-gdk-pixbuf --with-xscreensaver"
-        # "--enable-notifications --enable-otr --enable-pgp --enable-omemo --enable-omemo-qrcode
-        # --enable-icons-and-clipboard --enable-gdk-pixbuf --with-xscreensaver --enable-plugins"
-        # "--enable-notifications --enable-otr --enable-pgp --enable-omemo --enable-omemo-qrcode
-        # --enable-icons-and-clipboard --enable-gdk-pixbuf --with-xscreensaver --enable-plugins
-        # --enable-c-plugins"
         )
         source /etc/profile.d/debuginfod.sh 2>/dev/null || true
         ;;
@@ -100,18 +82,6 @@ case "$ARCH" in
         "--disable-plugins --disable-c-plugins --disable-python-plugins"
         # 5. Default configuration
         ""
-        # --- Additional configurations (uncomment if needed) ---
-        # "--enable-notifications --enable-otr --enable-pgp --enable-omemo
-        # --enable-plugins --enable-c-plugins --enable-python-plugins"
-        # "--enable-notifications --enable-otr"
-        # "--enable-notifications --enable-otr --enable-pgp"
-        # "--enable-notifications --enable-otr --enable-pgp --enable-omemo"
-        # "--enable-notifications --enable-otr --enable-pgp --enable-omemo
-        # --enable-plugins"
-        # "--enable-notifications --enable-otr --enable-pgp --enable-omemo
-        # --enable-plugins --enable-c-plugins"
-        # "--enable-notifications --enable-otr --enable-pgp --enable-omemo
-        # --enable-icons-and-clipboard"
         )
         ;;
     openbsd*)
@@ -139,18 +109,6 @@ case "$ARCH" in
         "--disable-plugins --disable-c-plugins --disable-python-plugins"
         # 5. Default configuration
         ""
-        # --- Additional configurations (uncomment if needed) ---
-        # "--enable-notifications --enable-otr --enable-pgp --enable-omemo
-        # --enable-plugins --enable-c-plugins --enable-python-plugins"
-        # "--enable-notifications --enable-otr"
-        # "--enable-notifications --enable-otr --enable-pgp"
-        # "--enable-notifications --enable-otr --enable-pgp --enable-omemo"
-        # "--enable-notifications --enable-otr --enable-pgp --enable-omemo
-        # --enable-plugins"
-        # "--enable-notifications --enable-otr --enable-pgp --enable-omemo
-        # --enable-plugins --enable-c-plugins"
-        # "--enable-notifications --enable-otr --enable-pgp --enable-omemo
-        # --enable-icons-and-clipboard"
         )
         ;;
 esac

prof.supp

@@ -12,27 +12,6 @@
 # Functional tests suppressions (stabber/pthread)
 # ============================================
 
-{
-  stabber_recv_shutdown
-  Memcheck:Param
-  socketcall.recvfrom(buf)
-  fun:recv
-  fun:_shutdown
-  ...
-  obj:*/libstabber*
-}
-
-{
-  stabber_recv_read_stream
-  Memcheck:Param
-  socketcall.recvfrom(buf)
-  fun:recv
-  ...
-  fun:read_stream
-  ...
-  obj:*/libstabber*
-}
-
 {
   stabber_pthread_create
   Memcheck:Leak

src/command/cmd_defs.c

@@ -139,6 +139,7 @@ static const struct cmd_t command_defs[] = {
               "Show version and license information.")
     },
 
+    // Max args: account + server <s> + port <p> + tls <t> + auth <a> = 9
     { CMD_PREAMBLE("/connect",
                    parse_args, 0, 9, NULL)
       CMD_MAINFUNC(cmd_connect)

tests/functionaltests/functionaltests.c

@@ -8,6 +8,12 @@
  * init_prof_test (starts stabber server and profanity client)
  * and close_prof_test (cleanup) as setup/teardown functions.
  *
+ * NOTE: We restart client and server for each test to ensure complete
+ * isolation. This prevents state leakage between tests (roster entries,
+ * MUC rooms, presence subscriptions, etc.). While slower, it eliminates
+ * flaky tests caused by leftover state. The overhead is acceptable since
+ * functional tests run less frequently than unit tests.
+ *
  * Tests are organized into groups for better maintainability:
  *   Group 1: Connection, Ping, Rooms, Presence
  *   Group 2: Messages, Receipts, Roster management

tests/functionaltests/proftest.c

@@ -24,7 +24,11 @@ int fd = 0;
 int stub_port = 5230;
 pid_t child_pid = 0;
 
-/* Buffer for accumulating output from profanity */
+/*
+ * Buffer for accumulating output from profanity.
+ * 64KB is sufficient for typical test output while keeping memory usage
+ * reasonable. When full, older half is discarded (ring buffer behavior).
+ */
 #define OUTPUT_BUF_SIZE 65536
 static char output_buffer[OUTPUT_BUF_SIZE];
 static size_t output_len = 0;
@@ -300,7 +304,12 @@ close_prof_test(void **state)
     }
 
     stbbr_stop();
-    // Give stabber time to release the port
+    /*
+     * TODO: Replace with proper synchronization.
+     * stabber doesn't provide wait_stopped() API yet, so we use delay
+     * to ensure the port is released before the next test starts.
+     * See: https://git.jabber.space/devs/stabber/issues/3
+     */
     usleep(100000);  // 100ms
     return 0;
 }

tests/functionaltests/test_chat_session.c

@@ -144,7 +144,11 @@ resets_to_barejid_after_presence_received(void **state)
             "<show>dnd</show>"
         "</presence>"
     );
-    sleep(1);
+    // TODO: This assertion is currently disabled because the presence update
+    // may not reliably appear in the console output when a chat session is active.
+    // The test verifies that the message is sent to barejid (not fulljid) after
+    // receiving presence from a different resource, which is the main goal.
+    // See: PR #63 review discussion
     // assert_true(prof_output_regex("Buddy1.*dnd"));
 
     prof_input("/msg buddy1@localhost Outgoing 2");

tests/functionaltests/test_muc.c

@@ -8,6 +8,14 @@
 
 #include "proftest.h"
 
+/*
+ * NOTE: We use prof_output_regex() throughout this file even for seemingly
+ * exact strings because some output may include timestamps, color codes,
+ * or other dynamic content depending on configuration. Using regex provides
+ * more robust matching. For patterns without regex metacharacters, the
+ * performance difference is negligible.
+ */
+
 void
 sends_room_join(void **state)
 {

tests/functionaltests/test_ping.c

@@ -11,8 +11,13 @@
 void
 ping_server(void **state)
 {
-    // This test verifies that profanity correctly handles the /ping command
+    /*
-    // when the server supports ping (urn:xmpp:ping feature)
+     * This test verifies that profanity correctly handles the /ping command
+     * when the server supports ping (urn:xmpp:ping feature).
+     * 
+     * We register disco#info response with ping support, then verify
+     * profanity sends ping and receives "Pinged server" confirmation.
+     */
     
     // Register disco#info response that includes ping support
     stbbr_for_query("http://jabber.org/protocol/disco#info",
@@ -31,15 +36,18 @@ ping_server(void **state)
 
     prof_connect();
     
-    // Wait for disco#info exchange to complete
+    /*
+     * Wait for disco#info exchange to complete.
+     * TODO: Replace with proper wait mechanism (e.g., wait for capabilities
+     * to be cached). Currently we use sleep to ensure disco#info response
+     * is processed before sending /ping command.
+     */
     sleep(3);
 
-    // Send ping command - should either work or report server doesn't support it
     prof_input("/ping");
     
     prof_timeout(10);
-    // Accept either outcome: ping was sent OR server doesn't support
+    assert_true(prof_output_regex("Pinged server"));
-    assert_true(prof_output_regex("Ping|Server does not support"));
     prof_timeout_reset();
 }