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

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("Ping|Server does not support"));
+    assert_true(prof_output_regex("Pinged server"));
     prof_timeout_reset();
 }