Testing Guidelines

QueryBox uses Go’s built-in testing framework for unit and integration tests.

Running Tests

Run All Tests

Execute all tests in the project:

go test ./...

Run Tests with Verbose Output

go test -v ./...

Run Specific Package Tests

# Test services
go test ./services/...

# Test plugins
go test ./plugins/...

# Test plugin SDK
go test ./pkg/plugin/...

Run Individual Test Functions

go test ./services -run TestConnectionService_Shutdown

Run Tests with Coverage

go test -cover ./...

# Generate detailed coverage report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Test Structure

QueryBox tests are organized alongside the source code:

├── services/
│   ├── connection.go
│   ├── connection_test.go          # Connection service tests
│   ├── credmanager/
│   │   └── credmanager_test.go     # Credential manager tests
│   └── pluginmgr/
│       ├── pluginmgr_test.go       # Cross-platform plugin tests
│       ├── pluginmgr_windows_test.go      # Windows-specific tests
│       └── pluginmgr_nonwindows_test.go   # Unix-specific tests
├── plugins/
│   ├── mysql/
│   │   └── mysql_test.go           # MySQL plugin tests
│   ├── postgresql/
│   │   └── postgresql_test.go      # PostgreSQL plugin tests
│   └── ...
└── pkg/
    ├── plugin/
    │   └── plugin_test.go          # Plugin SDK tests
    └── certs/
        └── certs_test.go           # Certificate utilities tests

Writing Tests

Basic Test Structure

Follow Go’s standard test conventions:

package services

import "testing"

func TestYourFunction(t *testing.T) {
    // Arrange
    input := "test input"
    expected := "expected output"
    
    // Act
    result := YourFunction(input)
    
    // Assert
    if result != expected {
        t.Errorf("YourFunction(%q) = %q; want %q", input, result, expected)
    }
}

Table-Driven Tests

Use table-driven tests for multiple test cases:

func TestFormatSQLValue(t *testing.T) {
    tests := []struct {
        name  string
        input interface{}
        want  string
    }{
        {"nil", nil, ""},
        {"string", "foo", "foo"},
        {"int", 42, "42"},
        {"bool", true, "true"},
        {"float", 3.14, "3.14"},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            got := FormatSQLValue(tt.input)
            if got != tt.want {
                t.Errorf("FormatSQLValue(%v) = %q; want %q", tt.input, got, tt.want)
            }
        })
    }
}

Testing with Context

Many QueryBox functions accept context.Context for cancellation:

func TestConnectionService_ListConnections(t *testing.T) {
    ctx := context.Background()
    svc := NewConnectionService()
    
    connections, err := svc.ListConnections(ctx)
    if err != nil {
        t.Fatalf("ListConnections failed: %v", err)
    }
    
    if connections == nil {
        t.Error("expected non-nil connections slice")
    }
}

Testing Cleanup and Shutdown

Test that resources are properly cleaned up:

func TestConnectionService_Shutdown(t *testing.T) {
    svc := NewConnectionService()
    if !svc.closeable() {
        t.Skip("database not available, skipping test")
    }

    // Perform initial operation
    _, err := svc.ListConnections(context.Background())
    if err != nil {
        t.Fatalf("initial ListConnections failed: %v", err)
    }

    // Shutdown and verify
    svc.Shutdown()
    if svc.closeable() {
        t.Fatal("service should not be closeable after Shutdown")
    }

    // Verify operations fail after shutdown
    _, err = svc.ListConnections(context.Background())
    if err == nil {
        t.Fatal("expected error after Shutdown, got nil")
    }
}

Mocking Dependencies

Use dependency injection for testability:

func TestDataDir(t *testing.T) {
    // Save original function
    orig := userConfigDirFunc
    defer func() { userConfigDirFunc = orig }()

    // Mock the function
    userConfigDirFunc = func() (string, error) {
        return "/home/alice/.config", nil
    }
    
    want := filepath.Join("/home/alice/.config", "querybox")
    if got := dataDir(); got != want {
        t.Errorf("dataDir() = %q; want %q", got, want)
    }
}

Plugin Testing

Testing Plugin Logic

Plugin tests typically focus on:

DSN/connection string parsing
Query execution logic
Result formatting
Error handling

Example from mysql_test.go:

func TestGetDatabaseFromConn(t *testing.T) {
    makeBlob := func(vals map[string]string) string {
        payload := struct {
            Form   string            `json:"form"`
            Values map[string]string `json:"values"`
        }{Form: "basic", Values: vals}
        b, _ := json.Marshal(payload)
        return string(b)
    }

    tests := []struct {
        name   string
        conn   map[string]string
        wantDB string
    }{
        {"empty", map[string]string{}, ""},
        {"dsn with name", map[string]string{"dsn": "user:pass@tcp(localhost:3306)/baz"}, "baz"},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            got := getDatabaseFromConn(tt.conn)
            if got != tt.wantDB {
                t.Fatalf("got %q, want %q", got, tt.wantDB)
            }
        })
    }
}

Integration Tests

Some plugin tests may require actual database connections. Use environment variables or skip conditions:

func TestPostgreSQLConnection(t *testing.T) {
    dsn := os.Getenv("POSTGRES_TEST_DSN")
    if dsn == "" {
        t.Skip("POSTGRES_TEST_DSN not set, skipping integration test")
    }
    
    // Test with real database
}

Platform-Specific Tests

Use build tags for platform-specific tests:

//go:build windows
// +build windows

package pluginmgr

import "testing"

func TestWindowsSpecific(t *testing.T) {
    // Windows-only test logic
}

//go:build !windows
// +build !windows

package pluginmgr

import "testing"

func TestUnixSpecific(t *testing.T) {
    // Unix-only test logic
}

Testing Best Practices

1. Use Descriptive Test Names

// Good
func TestConnectionService_Shutdown_ClosesDatabase(t *testing.T) {}

// Bad
func TestShutdown(t *testing.T) {}

2. Test Error Cases

func TestBuildDSN_InvalidBlob(t *testing.T) {
    conn := map[string]string{"credential_blob": "invalid json"}
    _, err := buildDSN(conn)
    if err == nil {
        t.Fatal("expected error for invalid credential_blob, got nil")
    }
}

3. Use t.Helper() for Test Utilities

func assertNoError(t *testing.T, err error) {
    t.Helper()
    if err != nil {
        t.Fatalf("unexpected error: %v", err)
    }
}

4. Clean Up Resources

func TestWithTempFile(t *testing.T) {
    f, err := os.CreateTemp("", "test")
    if err != nil {
        t.Fatal(err)
    }
    defer os.Remove(f.Name())
    defer f.Close()
    
    // Test logic
}

5. Skip Unavailable Tests

func TestRequiresDatabase(t *testing.T) {
    if !databaseAvailable() {
        t.Skip("database not available, skipping test")
    }
    // Test logic
}

Continuous Integration

QueryBox tests should pass in CI environments. Ensure your tests:

Don’t rely on external services (or skip gracefully)
Don’t require specific file paths (use t.TempDir())
Are platform-agnostic (or use build tags)
Complete within reasonable time limits

Test Coverage Goals

Aim for:

Core services: 80%+ coverage
Plugin SDK: 90%+ coverage
Individual plugins: 70%+ coverage
Critical paths: 100% coverage (authentication, credential storage, query execution)

Debugging Tests

Run with Race Detector

go test -race ./...

Run with Memory Sanitizer

go test -msan ./...

Enable Verbose Logging

func TestWithLogging(t *testing.T) {
    t.Logf("Starting test...")
    // Test logic
    t.Logf("Test completed")
}

Contributing

Architecture

Testing Guidelines

Running Tests

Run All Tests

Run Tests with Verbose Output

Run Specific Package Tests

Run Individual Test Functions

Run Tests with Coverage

Test Structure

Writing Tests

Basic Test Structure

Table-Driven Tests

Testing with Context

Testing Cleanup and Shutdown

Mocking Dependencies

Plugin Testing

Testing Plugin Logic

Integration Tests

Platform-Specific Tests

Testing Best Practices

1. Use Descriptive Test Names

2. Test Error Cases

3. Use t.Helper() for Test Utilities

4. Clean Up Resources

5. Skip Unavailable Tests

Continuous Integration

Test Coverage Goals

Debugging Tests

Run with Race Detector

Run with Memory Sanitizer

Enable Verbose Logging

Next Steps

Contributing Overview

Building

Build docs developers (and LLMs) love

Contributing

Architecture

Documentation Index

​Running Tests

​Run All Tests

​Run Tests with Verbose Output

​Run Specific Package Tests

​Run Individual Test Functions

​Run Tests with Coverage

​Test Structure

​Writing Tests

​Basic Test Structure

​Table-Driven Tests

​Testing with Context

​Testing Cleanup and Shutdown

​Mocking Dependencies

​Plugin Testing

​Testing Plugin Logic

​Integration Tests

​Platform-Specific Tests

​Testing Best Practices

​1. Use Descriptive Test Names

​2. Test Error Cases

​3. Use t.Helper() for Test Utilities

​4. Clean Up Resources

​5. Skip Unavailable Tests

​Continuous Integration

​Test Coverage Goals

​Debugging Tests

​Run with Race Detector

​Run with Memory Sanitizer

​Enable Verbose Logging

​Next Steps

Contributing Overview

Building

Build docs developers (and LLMs) love

Running Tests

Run All Tests

Run Tests with Verbose Output

Run Specific Package Tests

Run Individual Test Functions

Run Tests with Coverage

Test Structure

Writing Tests

Basic Test Structure

Table-Driven Tests

Testing with Context

Testing Cleanup and Shutdown

Mocking Dependencies

Plugin Testing

Testing Plugin Logic

Integration Tests

Platform-Specific Tests

Testing Best Practices

1. Use Descriptive Test Names

2. Test Error Cases

3. Use t.Helper() for Test Utilities

4. Clean Up Resources

5. Skip Unavailable Tests

Continuous Integration

Test Coverage Goals

Debugging Tests

Run with Race Detector

Run with Memory Sanitizer

Enable Verbose Logging

Next Steps