Run Tests Skill

Use this skill when running or writing tests for this project.

Test Types

This project uses filename and function name conventions for test categorization:

• Unit tests: Files without “Integration” in test function names. No external dependencies, fast.
• Integration tests: *_integration_test.go files with “Integration” in function names. Requires database, slower.
• Benchmarks: Standard Go benchmarks (func Benchmark...). See internal/evaluator/evaluator_benchmark_test.go for an example.

When to Use Each

Unit Tests (task test:unit)

Use when:

• Doing TDD or tight iteration loops
• Testing pure functions or business logic
• No database or network calls needed
• Want fast feedback (runs in seconds)

Command:

task test:unit

What it runs:

go test ./... -run "Test[^I]"

This runs all tests that don’t have “Integration” in the name.

Example test files:

• internal/helpers/maths_test.go
• internal/candidate_tree/item_test.go
• internal/evaluator/trader_constraints_test.go

Integration Tests (task test:integration)

Use when:

• Testing database operations (models package)
• Testing full workflows that span multiple components
• Verifying migrations work correctly
• Before merging to main

Commands:

# Recommended for DevContainer (assuming database is running)
task test:integration

# Use if database needs to be started via Docker Compose
task test:integration:docker

What it does:

1. test:integration: Runs tests matching .*Integration.* pattern.
2. test:integration:docker: Starts Docker services (PostgreSQL) via compose:up, then runs integration tests.

What it runs:

go test ./... -run ".*Integration.*"

Example test files:

• internal/evaluator/find_best_build_integration_test.go
• internal/db/db_test.go

Requirements:

• Docker running
• .env file configured
• Database migrations applied

All Tests (task test)

Use when:

• Running CI/CD pipeline
• Final verification before pushing
• Want comprehensive coverage check

Command:

task test

What it runs:

go test ./...

Runs everything: unit, integration, and any other tests.

Test Workflow Recommendations

During Active Development (TDD)

# Run unit tests repeatedly after changes
task test:unit

Before Committing

# Run unit tests (fast check)
task test:unit

# If touching database code, run integration tests
task test:integration

Before Pushing/Merging

# Run everything
task test

# Run linter too
task lint

Running Specific Tests

Single test function:

go test ./internal/evaluator -run TestFindBestBuild

Single package:

go test ./internal/evaluator/...

Verbose output:

go test -v ./...

With coverage:

go test -cover ./...

Writing New Tests

When creating tests, follow the naming convention:

// Unit test (no external dependencies)
// File: internal/helpers/maths_unit_test.go
func TestCalculateAverage(t *testing.T) {
    // ...
}

// Integration test (uses database)
// File: internal/models/weapons_integration_test.go
func TestWeaponsIntegration(t *testing.T) {
    // ...
}

Rules:

• Unit tests: *_unit_test.go files, no database/network
• Integration tests: *_integration_test.go files, function name must include “Integration”
• Use table-driven tests for multiple cases
• Keep tests focused and independent

Troubleshooting

Integration tests fail with connection error:

• Ensure database is running.
• Check .env has correct connection details.
• In a devcontainer, the database is usually already running. Outside, you might need task compose:up.

Tests pass locally but fail in CI:

• Ensure you’re not relying on local state or files
• Check if tests have proper cleanup
• Verify tests are idempotent (can run multiple times)

Tests are slow:

• Ensure unit tests aren’t hitting the database
• Check if you can mock external dependencies
• Consider moving integration logic to integration test files