tests: add some comments to the wifi connection completion tests

src/tests/test-wifi-ap-utils.c

@@ -284,6 +284,10 @@ test_open_ap_empty_connection (void)
 	gboolean success;
 	GError *error = NULL;
 
+	/* Test that an empty source connection is correctly filled with the
+	 * SSID and Infra modes of the given AP details.
+	 */
+
 	src = nm_connection_new ();
 	success = complete_connection (ssid, bssid,
 	                               NM_802_11_MODE_INFRA, NM_802_11_AP_FLAGS_NONE,
@@ -308,6 +312,11 @@ test_open_ap_leap_connection_1 (gboolean add_wifi)
 	gboolean success;
 	GError *error = NULL;
 
+	/* Test that a basic connection filled with a LEAP username is
+	 * rejected when completion is attempted with an open AP.  LEAP requires
+	 * the AP to have the Privacy bit set.
+	 */
+
 	src = nm_connection_new ();
 	if (add_wifi)
 		fill_wifi_empty (src);
@@ -335,6 +344,10 @@ test_open_ap_leap_connection_2 (void)
 	gboolean success;
 	GError *error = NULL;
 
+	/* Test that a basic connection specifying IEEE8021x security (ie, Dynamic
+	 * WEP or LEAP) is rejected when completion is attempted with an open AP.
+	 */
+
 	src = nm_connection_new ();
 	fill_wifi_empty (src);
 	fill_wsec (src, src_wsec);
@@ -365,6 +378,10 @@ test_open_ap_wep_connection (gboolean add_wifi)
 	gboolean success;
 	GError *error = NULL;
 
+	/* Test that a static WEP connection is rejected when completion is
+	 * attempted with an open AP.
+	 */
+
 	src = nm_connection_new ();
 	if (add_wifi)
 		fill_wifi_empty (src);
@@ -426,6 +443,10 @@ test_ap_wpa_psk_connection_base (const char *key_mgmt,
 static void
 test_open_ap_wpa_psk_connection_1 (void)
 {
+	/* Test that a WPA-PSK connection filling only the PSK itself and *not*
+	 * filling the wifi setting is rejected when completion is attempted with
+	 * an open AP.
+	 */
 	test_ap_wpa_psk_connection_base (NULL, NULL,
 	                                 NM_802_11_AP_FLAGS_NONE,
 	                                 NM_802_11_AP_SEC_NONE,
@@ -436,16 +457,23 @@ test_open_ap_wpa_psk_connection_1 (void)
 static void
 test_open_ap_wpa_psk_connection_2 (void)
 {
+	/* Test that a WPA-PSK connection filling only the PSK itself and also
+	 * filling the wifi setting is rejected when completion is attempted with
+	 * an open AP.
+	 */
 	test_ap_wpa_psk_connection_base (NULL, NULL,
 	                                 NM_802_11_AP_FLAGS_NONE,
 	                                 NM_802_11_AP_SEC_NONE,
 	                                 NM_802_11_AP_SEC_NONE,
-	                                 FALSE, NULL);
+	                                 TRUE, NULL);
 }
 
 static void
 test_open_ap_wpa_psk_connection_3 (void)
 {
+	/* Test that a WPA-PSK connection filling the PSK and setting the auth alg
+	 * to 'open' is rejected when completion is attempted with an open AP.
+	 */
 	test_ap_wpa_psk_connection_base (NULL, "open",
 	                                 NM_802_11_AP_FLAGS_NONE,
 	                                 NM_802_11_AP_SEC_NONE,
@@ -456,6 +484,10 @@ test_open_ap_wpa_psk_connection_3 (void)
 static void
 test_open_ap_wpa_psk_connection_4 (void)
 {
+	/* Test that a WPA-PSK connection filling the PSK and setting the auth alg
+	 * to 'shared' is rejected when completion is attempted with an open AP.
+	 * Shared auth cannot be used with WPA.
+	 */
 	test_ap_wpa_psk_connection_base (NULL, "shared",
 	                                 NM_802_11_AP_FLAGS_NONE,
 	                                 NM_802_11_AP_SEC_NONE,
@@ -466,6 +498,9 @@ test_open_ap_wpa_psk_connection_4 (void)
 static void
 test_open_ap_wpa_psk_connection_5 (void)
 {
+	/* Test that a WPA-PSK connection filling the PSK, the auth algorithm, and
+	 * key management is rejected when completion is attempted with an open AP.
+	 */
 	test_ap_wpa_psk_connection_base ("wpa-psk", "open",
 	                                 NM_802_11_AP_FLAGS_NONE,
 	                                 NM_802_11_AP_SEC_NONE,
@@ -663,6 +698,10 @@ test_priv_ap_empty_connection (void)
 	gboolean success;
 	GError *error = NULL;
 
+	/* Test that an empty connection is completed to a valid Static WEP
+	 * connection when completed with an AP with the Privacy bit set.
+	 */
+
 	src = nm_connection_new ();
 	success = complete_connection (ssid, bssid,
 	                               NM_802_11_MODE_INFRA, NM_802_11_AP_FLAGS_PRIVACY,
@@ -700,6 +739,11 @@ test_priv_ap_leap_connection_1 (gboolean add_wifi)
 	gboolean success;
 	GError *error = NULL;
 
+	/* Test that an minimal LEAP connection specifying only key management and
+	 * the LEAP username is completed to a full LEAP connection when completed
+	 * with an AP with the Privacy bit set.
+	 */
+
 	src = nm_connection_new ();
 	if (add_wifi)
 		fill_wifi_empty (src);
@@ -734,6 +778,11 @@ test_priv_ap_leap_connection_2 (void)
 	gboolean success;
 	GError *error = NULL;
 
+	/* Test that an minimal LEAP connection specifying only key management and
+	 * the LEAP auth alg is completed to a full LEAP connection when completed
+	 * with an AP with the Privacy bit set.
+	 */
+
 	src = nm_connection_new ();
 	fill_wifi_empty (src);
 	fill_wsec (src, src_wsec);
@@ -776,6 +825,11 @@ test_priv_ap_dynamic_wep_1 (void)
 	gboolean success;
 	GError *error = NULL;
 
+	/* Test that an minimal Dynamic WEP connection specifying key management,
+	 * the auth algorithm, and valid 802.1x setting is completed to a valid
+	 * Dynamic WEP connection when completed with an AP with the Privacy bit set.
+	 */
+
 	src = nm_connection_new ();
 	fill_wifi_empty (src);
 	fill_wsec (src, src_wsec);
@@ -822,6 +876,11 @@ test_priv_ap_dynamic_wep_2 (void)
 	gboolean success;
 	GError *error = NULL;
 
+	/* Test that an minimal Dynamic WEP connection specifying only the auth
+	 * algorithm and a valid 802.1x setting is completed to a valid Dynamic
+	 * WEP connection when completed with an AP with the Privacy bit set.
+	 */
+
 	src = nm_connection_new ();
 	fill_wifi_empty (src);
 	fill_wsec (src, src_wsec);
@@ -859,6 +918,10 @@ test_priv_ap_dynamic_wep_3 (void)
 	gboolean success;
 	GError *error = NULL;
 
+	/* Ensure that a basic connection specifying 'shared' auth and an 802.1x
+	 * setting is rejected, as 802.1x is incompatible with 'shared' auth.
+	 */
+
 	src = nm_connection_new ();
 	fill_wifi_empty (src);
 	fill_wsec (src, src_wsec);
@@ -879,6 +942,10 @@ test_priv_ap_dynamic_wep_3 (void)
 static void
 test_priv_ap_wpa_psk_connection_1 (void)
 {
+	/* Test that a basic WPA-PSK connection is rejected when completion is
+	 * attempted with an AP with just the Privacy bit set.  Lack of WPA/RSN
+	 * flags means the AP provides Static/Dynamic WEP or LEAP, not WPA.
+	 */
 	test_ap_wpa_psk_connection_base (NULL, NULL,
 	                                 NM_802_11_AP_FLAGS_PRIVACY,
 	                                 NM_802_11_AP_SEC_NONE,
@@ -889,6 +956,10 @@ test_priv_ap_wpa_psk_connection_1 (void)
 static void
 test_priv_ap_wpa_psk_connection_2 (void)
 {
+	/* Test that a basic WPA-PSK connection is rejected when completion is
+	 * attempted with an AP with just the Privacy bit set.  Lack of WPA/RSN
+	 * flags means the AP provides Static/Dynamic WEP or LEAP, not WPA.
+	 */
 	test_ap_wpa_psk_connection_base (NULL, NULL,
 	                                 NM_802_11_AP_FLAGS_PRIVACY,
 	                                 NM_802_11_AP_SEC_NONE,
@@ -899,6 +970,11 @@ test_priv_ap_wpa_psk_connection_2 (void)
 static void
 test_priv_ap_wpa_psk_connection_3 (void)
 {
+	/* Test that a basic WPA-PSK connection specifying only the auth algorithm
+	 * is rejected when completion is attempted with an AP with just the Privacy
+	 * bit set.  Lack of WPA/RSN flags means the AP provides Static/Dynamic WEP
+	 * or LEAP, not WPA.
+	 */
 	test_ap_wpa_psk_connection_base (NULL, "open",
 	                                 NM_802_11_AP_FLAGS_PRIVACY,
 	                                 NM_802_11_AP_SEC_NONE,
@@ -909,6 +985,11 @@ test_priv_ap_wpa_psk_connection_3 (void)
 static void
 test_priv_ap_wpa_psk_connection_4 (void)
 {
+	/* Test that a basic WPA-PSK connection specifying only the auth algorithm
+	 * is rejected when completion is attempted with an AP with just the Privacy
+	 * bit set.  Lack of WPA/RSN flags means the AP provides Static/Dynamic WEP
+	 * or LEAP, not WPA.  Second, 'shared' auth is incompatible with WPA.
+	 */
 	test_ap_wpa_psk_connection_base (NULL, "shared",
 	                                 NM_802_11_AP_FLAGS_PRIVACY,
 	                                 NM_802_11_AP_SEC_NONE,
@@ -919,6 +1000,11 @@ test_priv_ap_wpa_psk_connection_4 (void)
 static void
 test_priv_ap_wpa_psk_connection_5 (void)
 {
+	/* Test that a WPA-PSK connection specifying both the key management and
+	 * auth algorithm is rejected when completion is attempted with an AP with
+	 * just the Privacy bit set.  Lack of WPA/RSN flags means the AP provides
+	 * Static/Dynamic WEP or LEAP, not WPA.
+	 */
 	test_ap_wpa_psk_connection_base ("wpa-psk", "open",
 	                                 NM_802_11_AP_FLAGS_PRIVACY,
 	                                 NM_802_11_AP_SEC_NONE,
@@ -941,6 +1027,11 @@ test_wpa_ap_empty_connection (guint idx)
 	gboolean success;
 	GError *error = NULL;
 
+	/* Test that a basic WPA-PSK connection specifying just key management and
+	 * the auth algorithm is completed successfully when given an AP with WPA
+	 * or RSN flags.
+	 */
+
 	src = nm_connection_new ();
 	success = complete_connection (ssid, bssid,
 	                               NM_802_11_MODE_INFRA, NM_802_11_AP_FLAGS_PRIVACY,
@@ -948,7 +1039,7 @@ test_wpa_ap_empty_connection (guint idx)
 	                               rsn_flags_for_idx (idx),
 	                               FALSE, src, &error);
 
-	/* Static WEP connection expected */
+	/* WPA connection expected */
 	expected = create_basic (ssid, NULL, NM_802_11_MODE_INFRA, TRUE);
 	fill_wsec (expected, exp_wsec);
 	COMPARE (src, expected, success, error, 0, 0);
@@ -973,6 +1064,10 @@ test_wpa_ap_leap_connection_1 (guint idx)
 	gboolean success;
 	GError *error = NULL;
 
+	/* Test that completion of a LEAP connection with a WPA-enabled AP is
+	 * rejected since WPA APs (usually) do not support LEAP.
+	 */
+
 	src = nm_connection_new ();
 	fill_wifi_empty (src);
 	fill_wsec (src, src_wsec);
@@ -1002,6 +1097,10 @@ test_wpa_ap_leap_connection_2 (guint idx)
 	gboolean success;
 	GError *error = NULL;
 
+	/* Test that completion of a LEAP connection with a WPA-enabled AP is
+	 * rejected since WPA APs (usually) do not support LEAP.
+	 */
+
 	src = nm_connection_new ();
 	fill_wifi_empty (src);
 	fill_wsec (src, src_wsec);
@@ -1030,6 +1129,10 @@ test_wpa_ap_dynamic_wep_connection (guint idx)
 	gboolean success;
 	GError *error = NULL;
 
+	/* Test that completion of a Dynamic WEP connection with a WPA-enabled AP is
+	 * rejected since WPA APs (usually) do not support Dynamic WEP.
+	 */
+
 	src = nm_connection_new ();
 	fill_wifi_empty (src);
 	fill_wsec (src, src_wsec);