docs: update test.md for unified test runner

Author: alexluong

contributing/test.md

@@ -1,75 +1,94 @@
 # Test
 
-## Commands
+## Test Runner
 
-### Using go test
+The test suite uses `scripts/test.sh` as the unified test runner. It provides consistent behavior across different commands with support for [gotestsum](https://github.com/gotestyourself/gotestsum) (recommended) or plain `go test`.
 
-1. Run all tests
+### Runner Behavior
 
-```sh
-go test ./...
-```
+By default, the script auto-detects the available runner:
 
-2. Run unit tests
+1. If `RUNNER` env var is set, use that explicitly
+2. If `gotestsum` is installed, use it (with automatic retries for flaky tests)
+3. Otherwise, fall back to `go test`
+
+To install gotestsum (recommended):
 
 ```sh
-go test ./... -short
+go install gotest.tools/gotestsum@latest
 ```
 
-3. Run integration tests
+To force a specific runner:
 
 ```sh
-go test ./... -run "Integration"
+RUNNER=go ./scripts/test.sh test    # Force go test
+RUNNER=gotestsum ./scripts/test.sh test  # Force gotestsum
 ```
 
-### Using Make (requires gotestsum)
+## Commands
 
-The Makefile uses [gotestsum](https://github.com/gotestyourself/gotestsum) which provides better output formatting and automatic retries for flaky tests.
+### Using the Test Script
 
 ```sh
-# Install gotestsum first
-go install gotest.tools/gotestsum@latest
-```
+# Run all tests (unit + integration)
+./scripts/test.sh test
 
-1. Run all tests
+# Run unit tests only (uses -short flag)
+./scripts/test.sh unit
 
-```sh
-make test
+# Run end-to-end tests
+./scripts/test.sh e2e
+
+# Run full suite with all backend combinations
+./scripts/test.sh full
 ```
 
-2. Run unit tests
+### Using Make
+
+The Makefile targets delegate to `scripts/test.sh`:
 
 ```sh
-make test/unit
+make test        # ./scripts/test.sh test
+make test/unit   # ./scripts/test.sh unit
+make test/e2e    # ./scripts/test.sh e2e
+make test/full   # ./scripts/test.sh full
 ```
 
-3. Run integration tests
+### Using go test Directly
 
 ```sh
-make test/integration
+go test ./...           # All tests
+go test ./... -short    # Unit tests only
+go test ./... -run "Integration"  # Integration tests
 ```
 
-#### Make Options
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `TEST` | Package(s) to test | `./internal/...` |
+| `RUN` | Filter tests by name pattern | (none) |
+| `TESTARGS` | Additional arguments to pass to test command | (none) |
+| `TESTINFRA` | Set to `1` to use persistent test infrastructure | (none) |
+| `TESTCOMPAT` | Set to `1` to run full backend compatibility suite | (none) |
+| `TESTREDISCLUSTER` | Set to `1` to enable Redis cluster tests | (none) |
+| `RUNNER` | Force test runner: `gotestsum` or `go` | auto-detect |
 
-1. To test specific package
+### Examples
 
 ```sh
+# Test specific package
 TEST='./internal/services/api' make test
-```
 
-2. To run specific tests
-
-```sh
+# Run specific tests
 RUN='TestJWT' make test
-```
-
-3. To pass additional options
 
-```sh
+# Pass additional options
 TESTARGS='-v' make test
-```
 
-Keep in mind you can't use `RUN` along with `make test/integration` as it already uses `-run` option. However, since you're already specifying which test to run, we assume this is a non-issue.
+# Combine options
+RUN='TestListTenant' TEST='./internal/models' TESTINFRA=1 make test
+```
 
 ## Coverage