starlog/docs/DEVELOPMENT.md

Development Guide

This file defines the local test matrix and troubleshooting notes for starlog.

Local Test Matrix

Run these commands from repository root:

go test ./...
go test -race ./...
go test . -run '^$' -bench Benchmark -benchmem -benchtime=100x
go test . -run '^$' -fuzz=FuzzTextAndJSONFormatter -fuzztime=2s
go test . -run '^$' -fuzz=FuzzKeywordHighlight -fuzztime=2s

One-Command Local Check

Use the helper script:

powershell -ExecutionPolicy Bypass -File scripts/test-local.ps1

The script runs:

1. Unit tests.
2. Race tests (with a precheck).
3. Benchmark smoke.
4. Fuzz smoke.

Race Troubleshooting (Windows)

If this command fails:

go test -race fmt

with:

runtime/race: package testmain: cannot find package

the problem is the local Go toolchain/runtime environment, not starlog code.

Recommended steps:

1. Verify toolchain:

   where.exe go
   go version
   go env GOROOT GOPATH GOOS GOARCH CGO_ENABLED
   

2. Clear caches:

   go clean -cache -testcache -fuzzcache
   

3. Reinstall an official Go distribution for your platform.
4. Re-run:

   go test -race fmt
   

CI Mapping

The same matrix is mirrored in:

• .github/workflows/quality.yml

Linux executes -race and fuzz smoke; Windows keeps unit test coverage.