From 24f32421adbf6bb756a695305baea278f8301421 Mon Sep 17 00:00:00 2001
From: juanatsap <juanatsap@gmail.com>
Date: Sat, 6 Dec 2025 15:24:07 +0000
Subject: [PATCH] chore: improve test targets and documentation

- Add test-local target for running all tests from project root
- Add -short flag to test-unit for CI-safe execution
- Expand tests/README.md with Go backend test documentation
- Rename css-bundling test to follow numbered convention (81-)
---
 Makefile                                      |  9 ++-
 tests/README.md                               | 75 ++++++++++++++++++-
 ...ling.test.mjs => 81-css-bundling.test.mjs} |  0
 3 files changed, 81 insertions(+), 3 deletions(-)
 rename tests/mjs/{css-bundling.test.mjs => 81-css-bundling.test.mjs} (100%)

diff --git a/Makefile b/Makefile
index 0173a61..69b9653 100644
--- a/Makefile
+++ b/Makefile
@@ -1,11 +1,16 @@
-.PHONY: test test-all test-unit test-integration lint lint-fix build dev run clean css-dev css-prod css-watch css-clean sprites sprites-clean
+.PHONY: test test-all test-unit test-local test-integration lint lint-fix build dev run clean css-dev css-prod css-watch css-clean sprites sprites-clean
 
 # Default: Run unit tests only (fast, no Chrome needed)
 test: test-unit
 
-# Run unit tests only (CI-safe, no Chrome)
+# Run unit tests only (CI-safe, skips tests requiring project root)
 test-unit:
 	@echo "🧪 Running unit tests..."
+	go test -short -v -race -coverprofile=coverage.txt -covermode=atomic ./...
+
+# Run unit tests from project root (includes all tests)
+test-local:
+	@echo "🧪 Running ALL unit tests from project root..."
 	go test -v -race -coverprofile=coverage.txt -covermode=atomic ./...
 
 # Run ALL tests including PDF/Chrome integration tests
diff --git a/tests/README.md b/tests/README.md
index fc562e1..c504b93 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -17,8 +17,25 @@ If something breaks and the test didn't catch it → **THE TEST IS INCOMPLETE**
 
 ## Quick Start
 
+### Go Backend Tests
 ```bash
-# Run ALL tests (the complete specification)
+# Run unit tests (fast, CI-safe)
+make test
+
+# Run ALL tests including integration (requires Chrome)
+make test-all
+
+# Run integration tests only
+make test-integration
+
+# Run with coverage report
+go test -v -race -coverprofile=coverage.txt ./...
+go tool cover -html=coverage.txt  # View in browser
+```
+
+### Frontend Tests (Playwright)
+```bash
+# Run ALL frontend tests
 bun tests/run-all.mjs
 
 # Run individual test
@@ -32,6 +49,62 @@ bun tests/mjs/6-modals.test.mjs
 bun tests/mjs/7-mobile-responsive.test.mjs
 ```
 
+---
+
+## Go Backend Test Structure
+
+Go tests are **colocated with source code** (Go convention):
+
+```
+internal/
+├── handlers/
+│   ├── cv_pages.go
+│   ├── cv_pages_test.go      # Handler tests
+│   ├── cv_contact_test.go
+│   ├── cv_htmx_test.go
+│   ├── cv_security_test.go
+│   ├── cv_text_test.go
+│   ├── cv_cmdk_test.go
+│   ├── pdf_test.go           # PDF generation (integration tag)
+│   └── benchmarks_test.go
+├── models/cv/
+│   ├── loader_test.go        # JSON loading tests
+│   └── validation_test.go    # Data validation tests
+├── middleware/
+│   ├── preferences_test.go
+│   └── benchmarks_test.go
+├── validation/
+│   └── contact_test.go       # Form validation tests
+├── fileutil/
+│   └── fileutil_test.go
+└── lang/
+    └── lang_test.go
+
+tests/
+├── integration/
+│   └── email_test.go         # SMTP integration (requires credentials)
+└── security/
+    └── contact_security_test.go  # Security-focused tests
+```
+
+### Go Test Categories
+
+| Category | Command | Description |
+|----------|---------|-------------|
+| Unit | `make test` | Fast, CI-safe (skips path-dependent tests) |
+| Local | `make test-local` | All unit tests (run from project root) |
+| Integration | `make test-integration` | Requires Chrome/SMTP |
+| All | `make test-all` | Complete suite with integration |
+| Benchmarks | `go test -bench=. ./...` | Performance tests |
+
+### CI/CD Integration
+
+- **GitHub Actions**: `.github/workflows/test.yml`
+- **Coverage target**: 70% (warning if below)
+- **Artifacts**: coverage.txt, benchmark.txt uploaded
+
+---
+
 ## Test Suite Structure
 
 ```
diff --git a/tests/mjs/css-bundling.test.mjs b/tests/mjs/81-css-bundling.test.mjs
similarity index 100%
rename from tests/mjs/css-bundling.test.mjs
rename to tests/mjs/81-css-bundling.test.mjs