fix(test): resolve integration test routing, gotestsum PATH, and cross-compilation

- Remove broken test-integration target: TAGS=integration bypassed the t/
  runner, skipping Docker Compose orchestration and plugin compilation that
  integration tests require. Use SUITE= to route through the t/ runner instead.
- Fix gotestsum PATH resolution in t/t.go: add gotestsumBin() that resolves
  to $GOPATH/bin/gotestsum instead of relying on PATH lookup, which fails on
  machines where $GOPATH/bin is not in PATH.
- Add cross-compilation support for Go plugins on macOS: detect non-Linux
  hosts and set CGO_ENABLED=1, CC to the appropriate cross-compiler, and
  use the BFD linker (both testutil/plugin.go and dgraphtest/local_cluster.go).
- Add check-cross-compiler.sh dependency check script.
- Add top-level make deps and make setup targets for dependency management.
- Update TESTING.md and CONTRIBUTING.md to document new targets and recommend
  make setup for first-time onboarding.
- Remove test-integration from test-full (redundant: SUITE=all covers it).

Author: mlwelles

CONTRIBUTING.md

@@ -40,7 +40,8 @@
 ```bash
 git clone https://github.com/dgraph-io/dgraph.git
 cd ./dgraph
-make install
+make setup    # auto-install tool dependencies (gotestsum, ack, etc.)
+make install  # build and install the dgraph binary
 ```
 
 This will put the source code in a Git repo under `$GOPATH/src/github.com/dgraph-io/dgraph` and
@@ -144,6 +145,9 @@ directory, providing control and flexibility beyond the standard Go testing fram
 The simplest way to run tests is via Make:
 
 ```bash
+# First-time setup: install tool dependencies
+make setup
+
 # Run default tests (~30 min): unit, systest, core suites + integration2
 make test
 

Makefile

@@ -78,6 +78,14 @@ dgraph-installed:
 		$(MAKE) install; \
 	fi
 
+.PHONY: deps
+deps: ## Check test dependencies (pass AUTO_INSTALL=true to auto-install missing ones)
+	$(MAKE) -C t check
+
+.PHONY: setup
+setup: ## Install all test dependencies automatically
+	$(MAKE) deps AUTO_INSTALL=true
+
 .PHONY: test
 test: dgraph-installed local-image ## Run tests (default: unit,systest,core + integration2)
 ifdef TAGS
@@ -124,11 +132,6 @@ test-core: ## Core tests (i.e. 'make test SUITE=core')
 	$(if $(filter command line,$(origin SUITE)),$(error SUITE= cannot be passed to test-core; use 'make test SUITE=...' instead))
 	@SUITE=core $(MAKE) test
 
-.PHONY: test-integration
-test-integration: ## Integration tests (i.e. 'make test TAGS=integration')
-	$(if $(filter command line,$(origin TAGS)),$(error TAGS= cannot be passed to test-integration; use 'make test TAGS=...' instead))
-	@TAGS=integration $(MAKE) test
-
 .PHONY: test-integration2
 test-integration2: ## Integration2 tests via dgraphtest (i.e. 'make test TAGS=integration2')
 	$(if $(filter command line,$(origin TAGS)),$(error TAGS= cannot be passed to test-integration2; use 'make test TAGS=...' instead))
@@ -165,9 +168,8 @@ test-load: ## Heavy load tests (i.e. 'make test SUITE=load')
 	@SUITE=load $(MAKE) test
 
 .PHONY: test-full
-test-full: ## Every test: all suites + integration + integration2 + upgrade + fuzz
+test-full: ## Every test: all suites + integration2 + upgrade + fuzz
 	$(MAKE) test-suite
-	$(MAKE) test-integration
 	$(MAKE) test-integration2
 	$(MAKE) test-upgrade
 	$(MAKE) test-fuzz
@@ -188,6 +190,13 @@ local-image: ## Build local Docker image (dgraph/dgraph:local)
 .PHONY: image-local
 image-local: local-image ## Alias for local-image
 
+.PHONY: clean
+clean: ## Clean build artifacts
+	$(MAKE) -C dgraph clean
+	$(MAKE) -C compose clean
+	@rm -rf linux
+	@go clean -testcache
+
 .PHONY: docker-image
 docker-image: dgraph ## Build Docker image (dgraph/dgraph:$VERSION)
 	@mkdir -p linux
@@ -243,8 +252,9 @@ help: ## Show available targets and variables
 	@printf "  Available TAGS values:  "
 	@grep -roh "//go:build [a-z0-9]*" --include="*_test.go" . 2>/dev/null | \
 		awk '{print $$2}' | \
-		grep -E '^(integration|integration2|upgrade)$$' | \
+		grep -E '^(integration2|upgrade)$$' | \
 		sort -u | tr '\n' ' ' && echo ""
+	@echo "  Note: 'integration' tests require the t/ runner (use SUITE=, not TAGS=)"
 	@echo ""
 	@echo "Examples:"
 	@echo "  make test TAGS=integration2 PKG=systest/vector        # integration2 tests for vector"

TESTING.md

@@ -128,20 +128,24 @@ The codebase is organized into several key packages:
 
 Before running tests, ensure you have the following installed and configured.
 
-> **TL;DR:** On a fresh checkout, just run `make install` followed by `make test`. The build system
-> automatically handles OS detection, builds the correct binaries, and validates dependencies.
+> **TL;DR:** On a fresh checkout, run `make setup` to auto-install tool dependencies, then
+> `make install` followed by `make test`. The build system automatically handles OS detection,
+> builds the correct binaries, and validates dependencies.
 
 ### Automatic Dependency Checking
 
 The test framework includes scripts that check for required dependencies and can optionally
 auto-install them:
 
 ```bash
-# Check all dependencies (run from t/ directory)
-cd t && make check
+# Auto-install all missing tool dependencies (recommended for first-time setup)
+make setup
 
-# Auto-install missing dependencies
-AUTO_INSTALL=true make check
+# Check dependencies without installing (reports what's missing)
+make deps
+
+# Same as 'make deps' but auto-installs anything missing
+make deps AUTO_INSTALL=true
 ```
 
 The check scripts validate:
@@ -154,9 +158,8 @@ The check scripts validate:
 
 ### Required Tools
 
-> **Note:** You don't need to install these manually. Running `AUTO_INSTALL=true make check` from
-> the `t/` directory (or `AUTO_INSTALL=true make test` from the repo root) automatically installs
-> missing dependencies. The commands below are listed for reference.
+> **Note:** You don't need to install these manually. Running `make setup` from the repo root
+> automatically installs missing dependencies. The commands below are listed for reference.
 
 #### 1. Go (1.21+)
 
@@ -222,8 +225,8 @@ dgraph version
 The build system now handles most setup automatically. On both Linux and macOS:
 
 ```bash
-# Install dependencies (optional - auto-installs if missing)
-cd t && AUTO_INSTALL=true make check && cd ..
+# Auto-install tool dependencies (gotestsum, ack, etc.)
+make setup
 
 # Build dgraph binary (automatically handles Linux binary on macOS)
 make install
@@ -318,7 +321,6 @@ make test-systest       # System integration tests (i.e. 'make test SUITE=systes
 make test-vector        # Vector search tests (i.e. 'make test SUITE=vector')
 make test-ldbc          # LDBC benchmark tests (i.e. 'make test SUITE=ldbc')
 make test-load          # Heavy load tests (i.e. 'make test SUITE=load')
-make test-integration   # Integration tests (i.e. 'make test TAGS=integration')
 make test-integration2  # Integration2 tests via dgraphtest (i.e. 'make test TAGS=integration2')
 make test-upgrade       # Upgrade tests (i.e. 'make test TAGS=upgrade')
 make test-fuzz          # Fuzz tests (i.e. 'make test FUZZ=1')
@@ -1301,7 +1303,7 @@ The following items from the original wishlist have been implemented:
   make test SUITE=systest
   make test FUZZ=1 PKG=dql
   make test TAGS=upgrade PKG=acl
-  make test TAGS=integration PKG=systest/plugin
+  make test-suite SUITE=systest PKG=systest/plugin
   ```
 
 ### Remaining Ideas

dgraphtest/local_cluster.go

@@ -1322,11 +1322,19 @@ func (c *LocalCluster) GeneratePlugins(raceEnabled bool) error {
 		if raceEnabled {
 			opts = append(opts, "-race")
 		}
-		opts = append(opts, "-buildmode=plugin", "-o", so, src)
-		os.Setenv("GOOS", "linux")
-		os.Setenv("GOARCH", "amd64")
+		opts = append(opts, "-buildmode=plugin")
+		if runtime.GOOS != "linux" {
+			// Use the BFD linker; the default gold linker is not shipped
+			// with most cross-compiler toolchains.
+			opts = append(opts, "-ldflags", "-extldflags -fuse-ld=bfd")
+		}
+		opts = append(opts, "-o", so, src)
 		cmd := exec.Command("go", opts...)
 		cmd.Dir = filepath.Dir(curr)
+		cmd.Env = append(os.Environ(), "GOOS=linux", "GOARCH="+runtime.GOARCH)
+		if runtime.GOOS != "linux" {
+			cmd.Env = append(cmd.Env, "CGO_ENABLED=1", "CC="+linuxCrossCC())
+		}
 		if out, err := cmd.CombinedOutput(); err != nil {
 			log.Printf("Error: %v\n", err)
 			log.Printf("Output: %v\n", string(out))
@@ -1347,6 +1355,22 @@ func (c *LocalCluster) GeneratePlugins(raceEnabled bool) error {
 	return nil
 }
 
+// linuxCrossCC returns the C cross-compiler for targeting Linux from the current host.
+// Respects the LINUX_CC environment variable if set.
+func linuxCrossCC() string {
+	if cc := os.Getenv("LINUX_CC"); cc != "" {
+		return cc
+	}
+	switch runtime.GOARCH {
+	case "arm64":
+		return "aarch64-unknown-linux-gnu-gcc"
+	case "amd64":
+		return "x86_64-unknown-linux-gnu-gcc"
+	default:
+		return "gcc"
+	}
+}
+
 func (c *LocalCluster) GetAlphaGrpcPublicPort(id int) (string, error) {
 	return publicPort(c.dcli, c.alphas[id], alphaGrpcPort)
 }

t/Makefile

@@ -19,7 +19,7 @@ endif
 all: test
 
 .PHONY: check
-check: check-go check-docker check-gotestsum check-ack
+check: check-go check-docker check-gotestsum check-ack check-cross-compiler
 	@if [ "$(GOOS)" = "linux" ]; then \
 		which protoc > /dev/null 2>&1 || (echo "Error: protoc is not installed or not in PATH" && exit 1); \
 	fi
@@ -44,6 +44,10 @@ check-gotestsum:
 check-ack:
 	@./scripts/check-ack.sh
 
+.PHONY: check-cross-compiler
+check-cross-compiler:
+	@./scripts/check-cross-compiler.sh
+
 .PHONY: check-protoc
 check-protoc:
 	@./scripts/check-protoc.sh

t/scripts/check-cross-compiler.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# shellcheck disable=SC2310
+set -euo pipefail
+
+# shellcheck source=checkhelper.sh
+source "$(dirname "${BASH_SOURCE[0]}")/checkhelper.sh"
+
+BREW_TAP="messense/macos-cross-toolchains"
+
+# Return the expected cross-compiler binary name for the host architecture.
+get_cross_compiler() {
+	if [[ -n ${LINUX_CC-} ]]; then
+		echo "${LINUX_CC}"
+		return
+	fi
+	local arch
+	arch="$(uname -m)"
+	case "${arch}" in
+	arm64 | aarch64)
+		echo "aarch64-unknown-linux-gnu-gcc"
+		;;
+	x86_64)
+		echo "x86_64-unknown-linux-gnu-gcc"
+		;;
+	*)
+		err "unsupported architecture: ${arch}"
+		return 1
+		;;
+	esac
+}
+
+# Return the Homebrew formula name for the cross-compiler.
+get_brew_formula() {
+	local arch
+	arch="$(uname -m)"
+	case "${arch}" in
+	arm64 | aarch64)
+		echo "aarch64-unknown-linux-gnu"
+		;;
+	x86_64)
+		echo "x86_64-unknown-linux-gnu"
+		;;
+	*)
+		err "unsupported architecture: ${arch}"
+		return 1
+		;;
+	esac
+}
+
+install_cross_compiler_macos() {
+	ensure_brew || exit 1
+	local formula
+	formula="$(get_brew_formula)"
+	brew tap "${BREW_TAP}"
+	brew install "${BREW_TAP}/${formula}"
+}
+
+main() {
+	# Cross-compiler is only needed on non-Linux systems
+	if [[ "$(get_os)" == "Linux" ]]; then
+		exit 0
+	fi
+
+	local cc
+	cc="$(get_cross_compiler)"
+
+	if command -v "${cc}" &>/dev/null; then
+		exit 0
+	fi
+
+	if [[ ${AUTO_INSTALL-} == "true" ]]; then
+		install_cross_compiler_macos
+		if command -v "${cc}" &>/dev/null; then
+			exit 0
+		else
+			err "cross-compiler check still failing after installation"
+			exit 1
+		fi
+	fi
+
+	echo ""
+	err "Linux cross-compiler is not installed (needed for Go plugin builds)"
+	echo ""
+	err "Required binary: ${cc}"
+	echo ""
+	err "Please install manually:"
+
+	case "$(get_os)" in
+	Darwin)
+		local formula
+		formula="$(get_brew_formula)"
+		err "    brew tap ${BREW_TAP}"
+		err "    brew install ${BREW_TAP}/${formula}"
+		echo ""
+		err 'Or set LINUX_CC to a custom cross-compiler (e.g. "zig cc -target ...")'
+		;;
+	*)
+		err "    (install a gcc cross-compiler targeting linux for your architecture)"
+		;;
+	esac
+
+	print_auto_install_hint
+	exit 1
+}
+
+main "$@"

t/t.go

@@ -422,8 +422,19 @@ func sanitizeFilename(pkg string) string {
 	return strings.ReplaceAll(pkg, "/", "_")
 }
 
+// gotestsumBin returns the absolute path to gotestsum inside $GOPATH/bin.
+// This avoids relying on $PATH, which may not include $GOPATH/bin on all machines
+// (the check-gotestsum.sh script validates at this same path).
+func gotestsumBin() string {
+	gopath := os.Getenv("GOPATH")
+	if gopath == "" {
+		gopath = filepath.Join(os.Getenv("HOME"), "go")
+	}
+	return filepath.Join(gopath, "bin", "gotestsum")
+}
+
 func runTestsFor(ctx context.Context, pkg, prefix string, xmlFile string) error {
-	args := []string{"gotestsum", "--junitfile", xmlFile, "--format", "standard-verbose", "--max-fails", "1", "--",
+	args := []string{gotestsumBin(), "--junitfile", xmlFile, "--format", "standard-verbose", "--max-fails", "1", "--",
 		"-v", "-failfast", "-tags=integration"}
 	switch {
 	case *testTimeout != "":

testutil/plugin.go

@@ -7,6 +7,7 @@ package testutil
 
 import (
 	"fmt"
+	"os"
 	"os/exec"
 	"path/filepath"
 	"runtime"
@@ -33,9 +34,19 @@ func GeneratePlugins(raceEnabled bool) {
 		if raceEnabled {
 			opts = append(opts, "-race")
 		}
-		opts = append(opts, "-buildmode=plugin", "-o", so, src)
+		opts = append(opts, "-buildmode=plugin")
+		if runtime.GOOS != "linux" {
+			// Use the BFD linker; the default gold linker is not shipped
+			// with most cross-compiler toolchains.
+			opts = append(opts, "-ldflags", "-extldflags -fuse-ld=bfd")
+		}
+		opts = append(opts, "-o", so, src)
 		cmd := exec.Command("go", opts...)
 		cmd.Dir = filepath.Dir(curr)
+		cmd.Env = append(os.Environ(), "GOOS=linux", "GOARCH="+runtime.GOARCH)
+		if runtime.GOOS != "linux" {
+			cmd.Env = append(cmd.Env, "CGO_ENABLED=1", "CC="+linuxCC())
+		}
 		if out, err := cmd.CombinedOutput(); err != nil {
 			fmt.Printf("Error: %v\n", err)
 			fmt.Printf("Output: %v\n", string(out))
@@ -51,3 +62,19 @@ func GeneratePlugins(raceEnabled bool) {
 
 	fmt.Printf("plugin build completed. Files are: %s\n", strings.Join(soFiles, ","))
 }
+
+// linuxCC returns the C cross-compiler for targeting Linux from the current host.
+// Respects the LINUX_CC environment variable if set.
+func linuxCC() string {
+	if cc := os.Getenv("LINUX_CC"); cc != "" {
+		return cc
+	}
+	switch runtime.GOARCH {
+	case "arm64":
+		return "aarch64-unknown-linux-gnu-gcc"
+	case "amd64":
+		return "x86_64-unknown-linux-gnu-gcc"
+	default:
+		return "gcc"
+	}
+}