How to Run Tests for the Caveman Engine: A Complete Guide

Run go test ./engine/... from the repository root to execute the full test suite covering compressors, CCR storage, and detection logic, or use make product-test PRODUCT=engine for the release build configuration.

The Caveman Engine is a pure-Go compression library developed in the JuliusBrussee/caveman repository. The project maintains comprehensive unit and integration tests under the engine/ directory to validate its 15 default compressor implementations, SQLite-backed CCR storage layer, and public API methods. Understanding how to run tests for the Caveman engine ensures your modifications to detection logic or compression algorithms maintain backward compatibility.

Prerequisites for Running Caveman Engine Tests

Before executing any test commands, verify your environment meets the engine's build requirements.

Go Version Requirements

The Caveman engine requires Go 1.26.5 or later, as specified in the go.mod file. Verify your installation:

go version

If the version is below 1.26.5, upgrade Go to prevent compatibility issues with the engine's module dependencies.

Dependency Resolution

Resolve all Go modules before testing:

go mod tidy

This command downloads the dependencies required by engine/engine.go and its sub-packages, including the SQLite driver for CCR storage and pixel processing libraries.

Running the Full Test Suite

The engine uses Go's standard testing framework, discovering all files matching *_test.go patterns under the engine/ tree.

Standard Go Test Command

Execute every test across all engine sub-packages:

go test ./engine/...

This command runs tests in engine/compressors/json_test.go, engine/ccr/store_test.go, engine/detect_test.go, and all other test files, validating the Compress(), Retrieve(), Detect(), and Stats() API methods defined in engine/engine.go.

Make-Based Testing (Alternative)

If the repository includes the Makefile, use the canonical release configuration:

make product-test PRODUCT=engine

This wrapper sets environment variables and build flags identical to the release pipeline before invoking go test ./engine/....

Testing Specific Components

Isolate testing to individual sub-packages when iterating on specific features.

Compressor Tests

Run tests for all compression algorithms:

go test ./engine/compressors/...

Test a specific compressor implementation, such as the JSON compressor in engine/compressors/json.go or the TOON compressor in engine/compressors/toon.go:

go test ./engine/compressors/... -run TestJSON -v

CCR Storage Tests

Validate the SQLite-backed Caveman Compression Recovery (CCR) storage layer:

go test ./engine/ccr/... -v

This exercises the storage logic in engine/ccr/store.go, ensuring reliable persistence of compressed artifacts.

Detection and Pixel Tests

Test content detection and pixel transformation logic:

go test ./engine/detect_test.go -v
go test ./engine/pixel/transform_openai_test.go -v

These commands validate the token-budgeting logic in engine/contextwindow/contextwindow.go and image processing pipelines.

Advanced Test Configuration

Refine test execution using standard Go test flags and environment variables.

Filtering Tests with Regular Expressions

Run only tests matching a specific pattern:

go test ./engine/... -run TestDetect -v

The -run flag accepts regular expressions, allowing you to target specific functions like TestDetect or TestTransform.

Race Detection and Coverage

Enable the data-race detector for concurrent compressor validation:

go test -race ./engine/...

Generate coverage reports to identify untested code paths:

go test -cover ./engine/...

Combine flags for comprehensive validation:

go test ./engine/... -v -race -cover

Repeat tests to catch flaky behavior using the -count flag:

go test ./engine/... -count=10

Environment Variables for Test Configuration

Override default limits during testing:

CAVEMAN_INPUT_LIMIT=10485760 go test ./engine/detect_test.go -v
CAVEMAN_CCR_MAX_BYTES=104857600 go test ./engine/ccr/... -v

These variables configure the input size limit and CCR memory cap respectively.

Installer Tests (Node.js)

Validate the Node.js-based installer separately from the Go engine:

npm run test

This command, defined in package.json, executes the installer tests located in tests/installer/*.test.mjs, verifying CLI distribution and installation workflows.

Summary

• Run the full suite with go test ./engine/... or make product-test PRODUCT=engine for release parity.
• Test individual components by specifying sub-package paths like ./engine/compressors/... or ./engine/ccr/.
• Enable advanced diagnostics using -race for concurrency checks and -cover for coverage analysis.
• Configure test behavior through environment variables CAVEMAN_INPUT_LIMIT and CAVEMAN_CCR_MAX_BYTES.
• Validate installers separately using npm run test for the Node.js test suite.

Frequently Asked Questions

What Go version is required to run Caveman engine tests?

The Caveman engine requires Go 1.26.5 or later, as declared in the go.mod file. Running tests with earlier versions may result in dependency resolution failures or compilation errors in engine/engine.go.

How do I run only the compressor tests?

Execute go test ./engine/compressors/... to run all compressor tests, or narrow the scope further with go test ./engine/compressors/json_test.go -v for single-file testing. The -run flag allows filtering by function name, such as -run TestJSON.

Can I enable race detection when testing the Caveman engine?

Yes. Append the -race flag to any test command: go test -race ./engine/.... This enables Go's data-race detector, which is essential for validating concurrent operations in the compressor implementations and CCR storage layer.

How do I generate a test coverage report for the engine?

Add the -cover flag to your test command: go test -cover ./engine/.... For detailed coverage profiles showing which lines in engine/ccr/store.go or engine/compressors/toon.go are untested, use -coverprofile=coverage.out and analyze the output with go tool cover.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}