Explain complex Go test cases

Signed-off-by: Kaylee Lubick <klubick@nvidia.com>

Author: kjlubick

scripts/inference-dispatcher/dispatcher_test.go

@@ -51,6 +51,8 @@ func configuredTestClient(t *testing.T, args []string, baseURL string, stderr *b
 	return cfg, client
 }
 
+// The inventory puts an embedding model first and chat models out of order.
+// Default selection must find a generation-capable model rather than use list order.
 func TestOmittedModel_SelectsAvailableGenerationModel(t *testing.T) {
 	var receivedModel string
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -145,6 +147,8 @@ func TestLMStudio_FallsBackToOpenAIInventory(t *testing.T) {
 	assert.Contains(t, stdout.String(), "live-model", "selected model missing from output")
 }
 
+// llama.cpp exposes OpenAI inventory and chat routes rather than Ollama's native
+// API. Auto-selection and dispatch must agree on that protocol.
 func TestLlamaCPP_UsesOpenAIInventoryAndChat(t *testing.T) {
 	type observedRequest struct {
 		method       string

services/nvpair-cluster-manager/admission_migration_test.go

@@ -33,6 +33,8 @@ func TestLegacyPairingInfo_MapsToFirstAdmission(t *testing.T) {
 	require.Error(t, err, "v2 pairing info without admission epoch was accepted")
 }
 
+// Old persisted pins lack admission metadata. Restart must bind them to the
+// current cluster so existing members remain trusted and removable while offline.
 func TestRestart_MigratesLegacyPinnedMemberAdmission(t *testing.T) {
 	dir := t.TempDir()
 	m := testManagerAt(t, dir, 15124)

services/nvpair-engine-manager/executor_test.go

@@ -76,6 +76,8 @@ func TestEngineHTTPClients_BoundResponseHeaderWait(t *testing.T) {
 	require.Equal(t, ollamaLoadResponseHeaderTimeout, responseHeaderTimeout(t, ex.ollamaLoadClient), "Ollama load response-header timeout")
 }
 
+// A cold Ollama model load can delay response headers. Only that action gets the
+// longer budget, so unrelated operations still detect an unresponsive engine quickly.
 func TestOnlyOllamaRunModel_UsesSlowResponseHeaderBudget(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
 		time.Sleep(100 * time.Millisecond)
@@ -229,6 +231,8 @@ func TestEngineLifecycle_DetectsStartsReportsHealthAndStops(t *testing.T) {
 	require.False(t, st.Running, "expected stopped (%v)", st)
 }
 
+// Another application can claim the port after a managed process crashes.
+// Restart must recognize that owner instead of spawning a competing process.
 func TestCrashThenExternalService_IsAdoptedWithoutRespawn(t *testing.T) {
 	port, err := freePort()
 	require.NoError(t, err)
@@ -595,6 +599,8 @@ func TestAdoptedEngine_ReportsObservedLiveness(t *testing.T) {
 	require.False(t, st.Healthy, "closed external listener remained present (%v)", st)
 }
 
+// The proxy also answers health requests on loopback. The identity probe must
+// distinguish it from Ollama, or forwarding can route requests back into the proxy.
 func TestProxyFacade_CannotIdentifyAsOllama(t *testing.T) {
 	var probes atomic.Int32
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -636,6 +642,8 @@ func TestProxyFacade_CannotIdentifyAsOllama(t *testing.T) {
 	require.NotEqual(t, int32(0), probes.Load(), "engine identity probe did not carry the proxy sentinel")
 }
 
+// A successful earlier identity check does not identify a new listener on the
+// same port. Losing that identity must block adoption and installation.
 func TestPreviouslyAdoptedForeignReplacement_FailsClosed(t *testing.T) {
 	var isOllama atomic.Bool
 	isOllama.Store(true)

services/nvpair-engine-manager/models_test.go

@@ -16,6 +16,8 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
+// Engines use different inventory shapes and loaded-model markers. Only rows
+// matching the configured path and filter may become model identifiers.
 func TestExtractStrings_ReadsConfiguredResultPath(t *testing.T) {
 	tests := []struct {
 		name string

services/nvpair-engine-manager/pull_llamacpp_test.go

@@ -286,6 +286,8 @@ func TestLlamaCPPPull_PreservesOtherDownloadWhenStartIsRejected(t *testing.T) {
 	test("negative acknowledgement", http.StatusOK, `{"success":false}`)
 }
 
+// Cancellation can race an unreadable start acknowledgement. Without proof that
+// this request started the download, cleanup could unload another caller's model.
 func TestLlamaCPPPullUnconfirmedStart_DoesNotUnload(t *testing.T) {
 	test := func(name string, respond func(*testing.T, http.ResponseWriter, *http.Request)) {
 		t.Run(name, func(t *testing.T) {

services/nvpair-engine-manager/pull_test.go

@@ -88,6 +88,8 @@ func newHTTPPullTestExecutor(t *testing.T, server *httptest.Server, action Actio
 	return executor
 }
 
+// A fast download can finish as soon as the start request arrives. Subscribe
+// first so its terminal event cannot be missed and leave the caller waiting.
 func TestPullModelLlamaCPP_SubscribesToProgressBeforeStartingDownload(t *testing.T) {
 	const model = "owner/repo:Q4_K_M"
 	subscribed := make(chan struct{})
@@ -169,6 +171,8 @@ func TestPullModelLlamaCPP_SubscribesToProgressBeforeStartingDownload(t *testing
 	require.Equal(t, 100, events[1].Percent)
 }
 
+// The complete download deliberately exceeds one idle interval. Advancing bytes
+// must extend the deadline so slow progress is not mistaken for a stalled download.
 func TestPullModelOllamaAdvancingProgress_RefreshesTimeout(t *testing.T) {
 	const (
 		idleTimeout     = 400 * time.Millisecond
@@ -216,6 +220,8 @@ func TestPullModelOllamaAdvancingProgress_RefreshesTimeout(t *testing.T) {
 	require.Contains(t, string(result), `"status":"success"`, "pull must report terminal success")
 }
 
+// The SSE stream keeps advancing beyond the initial idle deadline. Each progress
+// update must renew that budget instead of imposing a total download time limit.
 func TestPullModelLlamaCPPAdvancingProgress_RefreshesTimeout(t *testing.T) {
 	const (
 		model           = "owner/repo:Q4_K_M"

services/nvpair-engine-manager/settings_test.go

@@ -275,6 +275,8 @@ const (
 	restartsProcess
 )
 
+// Changing only the proxy port must preserve a running engine, while engine
+// launch changes require a restart. Editing stopped engines must not start them.
 func TestConfigureLaunch_AppliesSettingsForEachEngineLifecycleState(t *testing.T) {
 	test := func(name string, want lifecycle, edit func(*testing.T, *settings.Request)) {
 		t.Run(name, func(t *testing.T) {
@@ -443,6 +445,8 @@ func TestSettings_ValidatesAndNormalizesCORSOrigins(t *testing.T) {
 	reject("wildcard in origin list", "http://localhost,*", "every origin")
 }
 
+// Only controls declared by the manifest carry CORS meaning. Treating arbitrary
+// engine flags as CORS settings could reject valid options or bypass declared checks.
 func TestSettingsCORS_IsOptionalAndIndependentOfEngine(t *testing.T) {
 	setup := func(t *testing.T, corsEnv, corsFlag, prefix, suffix string) (*Executor, settings.Request, settings.Preview) {
 		t.Helper()

services/nvpair-engine-manager/settingsremote_test.go

@@ -87,6 +87,8 @@ func TestNotifyPeerSettings_ForwardsEverySupportedEngine(t *testing.T) {
 	}
 }
 
+// Two pinned peers observe the same mutation, then one loses its pin. Revocation
+// must close its existing stream as well as reject new unauthenticated requests.
 func TestPairedSettings_PushesChangesAndRevokesObservers(t *testing.T) {
 	a, certA := settingsMesh(t, "a")
 	b, certB := settingsMesh(t, "b")
@@ -243,6 +245,8 @@ func TestSettingsRemoteOnlyCORS_IsLocalOnly(t *testing.T) {
 	}
 }
 
+// Replies arrive in reverse request order to expose accidental FIFO matching.
+// Cancellation must also remove its waiter so a later reply cannot retain it.
 func TestSettingsRelay_CorrelatesResponsesAndCleansUpCancelledRequests(t *testing.T) {
 	sent := make(chan settings.Relay, 2)
 	canceled := make(chan string, 1)

services/nvpair-job-scheduler/telemetry_test.go

@@ -15,6 +15,8 @@ import (
 	"nvpair-shared/schedulerwire"
 )
 
+// Dropping to a lower pressure band requires more headroom than entering it.
+// This prevents small utilization fluctuations from repeatedly changing node order.
 func TestTelemetryPressure_UsesBandsAndDownwardHysteresis(t *testing.T) {
 	bands := []struct {
 		utilization float64

services/nvpair-node-scanner/node_info_outage_test.go

@@ -94,6 +94,8 @@ func TestNodeInfoTransport_BoundsConnectionsPerHost(t *testing.T) {
 	require.Equal(t, 1, transport.MaxIdleConnsPerHost)
 }
 
+// Two requests share one connection and each fits its own timeout. Time spent
+// waiting for that connection must not consume the second request's response budget.
 func TestNodeInfoFetches_UseIndependentRequestBudgets(t *testing.T) {
 	const responseDelay = 200 * time.Millisecond
 	var requests atomic.Int32