test: add test tooling and documentation

- Add Makefile with convenient test targets (test, test-integration, test-env-up, test-env-down)
- Add .env.test with test-specific configuration
- Update .env.example with test configuration options and warnings
- Update README.md with comprehensive testing documentation
- Document all environment variables with safety warnings

This makes it easy to run tests without rate limiting issues while
keeping production security intact.

.env.example

@@ -6,3 +6,15 @@ JWT_SECRET=your-secure-jwt-secret-key-here
 
 # PostgreSQL database password
 DBPASS=your-secure-database-password-here
+
+# Test Mode Configuration (WARNING: Only set to true for integration testing)
+# When enabled, rate limiting is disabled to allow rapid test execution
+# Never enable in production environments
+TEST_MODE=false
+
+# Rate Limiting Configuration
+# Set to false to disable rate limiting (only for test environments)
+RATE_LIMIT_ENABLED=true
+# Number of requests allowed per minute per IP (default: 10)
+# Increase for integration testing (e.g., 1000)
+REQUESTS_PER_MINUTE=10

.env.test

@@ -0,0 +1,25 @@
+# Test environment configuration
+# WARNING: This configuration disables security features for testing only
+# Never use these settings in production
+
+# Database configuration
+DBPASS=027b61803f1d6d1873b934e8
+DATABASE_HOST=localhost
+DATABASE_PORT=5432
+DATABASE_USER=postgres
+DATABASE_PASSWORD=027b61803f1d6d1873b934e8
+DATABASE_NAME=ebookdb
+
+# JWT configuration
+JWT_SECRET=f3b6693578fdbd0671adb5c9971e1f8b
+
+# Server configuration
+SERVER_PORT=8080
+
+# Upload path
+UPLOAD_PATH=./uploads
+
+# Test configuration (for integration testing)
+TEST_MODE=true
+RATE_LIMIT_ENABLED=false
+REQUESTS_PER_MINUTE=1000

Makefile

@@ -0,0 +1,59 @@
+.PHONY: help test test-integration test-all build build-force clean rebuild logs test-env-up test-env-down
+
+# Default target
+help:
+	@echo "Available targets:"
+	@echo "  make test              - Run unit tests"
+	@echo "  make test-integration  - Run integration tests with test mode enabled"
+	@echo "  make test-all          - Run all tests"
+	@echo "  make build             - Build and start containers"
+	@echo "  make build-force       - Force rebuild and start containers"
+	@echo "  make clean             - Stop and remove containers"
+	@echo "  make rebuild           - Clean, rebuild, and start containers"
+	@echo "  make logs              - Show container logs"
+	@echo "  make test-env-up       - Start containers with test mode enabled"
+	@echo "  make test-env-down     - Stop test environment"
+
+# Run unit tests
+test:
+	go test ./... -v -short
+
+# Run integration tests with test mode enabled (avoids rate limiting)
+test-integration:
+	@echo "Running integration tests with TEST_MODE enabled..."
+	TEST_MODE=true RATE_LIMIT_ENABLED=false go test ./cmd/server/tests -run TestIntegrationAPI -v -timeout 5m
+
+# Run all tests
+test-all: test test-integration
+
+# Build and start containers
+build:
+	podman compose up --build -d
+
+# Force rebuild without cache
+build-force:
+	podman compose build --no-cache
+	podman compose up -d
+
+# Stop and remove containers
+clean:
+	podman compose down -v
+
+# Clean rebuild (remove volumes, rebuild, start)
+rebuild: clean build
+
+# Show container logs
+logs:
+	podman compose logs -f
+
+# Start containers with test mode enabled for integration testing
+test-env-up:
+	@echo "Starting containers with test mode enabled..."
+	TEST_MODE=true RATE_LIMIT_ENABLED=false REQUESTS_PER_MINUTE=1000 podman compose up --build -d
+	@echo "Waiting for services to be ready..."
+	sleep 10
+	@echo "Test environment is ready!"
+
+# Stop test environment
+test-env-down:
+	podman compose down -v

README.md

@@ -434,9 +434,25 @@ Comprehensive integration test suite in `cmd/server/tests/`:
 
 Run integration tests:
 ```bash
+# Standard test run (may hit rate limits)
 go test ./cmd/server/tests -v
+
+# Recommended: Run with test mode enabled to avoid rate limiting
+TEST_MODE=true RATE_LIMIT_ENABLED=false go test ./cmd/server/tests -run TestIntegrationAPI -v
+
+# Or with increased rate limits
+TEST_MODE=true REQUESTS_PER_MINUTE=1000 go test ./cmd/server/tests -run TestIntegrationAPI -v
 ```
 
+### Test Configuration Options
+The following environment variables can be used to configure test behavior:
+
+- **TEST_MODE**: Set to `true` to enable test mode (logs additional info)
+- **RATE_LIMIT_ENABLED**: Set to `false` to disable rate limiting for tests
+- **REQUESTS_PER_MINUTE**: Increase rate limit (e.g., `1000`) to avoid throttling
+
+**⚠️ WARNING**: Never disable rate limiting or enable test mode in production environments. These settings are only for integration testing.
+
 ### API Testing
 ```bash
 # Install Bruno