# Development Guide

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

## Local Test Matrix

Run these commands from repository root:

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

```powershell
go test -race fmt
```

with:

```text
runtime/race: package testmain: cannot find package
```

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

Recommended steps:

1. Verify toolchain:
   ```powershell
   where.exe go
   go version
   go env GOROOT GOPATH GOOS GOARCH CGO_ENABLED
   ```
2. Clear caches:
   ```powershell
   go clean -cache -testcache -fuzzcache
   ```
3. Reinstall an official Go distribution for your platform.
4. Re-run:
   ```powershell
   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.