feat: introduce e2e cypher validation integration test suite

Makefile

@@ -1,20 +1,97 @@
 THIS_FILE := $(lastword $(MAKEFILE_LIST))
 
-GO_CMD?=go
-CGO_ENABLED?=0
+# Go configuration
+GO_CMD ?= go
+CGO_ENABLED ?= 0
 
-MAIN_PACKAGES=$$($(GO_CMD) list ./...)
+# Main packages to test/build
+MAIN_PACKAGES := $(shell $(GO_CMD) list ./...)
 
-default: format test
-all: generate format test
+# Default target
+default: help
+all: generate format tidy test
 
-generate:
-	@$(GO_CMD) generate ./...
+# Build targets
+build:
+	@echo "Building all packages..."
+	@$(GO_CMD) build ./...
+
+# Dependency management
+deps:
+	@echo "Downloading dependencies..."
+	@$(GO_CMD) mod download
+
+tidy:
+	@echo "Tidying go modules..."
+	@$(GO_CMD) mod tidy
+
+# Code quality
+lint:
+	@echo "Running linter..."
+	@$(GO_CMD) vet ./...
 
 format:
+	@echo "Formatting code..."
 	@find ./ -name '*.go' -print0 | xargs -P 12 -0 -I '{}' goimports -w '{}'
 
+# Test targets
 test:
-	@for pkg in $(MAIN_PACKAGES) ; do \
-		$(GO_CMD) test -cover $$pkg -parallel=20 ; \
-	done
+	@echo "Running tests..."
+	@$(GO_CMD) test -race -cover -count=1 -parallel=10 $(MAIN_PACKAGES)
+
+test_neo4j:
+	@echo "Running Neo4j integration tests..."
+	@$(GO_CMD) test -tags neo4j_integration -race -cover -count=1 -parallel=1 $(MAIN_PACKAGES)
+
+test_pg:
+	@echo "Running PostgreSQL integration tests..."
+	@$(GO_CMD) test -tags pg_integration -race -cover -count=1 -parallel=1 $(MAIN_PACKAGES)
+
+test_update:
+	@echo "Updating test cases..."
+	@CYSQL_UPDATE_CASES=true $(GO_CMD) test -parallel=10 $(MAIN_PACKAGES) >>/dev/null 2>&1|| true
+
+	@cp -fv cypher/analyzer/updated_cases/* cypher/test/cases
+	@rm -rf cypher/analyzer/updated_cases/
+	@cp -fv cypher/models/pgsql/test/updated_cases/* cypher/models/pgsql/test/translation_cases
+	@rm -rf cypher/models/pgsql/test/updated_cases
+
+# Utility targets
+generate:
+	@echo "Running code generation..."
+	@$(GO_CMD) generate ./...
+
+clean:
+	@echo "Cleaning build artifacts..."
+	@$(GO_CMD) clean ./...
+
+	@rm -rf cypher/analyzer/updated_cases/
+	@rm -rf cypher/models/pgsql/test/updated_cases
+
+help:
+	@echo "Available targets:"
+	@echo "  default     - Show this help message"
+	@echo "  all         - Runs all prep steps for prepare a changeset for review"
+	@echo ""
+	@echo "Build:"
+	@echo "  build       - Build all packages"
+	@echo ""
+	@echo "Dependencies:"
+	@echo "  deps        - Download dependencies"
+	@echo "  tidy        - Tidy go modules"
+	@echo ""
+	@echo "Code Quality:"
+	@echo "  lint        - Run go vet"
+	@echo "  format      - Format all Go files"
+	@echo "  generate    - Run code generation"
+	@echo ""
+	@echo "Testing:"
+	@echo "  test        - Run all unit tests with coverage"
+	@echo "  test_bench  - Run benchmark test"
+	@echo "  test_neo4j  - Run Neo4j integration tests"
+	@echo "  test_pg     - Run PostgreSQL integration tests"
+	@echo "  test_update - Update test cases"
+	@echo ""
+	@echo "Utility:"
+	@echo "  clean       - Clean build artifacts"
+	@echo "  help        - Show this help message"

README.md

@@ -33,3 +33,46 @@ development processes.
 ```bash
 make
 ```
+
+#### Integration Tests
+
+Integration tests are excluded from the default `make` target and require a running database instance. They are
+selected via Go build tags and configured through environment variables.
+
+##### PostgreSQL Integration Tests
+
+The following tests require a live PostgreSQL instance:
+
+- `cypher/models/pgsql/test/translation_integration_test.go`
+- `cypher/models/pgsql/test/semantic_integration_test.go`
+
+Set the `PG_CONNECTION_STRING` environment variable to a valid PostgreSQL connection string (e.g. `user=postgres dbname=bhe password=bhe4eva host=localhost`), then run:
+
+```bash
+PG_CONNECTION_STRING="<connection-string>" make test_pg
+```
+
+To run a specific test directly:
+
+```bash
+PG_CONNECTION_STRING="<connection-string>" go test -tags pg_integration ./cypher/models/pgsql/test/...
+```
+
+##### Neo4j Integration Tests
+
+The following test requires a live Neo4j instance:
+
+- `drivers/neo4j/batch_integration_test.go`
+
+Set the `NEO4J_CONNECTION_STRING` environment variable to a valid Neo4j connection string (e.g.
+`neo4j://user:password@host:port`), then run:
+
+```bash
+NEO4J_CONNECTION_STRING="<connection-string>" make test_neo4j
+```
+
+To run the batch integration test directly:
+
+```bash
+NEO4J_CONNECTION_STRING="<connection-string>" go test -tags neo4j_integration ./drivers/neo4j/...
+```

cardinality/hyperloglog32_test.go

@@ -6,37 +6,6 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
-// This is a test that serves as a documented example of how HLL works. This test was designed to use the 14 register
-// HLL implementation.
-//
-// For more information on HLL see: https://en.wikipedia.org/wiki/HyperLogLog
-func TestHyperLogLog32(t *testing.T) {
-	const cardinalityMax = 10_000_000
-
-	sketch := NewHyperLogLog32()
-
-	for i := uint32(0); i < cardinalityMax; i++ {
-		sketch.Add(i)
-	}
-
-	var (
-		estimatedCardinality = sketch.Cardinality()
-		deviation            = 100 - cardinalityMax/float64(estimatedCardinality)*100
-	)
-
-	// We expect the HLL sketch to have a cardinality that does not deviate more than 0.5% from reality
-	require.Truef(t, deviation < 0.5, "Expected a cardinality less than 0.5%% but got %.2f%%", deviation)
-
-	for i := 0; i < 100; i++ {
-		previous := sketch.Cardinality()
-
-		sketch.Add(0)
-		after := sketch.Cardinality()
-
-		require.Equal(t, previous, after, "Expected cardinality to remain the same after encoding the same ID twice")
-	}
-}
-
 func TestHyperLogLog32_Add(t *testing.T) {
 	sketch := NewHyperLogLog32()
 

cardinality/hyperloglog64_test.go

@@ -6,37 +6,6 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
-// This is a test that serves as a documented example of how HLL works. This test was designed to use the 14 register
-// HLL implementation.
-//
-// For more information on HLL see: https://en.wikipedia.org/wiki/HyperLogLog
-func TestHyperLogLog64(t *testing.T) {
-	const cardinalityMax = 10_000_000
-
-	sketch := NewHyperLogLog64()
-
-	for i := uint64(0); i < cardinalityMax; i++ {
-		sketch.Add(i)
-	}
-
-	var (
-		estimatedCardinality = sketch.Cardinality()
-		deviation            = 100 - cardinalityMax/float64(estimatedCardinality)*100
-	)
-
-	// We expect the HLL sketch to have a cardinality that does not deviate more than 0.66% from reality
-	require.Truef(t, deviation < 0.66, "Expected a cardinality less than 0.66%% but got %.2f%%", deviation)
-
-	for i := 0; i < 100; i++ {
-		previous := sketch.Cardinality()
-
-		sketch.Add(0)
-		after := sketch.Cardinality()
-
-		require.Equal(t, previous, after, "Expected cardinality to remain the same after encoding the same ID twice")
-	}
-}
-
 func TestHyperLogLog64_Add(t *testing.T) {
 	sketch := NewHyperLogLog64()