fix(tests): enhance documentation and organization of functional tests for clarity

tests/functionaltests/functionaltests.c

@@ -1,3 +1,20 @@
+/*
+ * functionaltests.c
+ *
+ * Functional tests for CProof XMPP client.
+ * Uses cmocka framework with stabber mock XMPP server.
+ *
+ * Each test is wrapped with PROF_FUNC_TEST macro which sets up
+ * init_prof_test (starts stabber server and profanity client)
+ * and close_prof_test (cleanup) as setup/teardown functions.
+ *
+ * Tests are organized into groups for better maintainability:
+ *   Group 1: Connection, Ping, Rooms, Presence
+ *   Group 2: Messages, Receipts, Roster management
+ *   Group 3: MUC (Multi-User Chat) functionality
+ *   Group 4: Carbons, Chat sessions, Software version, Disconnect
+ */
+
 #include <stdio.h>
 #include <unistd.h>
 #include <fcntl.h>
@@ -20,27 +37,37 @@
 #include "test_muc.h"
 #include "test_disconnect.h"
 
+/* Macro to wrap each test with setup/teardown functions */
 #define PROF_FUNC_TEST(test) cmocka_unit_test_setup_teardown(test, init_prof_test, close_prof_test)
 
-int main(int argc, char* argv[]) {
-
+int
+main(int argc, char* argv[])
+{
     const struct CMUnitTest all_tests[] = {
 
-        // --- GROUP 1: Connect, Ping, Rooms, Presence ---
+        /* ============================================================
+         * GROUP 1: Connect, Ping, Rooms, Presence
+         * Basic XMPP session establishment and presence management
+         * ============================================================ */
+
+        /* Connection tests - verify login, roster, bookmarks */
         PROF_FUNC_TEST(connect_jid_requests_roster),
         PROF_FUNC_TEST(connect_jid_sends_presence_after_receiving_roster),
         PROF_FUNC_TEST(connect_jid_requests_bookmarks),
         PROF_FUNC_TEST(connect_bad_password),
         PROF_FUNC_TEST(connect_shows_presence_updates),
 
+        /* Ping tests - XEP-0199 XMPP Ping */
         PROF_FUNC_TEST(ping_server),
         PROF_FUNC_TEST(ping_server_not_supported),
         PROF_FUNC_TEST(ping_responds_to_server_request),
         PROF_FUNC_TEST(ping_jid),
         PROF_FUNC_TEST(ping_jid_not_supported),
 
+        /* Room discovery - XEP-0045 */
         PROF_FUNC_TEST(rooms_query),
 
+        /* Presence tests - online/away/xa/dnd/chat status */
         PROF_FUNC_TEST(presence_online),
         PROF_FUNC_TEST(presence_online_with_message),
         PROF_FUNC_TEST(presence_away),
@@ -57,38 +84,61 @@ int main(int argc, char* argv[]) {
         PROF_FUNC_TEST(presence_received),
         PROF_FUNC_TEST(presence_missing_resource_defaults),
 
-        // --- GROUP 2: Message, Receipts, Roster ---
+        /* ============================================================
+         * GROUP 2: Message, Receipts, Roster
+         * Core messaging and contact management
+         * ============================================================ */
+
+        /* Basic message send/receive */
         PROF_FUNC_TEST(message_send),
         PROF_FUNC_TEST(message_receive_console),
         PROF_FUNC_TEST(message_receive_chatwin),
 
+        /* Message receipts - XEP-0184 */
         PROF_FUNC_TEST(does_not_send_receipt_request_to_barejid),
         PROF_FUNC_TEST(send_receipt_request),
         PROF_FUNC_TEST(send_receipt_on_request),
 
+        /* Roster management - add/remove/rename contacts */
         PROF_FUNC_TEST(sends_new_item),
         PROF_FUNC_TEST(sends_new_item_nick),
         PROF_FUNC_TEST(sends_remove_item),
         PROF_FUNC_TEST(sends_remove_item_nick),
         PROF_FUNC_TEST(sends_nick_change),
 
-        // --- GROUP 3: MUC ---
+        /* ============================================================
+         * GROUP 3: MUC (Multi-User Chat)
+         * XEP-0045 conference room functionality
+         * ============================================================ */
+
+        /* Room join with various options */
         PROF_FUNC_TEST(sends_room_join),
         PROF_FUNC_TEST(sends_room_join_with_nick),
         PROF_FUNC_TEST(sends_room_join_with_password),
         PROF_FUNC_TEST(sends_room_join_with_nick_and_password),
+
+        /* Room information display */
         PROF_FUNC_TEST(shows_role_and_affiliation_on_join),
         PROF_FUNC_TEST(shows_subject_on_join),
-        // PROF_FUNC_TEST(shows_history_message), temporarily disabled due to timing issues in CI
+        // PROF_FUNC_TEST(shows_history_message), // temporarily disabled due to timing issues in CI
         PROF_FUNC_TEST(shows_occupant_join),
+
+        /* MUC messaging */
         PROF_FUNC_TEST(shows_message),
         PROF_FUNC_TEST(shows_me_message_from_occupant),
         PROF_FUNC_TEST(shows_me_message_from_self),
+
+        /* Console notification settings for MUC */
         PROF_FUNC_TEST(shows_all_messages_in_console_when_window_not_focussed),
         PROF_FUNC_TEST(shows_first_message_in_console_when_window_not_focussed),
         PROF_FUNC_TEST(shows_no_message_in_console_when_window_not_focussed),
 
-        // --- GROUP 4: Carbons, Chat Session, Software, Disconnect ---
+        /* ============================================================
+         * GROUP 4: Carbons, Chat Session, Software, Disconnect
+         * Message synchronization and session management
+         * ============================================================ */
+
+        /* Message Carbons - XEP-0280 (message sync across devices) */
         PROF_FUNC_TEST(send_enable_carbons),
         PROF_FUNC_TEST(connect_with_carbons_enabled),
         PROF_FUNC_TEST(send_disable_carbons),
@@ -96,6 +146,7 @@ int main(int argc, char* argv[]) {
         PROF_FUNC_TEST(receive_self_carbon),
         PROF_FUNC_TEST(receive_private_carbon),
 
+        /* Chat session management - bare/full JID routing */
         PROF_FUNC_TEST(sends_message_to_barejid_when_contact_offline),
         PROF_FUNC_TEST(sends_message_to_barejid_when_contact_online),
         PROF_FUNC_TEST(sends_message_to_fulljid_when_received_from_fulljid),
@@ -103,6 +154,7 @@ int main(int argc, char* argv[]) {
         PROF_FUNC_TEST(resets_to_barejid_after_presence_received),
         PROF_FUNC_TEST(new_session_when_message_received_from_different_fulljid),
 
+        /* Software Version - XEP-0092 */
         PROF_FUNC_TEST(send_software_version_request),
         PROF_FUNC_TEST(display_software_version_result),
         PROF_FUNC_TEST(shows_message_when_software_version_error),
@@ -110,6 +162,7 @@ int main(int argc, char* argv[]) {
         PROF_FUNC_TEST(show_message_in_chat_window_when_no_resource),
         PROF_FUNC_TEST(display_software_version_result_in_chat),
 
+        /* Disconnect - clean session termination */
         PROF_FUNC_TEST(disconnect_ends_session),
     };