Merge pull request #71 from neo4j/mjfwebb/integration-tests

Add integration tests

Author: mjfwebb

go.mod

@@ -1,21 +1,73 @@
 module github.com/neo4j/mcp
 
-go 1.25.1
+go 1.25.3
 
 require (
-	github.com/mark3labs/mcp-go v0.41.1
+	github.com/google/uuid v1.6.0
+	github.com/mark3labs/mcp-go v0.42.0
 	github.com/neo4j/neo4j-go-driver/v5 v5.28.4
+	github.com/testcontainers/testcontainers-go v0.39.0
 	go.uber.org/mock v0.6.0
 )
 
 require (
+	dario.cat/mergo v1.0.2 // indirect
+	github.com/Azure/go-ansiterm v0.0.0-20250102033503-faa5f7b0171c // indirect
+	github.com/Microsoft/go-winio v0.6.2 // indirect
 	github.com/bahlo/generic-list-go v0.2.0 // indirect
 	github.com/buger/jsonparser v1.1.1 // indirect
-	github.com/google/uuid v1.6.0 // indirect
+	github.com/cenkalti/backoff/v4 v4.3.0 // indirect
+	github.com/containerd/errdefs v1.0.0 // indirect
+	github.com/containerd/errdefs/pkg v0.3.0 // indirect
+	github.com/containerd/log v0.1.0 // indirect
+	github.com/containerd/platforms v0.2.1 // indirect
+	github.com/cpuguy83/dockercfg v0.3.2 // indirect
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/distribution/reference v0.6.0 // indirect
+	github.com/docker/docker v28.5.1+incompatible // indirect
+	github.com/docker/go-connections v0.6.0 // indirect
+	github.com/docker/go-units v0.5.0 // indirect
+	github.com/ebitengine/purego v0.9.0 // indirect
+	github.com/felixge/httpsnoop v1.0.4 // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/go-ole/go-ole v1.3.0 // indirect
 	github.com/invopop/jsonschema v0.13.0 // indirect
+	github.com/klauspost/compress v1.18.1 // indirect
+	github.com/lufia/plan9stats v0.0.0-20251013123823-9fd1530e3ec3 // indirect
+	github.com/magiconair/properties v1.8.10 // indirect
 	github.com/mailru/easyjson v0.9.1 // indirect
+	github.com/moby/docker-image-spec v1.3.1 // indirect
+	github.com/moby/go-archive v0.1.0 // indirect
+	github.com/moby/patternmatcher v0.6.0 // indirect
+	github.com/moby/sys/sequential v0.6.0 // indirect
+	github.com/moby/sys/user v0.4.0 // indirect
+	github.com/moby/sys/userns v0.1.0 // indirect
+	github.com/moby/term v0.5.2 // indirect
+	github.com/morikuni/aec v1.0.0 // indirect
+	github.com/opencontainers/go-digest v1.0.0 // indirect
+	github.com/opencontainers/image-spec v1.1.1 // indirect
+	github.com/pkg/errors v0.9.1 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 // indirect
+	github.com/shirou/gopsutil/v4 v4.25.9 // indirect
+	github.com/sirupsen/logrus v1.9.3 // indirect
 	github.com/spf13/cast v1.10.0 // indirect
+	github.com/stretchr/testify v1.11.1 // indirect
+	github.com/tklauser/go-sysconf v0.3.15 // indirect
+	github.com/tklauser/numcpus v0.10.0 // indirect
 	github.com/wk8/go-ordered-map/v2 v2.1.8 // indirect
 	github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
+	github.com/yusufpapurcu/wmi v1.2.4 // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.63.0 // indirect
+	go.opentelemetry.io/otel v1.38.0 // indirect
+	go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.38.0 // indirect
+	go.opentelemetry.io/otel/metric v1.38.0 // indirect
+	go.opentelemetry.io/otel/trace v1.38.0 // indirect
+	go.opentelemetry.io/proto/otlp v1.8.0 // indirect
+	golang.org/x/crypto v0.43.0 // indirect
+	golang.org/x/sys v0.37.0 // indirect
+	google.golang.org/protobuf v1.36.10 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -40,10 +40,10 @@ func (c *Config) Validate() error {
 // LoadConfig loads configuration from environment variables with defaults
 func LoadConfig() (*Config, error) {
 	cfg := &Config{
-		URI:      getEnvWithDefault("NEO4J_URI", "bolt://localhost:7687"),
-		Username: getEnvWithDefault("NEO4J_USERNAME", "neo4j"),
-		Password: getEnvWithDefault("NEO4J_PASSWORD", "password"),
-		Database: getEnvWithDefault("NEO4J_DATABASE", "neo4j"),
+		URI:      GetEnvWithDefault("NEO4J_URI", "bolt://localhost:7687"),
+		Username: GetEnvWithDefault("NEO4J_USERNAME", "neo4j"),
+		Password: GetEnvWithDefault("NEO4J_PASSWORD", "password"),
+		Database: GetEnvWithDefault("NEO4J_DATABASE", "neo4j"),
 	}
 
 	if err := cfg.Validate(); err != nil {
@@ -53,7 +53,7 @@ func LoadConfig() (*Config, error) {
 	return cfg, nil
 }
 
-func getEnvWithDefault(key, defaultValue string) string {
+func GetEnvWithDefault(key, defaultValue string) string {
 	if value := os.Getenv(key); value != "" {
 		return value
 	}

internal/config/config.go

@@ -0,0 +1,85 @@
+# Integration Tests
+
+Integration tests for the Neo4j MCP server using a shared Neo4j container (includes APOC + GDS).
+
+## Quick Start
+
+```go
+func TestMCPIntegration_MyFeature(t *testing.T) {
+    t.Parallel()
+    tc := helpers.NewTestContext(t)
+
+    // Seed test data (automatically isolated with unique labels and cleaned up)
+    personLabel, err := tc.SeedNode("Person", map[string]any{"name": "Alice"})
+    if err != nil {
+        t.Fatalf("failed to seed data: %v", err)
+    }
+
+    // Call tool
+    handler := cypher.ReadCypherHandler(tc.Deps)
+    res := tc.CallTool(handler, map[string]any{
+        "query":  "MATCH (p:" + personLabel + " {name: $name}) RETURN p",
+        "params": map[string]any{"name": "Alice"},
+    })
+
+    // Parse and assert
+    var records []map[string]any
+    tc.ParseJSONResponse(res, &records)
+
+    person := records[0]["p"].(map[string]any)
+    helpers.AssertNodeProperties(t, person, map[string]any{"name": "Alice"})
+    helpers.AssertNodeHasLabel(t, person, personLabel)
+}
+```
+
+## Key Helpers
+
+**TestContext:**
+
+- `helpers.NewTestContext(t)` - Auto-isolation + cleanup
+- `SeedNode(label, props)` - Create test data with unique label, returns `(UniqueLabel, error)`
+- `GetUniqueLabel(label)` - Get a unique label for creating nodes manually
+- `CallTool(handler, args)` - Invoke MCP tool
+- `ParseJSONResponse(res, &v)` - Parse response
+- `VerifyNodeInDB(label, props)` - Check DB state
+
+**Assertions:**
+
+- `helpers.AssertNodeProperties(t, node, props)`
+- `helpers.AssertNodeHasLabel(t, node, label)`
+- `helpers.AssertSchemaHasNodeType(t, schema, label, props)`
+
+## Running Tests
+
+```bash
+go test -tags=integration ./test/integration/... -v              # All tests
+go test -tags=integration ./test/integration/... -run MyFeature  # Specific test
+go test -tags=integration ./test/integration/... -race           # With race detection
+```
+
+## Configuration
+
+The integration tests use environment variables to configure the Neo4j test container. All variables have sensible defaults:
+
+| Environment Variable | Default                         | Description               |
+| -------------------- | ------------------------------- | ------------------------- |
+| `NEO4J_IMAGE`        | `neo4j:5.24.2-community`        | Neo4j Docker image to use |
+| `NEO4J_USERNAME`     | `neo4j`                         | Database username         |
+| `NEO4J_PASSWORD`     | `password`                      | Database password         |
+| `NEO4JLABS_PLUGINS`  | `["apoc","graph-data-science"]` | Plugins to install        |
+
+**Example with custom configuration:**
+
+```bash
+NEO4J_IMAGE=neo4j:5.25.0-enterprise \
+NEO4J_USERNAME=admin \
+NEO4J_PASSWORD=secret \
+go test -tags=integration ./test/integration/... -v
+```
+
+## Important
+
+- Always use `t.Parallel()` for parallel execution
+- Always use the `UniqueLabel` returned by `SeedNode()` or `GetUniqueLabel()` in your queries for isolation
+- Test data is automatically tagged with unique labels and cleaned up after each test
+- Import the helpers package: `"github.com/neo4j/mcp/test/integration/helpers"`

test/integration/README.md

@@ -0,0 +1,53 @@
+//go:build integration
+
+package integration
+
+import (
+	"testing"
+
+	"github.com/neo4j/mcp/internal/tools/cypher"
+	"github.com/neo4j/mcp/test/integration/helpers"
+)
+
+func TestMCPIntegration_GetSchema(t *testing.T) {
+	t.Parallel()
+
+	tc := helpers.NewTestContext(t)
+
+	// Use TestID as identifier to create unique labels
+	personLabel, err := tc.SeedNode("Person", map[string]any{"name": "Alice", "age": 30})
+	if err != nil {
+		t.Fatalf("failed to seed Person node: %v", err)
+	}
+	companyLabel, err := tc.SeedNode("Company", map[string]any{"name": "Neo4j", "founded": 2007})
+	if err != nil {
+		t.Fatalf("failed to seed Company node: %v", err)
+	}
+
+	getSchema := cypher.GetSchemaHandler(tc.Deps)
+	res := tc.CallTool(getSchema, nil)
+
+	var schemaArray []map[string]any
+	tc.ParseJSONResponse(res, &schemaArray)
+
+	if len(schemaArray) == 0 {
+		t.Fatal("expected schema to contain at least one entry")
+	}
+
+	schemaMap := make(map[string]map[string]any)
+	for _, entry := range schemaArray {
+		key, ok := entry["key"].(string)
+		if !ok {
+			continue
+		}
+		value, ok := entry["value"].(map[string]any)
+		if !ok {
+			continue
+		}
+		schemaMap[key] = value
+	}
+
+	// Check for the unique labels created
+	helpers.AssertSchemaHasNodeType(t, schemaMap, personLabel, []string{"name", "age"})
+	helpers.AssertSchemaHasNodeType(t, schemaMap, companyLabel, []string{"name", "founded"})
+}