integration: Use Eventually around external calls (#2685)

integration/utils.go

@@ -21,8 +21,13 @@ import (
 )
 
 const (
+	// derpPingTimeout defines the timeout for individual DERP ping operations
+	// Used in DERP connectivity tests to verify relay server communication
 	derpPingTimeout = 2 * time.Second
-	derpPingCount   = 10
+	
+	// derpPingCount defines the number of ping attempts for DERP connectivity tests
+	// Higher count provides better reliability assessment of DERP connectivity
+	derpPingCount = 10
 )
 
 func assertNoErr(t *testing.T, err error) {
@@ -105,6 +110,9 @@ func didClientUseWebsocketForDERP(t *testing.T, client TailscaleClient) bool {
 	return count > 0
 }
 
+// pingAllHelper performs ping tests between all clients and addresses, returning success count.
+// This is used to validate network connectivity in integration tests.
+// Returns the total number of successful ping operations.
 func pingAllHelper(t *testing.T, clients []TailscaleClient, addrs []string, opts ...tsic.PingOption) int {
 	t.Helper()
 	success := 0
@@ -123,6 +131,9 @@ func pingAllHelper(t *testing.T, clients []TailscaleClient, addrs []string, opts
 	return success
 }
 
+// pingDerpAllHelper performs DERP-based ping tests between all clients and addresses.
+// This specifically tests connectivity through DERP relay servers, which is important
+// for validating NAT traversal and relay functionality. Returns success count.
 func pingDerpAllHelper(t *testing.T, clients []TailscaleClient, addrs []string) int {
 	t.Helper()
 	success := 0
@@ -304,9 +315,13 @@ func assertValidNetcheck(t *testing.T, client TailscaleClient) {
 	assert.NotEqualf(t, 0, report.PreferredDERP, "%q does not have a DERP relay", client.Hostname())
 }
 
-// assertCommandOutputContains executes a command for a set time and asserts that the output
-// reaches a desired state.
-// It should be used instead of sleeping before executing.
+// assertCommandOutputContains executes a command with exponential backoff retry until the output
+// contains the expected string or timeout is reached (10 seconds).
+// This implements eventual consistency patterns and should be used instead of time.Sleep 
+// before executing commands that depend on network state propagation.
+//
+// Timeout: 10 seconds with exponential backoff
+// Use cases: DNS resolution, route propagation, policy updates
 func assertCommandOutputContains(t *testing.T, c TailscaleClient, command []string, contains string) {
 	t.Helper()