Testing

Testing Guide#

Testing procedures and integration test setup.

Running Tests#

Basic Tests#

# Run all tests with race detector
go test -race ./...

# Run specific package
go test -race ./pkg/cache/...

# Run specific test
go test -race -run TestCacheFetch ./pkg/cache/...

Integration Tests#

Integration tests are disabled by default. Enable using helper commands:

# Start dependencies
nix run .#deps

# Enable all integration tests
eval "$(enable-integration-tests)"

# Run tests
go test -race ./...

# Disable when done
eval "$(disable-integration-tests)"

Available helpers:

  • enable-s3-tests - S3/Garage tests
  • enable-postgres-tests - PostgreSQL tests
  • enable-mysql-tests - MySQL tests
  • enable-redis-tests - Redis lock tests
  • enable-integration-tests - All integration tests
  • disable-integration-tests - Disable all

End-to-end tests#

End-to-end scenarios (serve, CDC lifecycle, in-flight staging contention, and the Helm deployment permutations) run through the unified harness, against either a local run.py deployment or a Kind/Helm cluster:

# List scenarios.
nix run .#e2e -- --list

# Local mode (auto-manages `nix run .#deps` backends).
task test:e2e -- --mode local --scenario cdc-lifecycle

# Kubernetes mode (Kind + Helm).
nix run .#e2e -- --mode kubernetes --scenario single-s3-postgres

The harness is manual / opt-in and is not part of nix flake check. See nix/e2e-tests/README.md for the full scenario catalog and modes.

CI/CD Testing#

In Nix builds and CI, all integration tests run automatically:

nix flake check

This automatically:

  1. Starts all dependencies (Garage, PostgreSQL, MariaDB, Redis)
  2. Runs all tests including integration tests
  3. Stops all services

Test Structure#

Tests use testify for assertions:

import (
    "testing"
    "github.com/stretchr/testify/assert"
    "github.com/stretchr/testify/require"
)

func TestExample(t *testing.T) {
    result := SomeFunction()
    assert.Equal(t, expected, result)
}

Test Packages#

Tests use _test package suffix (testpackage linter):

package cache_test  // Not package cache

import (
    "testing"
    "github.com/kalbasit/ncps/pkg/cache"
)

Parallel Tests#

Use t.Parallel() where possible:

func TestParallel(t *testing.T) {
    t.Parallel()
    // Test code...
}

Linting#

# Run all linters
golangci-lint run

# Auto-fix issues
golangci-lint run --fix

# Check specific file
golangci-lint run path/to/file.go

Key linters:

  • err113 - Error handling
  • exhaustive - Switch exhaustiveness
  • gosec - Security
  • paralleltest - Parallel testing
  • testpackage - Test package naming

Code Formatting#

# Format all code (Go, Nix, SQL, etc.)
nix fmt

# Format SQL specifically
sqlfluff format migrations/

SQL Linting#

# Lint SQL files
sqlfluff lint migrations/

Coverage#

# Run with coverage
go test -race -coverprofile=coverage.out ./...

# View coverage
go tool cover -html=coverage.out

Related Documentation#