tests: Add some extra comments for tests and helper functions

Signed-off-by: Brian Goff <[email protected]>

test/handlers_test.go

@@ -101,6 +101,8 @@ func TestHandlerTargetForwarding(t *testing.T) {
 				return nil, err
 			}
 
+			// The phony/debug/resolve target creates a file with the contents "phony resolve".
+			// Check that its there to ensure we got the expected target.
 			checkFile(ctx, t, "resolve", res, []byte("phony resolve"))
 			return gwclient.NewResult(), nil
 		})

test/testenv/buildkit.go

@@ -65,11 +65,22 @@ func supportsFrontendAsInput(info *client.Info) bool {
 	return minor >= minVersion.Minor
 }
 
+// withGHCache adds the necessary cache export and import options to the solve request in order to use the GitHub Actions cache.
+// It uses the test name as a scope for the cache. Each test will have its own scope.
+// This means that caches are not shared between tests, but it also means that tests won't ovewrite each other's cache.
+//
+// Github Actions sets some specific environment variables that we'll look for to even determine if we should configure the cache or not.
+//
+// This is effectively what `docker build --cache-from=gha,scope=foo --cache-to=gha,mode=max,scope=foo` would do.
 func withGHCache(t *testing.T, so *client.SolveOpt) {
 	if os.Getenv("GITHUB_ACTIONS") != "true" {
+		// This is not running in GitHub Actions, so we don't need to configure the cache.
 		return
 	}
 
+	// token and url are required for the cache to work.
+	// These need to be exposed as environment variables in the GitHub Actions workflow.
+	// See the crazy-max/ghaction-github-runtime@v3 action.
 	token := os.Getenv("ACTIONS_RUNTIME_TOKEN")
 	if token == "" {
 		fmt.Fprintln(os.Stderr, "::warning::GITHUB_ACTIONS_RUNTIME_TOKEN is not set, skipping cache export")

test/testenv/buildx.go

@@ -56,6 +56,8 @@ func (b *BuildxEnv) Load(ctx context.Context, id string, f gwclient.BuildFunc) e
 	return nil
 }
 
+// bootstrap is ultimately responsible for creating a buildkit client.
+// It looks like the buildx config on the client (typically in $HOME/.docker/buildx) to determine how to connect to the configured buildkit.
 func (b *BuildxEnv) bootstrap(ctx context.Context) (retErr error) {
 	if b.client != nil {
 		return nil
@@ -95,6 +97,8 @@ func (b *BuildxEnv) bootstrap(ctx context.Context) (retErr error) {
 
 	configBase := filepath.Join(filepath.Dir(p), "buildx")
 
+	// builder is empty, so we need to check what the currently configured buildx builder is.
+	// This is stored int he buildx config in (typically) $HOME/.docker/buildx (the `dockercfg` lib determines where this actually is).
 	if b.builder == "" {
 		dt, err := os.ReadFile(filepath.Join(configBase, "current"))
 		if err != nil {
@@ -150,6 +154,8 @@ func (b *BuildxEnv) bootstrap(ctx context.Context) (retErr error) {
 		return pkgerrors.Errorf("no buildx nodes configured")
 	}
 
+	// On a typical client this would be a single node, but there could be multiple registered with he same builder name.
+	// We'll just try them all until we find one that works.
 	var errs []error
 	for _, n := range cfg.Nodes {
 		tr, err := transport.FromConnectionString(n.Endpoint)