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

> Easily run tests for the Caveman engine with simple commands. This guide details how to execute the full test suite covering compressors, storage, and detection logic.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: how-to-guide
- Published: 2026-08-22

---

**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:

```bash
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:

```bash
go mod tidy

```

This command downloads the dependencies required by [`engine/engine.go`](https://github.com/JuliusBrussee/caveman/blob/main/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:

```bash
go test ./engine/...

```

This command runs tests in [`engine/compressors/json_test.go`](https://github.com/JuliusBrussee/caveman/blob/main/engine/compressors/json_test.go), [`engine/ccr/store_test.go`](https://github.com/JuliusBrussee/caveman/blob/main/engine/ccr/store_test.go), [`engine/detect_test.go`](https://github.com/JuliusBrussee/caveman/blob/main/engine/detect_test.go), and all other test files, validating the `Compress()`, `Retrieve()`, `Detect()`, and `Stats()` API methods defined in [`engine/engine.go`](https://github.com/JuliusBrussee/caveman/blob/main/engine/engine.go).

### Make-Based Testing (Alternative)

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

```bash
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:

```bash
go test ./engine/compressors/...

```

Test a specific compressor implementation, such as the JSON compressor in [`engine/compressors/json.go`](https://github.com/JuliusBrussee/caveman/blob/main/engine/compressors/json.go) or the TOON compressor in [`engine/compressors/toon.go`](https://github.com/JuliusBrussee/caveman/blob/main/engine/compressors/toon.go):

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

```

### CCR Storage Tests

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

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

```

This exercises the storage logic in [`engine/ccr/store.go`](https://github.com/JuliusBrussee/caveman/blob/main/engine/ccr/store.go), ensuring reliable persistence of compressed artifacts.

### Detection and Pixel Tests

Test content detection and pixel transformation logic:

```bash
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`](https://github.com/JuliusBrussee/caveman/blob/main/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:

```bash
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:

```bash
go test -race ./engine/...

```

Generate coverage reports to identify untested code paths:

```bash
go test -cover ./engine/...

```

Combine flags for comprehensive validation:

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

```

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

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

```

### Environment Variables for Test Configuration

Override default limits during testing:

```bash
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:

```bash
npm run test

```

This command, defined in [`package.json`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/engine/ccr/store.go) or [`engine/compressors/toon.go`](https://github.com/JuliusBrussee/caveman/blob/main/engine/compressors/toon.go) are untested, use `-coverprofile=coverage.out` and analyze the output with `go tool cover`.