unit and integration tests

Author: YaoxuanZhang

.agent/workflows/agents.md

@@ -6,6 +6,11 @@ description: Best practices workflow for building the CAPY Go REST API with type
 
 This workflow ensures type-safe, reliable, and production-ready Go code for the CAPY club management API.
 
+> [!IMPORTANT]
+> **NO EMOJIS IN CODE OR COMMITS**
+> Do not use emojis in source code comments, commit messages, or pull request descriptions. Keep professional and clean.
+
+
 ## Prerequisites
 
 Ensure you have the required tools installed:
@@ -204,32 +209,32 @@ func TestCreateUser_Success(t *testing.T) {
 }
 ```
 
-### Step 4.2: Integration Tests
+### Step 4.2: Integration Tests (Testcontainers)
+
+Use `testcontainers-go` for isolated integration testing without managing external Docker Compose services manually.
 
 ```go
 //go:build integration
 
 func TestUserAPI_Integration(t *testing.T) {
-    // Setup real DB connection
-    pool := setupTestDB(t)
+    // Setup ephemeral Postgres via Testcontainers
+    pool := testutils.SetupTestDB(t)
     defer pool.Close()
 
-    // Run migration
-    runMigrations(t, pool)
-
-    // Test CRUD operations
+    // Test CRUD operations logic
     // ...
 }
 ```
 
 ### Step 4.3: Run Tests
 
 ```bash
-# Unit tests only
-go test -v -short ./...
+# Unit tests only (fast)
+go test -v ./...
 
-# All tests including integration
-docker-compose up -d db
+# All tests including integration (slow, requires Docker)
+make test-all
+# OR
 go test -v -tags=integration ./...
 ```
 
@@ -244,7 +249,7 @@ Before deploying any endpoint:
 - [ ] **Authentication**: Endpoint uses `middleware.Authenticator`
 - [ ] **Authorization**: Role check matches API design (faculty, org_admin, etc.)
 - [ ] **Input Validation**: All user input validated with struct tags
-- [ ] **SQL Injection**: Using sqlc (parameterized queries) — automatic ✓
+- [ ] **SQL Injection**: Using sqlc (parameterized queries) — automatic
 - [ ] **Error Handling**: No sensitive info leaked in error messages
 - [ ] **Logging**: Sensitive data (passwords, tokens) never logged
 - [ ] **Rate Limiting**: Consider adding for public endpoints

.github/workflows/ci.yml

@@ -0,0 +1,64 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    name: Test and Lint
+    runs-on: ubuntu-latest
+    
+    services:
+      # Optional: We use testcontainers, but having a service is good for fallback or specific DB tests
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_USER: test
+          POSTGRES_PASSWORD: test
+          POSTGRES_DB: test_db
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.25'
+          cache: true
+
+      - name: Install dependencies
+        run: go mod download
+
+      - name: Verify dependencies
+        run: go mod verify
+
+      - name: Install tools
+        run: |
+          go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest
+          go install github.com/swaggo/swag/cmd/swag@latest
+
+      - name: Generate code
+        run: make generate
+
+      - name: Run Linter
+        uses: golangci/golangci-lint-action@v4
+        with:
+          version: latest
+          args: --timeout=5m
+
+      - name: Run Unit Tests
+        run: make test
+
+      - name: Run Integration Tests
+        run: make test-integration

Makefile

@@ -20,7 +20,7 @@ test-integration:
 	go test -v -race -run Integration ./...
 
 test-all:
-	go test -v -race ./...
+	go test -v -race -tags=integration ./...
 
 # Linting
 lint:

README.md

@@ -0,0 +1,97 @@
+# CAPY API
+
+The backend API for the CAPY club management system. Built with Go (Chi), PostgreSQL, and SQLC.
+
+## Features
+- **Authentication**: JWT-based auth and OAuth2 (Google/Microsoft) support.
+- **Role-Based Access**: Granular permissions for Student, Alumni, Faculty, and External roles.
+- **Organization Management**: Create and join organizations (clubs).
+- **Event System**: Event scheduling, registration, and attendance tracking.
+- **Bot Integration**: API tokens for bot automation.
+
+## Tech Stack
+- **Language**: Go 1.25+
+- **Router**: [Chi](https://github.com/go-chi/chi)
+- **Database**: PostgreSQL
+- **ORM-ish**: [sqlc](https://sqlc.dev/) (Type-safe SQL generation)
+- **Migration**: [golang-migrate](https://github.com/golang-migrate/migrate)
+- **Testing**:
+    - [Testify](https://github.com/stretchr/testify) (Assertions)
+    - [Testcontainers](https://github.com/testcontainers/testcontainers-go) (Integration tests)
+    - [Mockery](https://github.com/vektra/mockery) (Mock generation)
+- **Documentation**: Swagger/OpenAPI (via `swag`)
+
+## Prerequisites
+- Go 1.25+
+- Docker & Docker Compose (for local DB)
+- Make
+
+## Getting Started
+
+### 1. Clone & Config
+```bash
+git clone https://github.com/CAPY-RPI/api.git
+cd capy-api
+cp .env.example .env
+# Edit .env with your local credentials if needed
+```
+
+### 2. Start Infrastructure
+Start the PostgreSQL database:
+```bash
+make docker
+```
+
+### 3. Run Migrations & Generate Code
+```bash
+# Install tools if needed (see Step 5 in agents.md or CI workflow)
+make generate
+```
+
+### 4. Run Server
+```bash
+make run
+# API will be available at http://localhost:8080
+# Health check: http://localhost:8080/health
+```
+
+## Testing
+
+### Unit Tests
+Fast tests running in isolation with mocks.
+```bash
+make test
+```
+
+### Integration Tests
+Full-stack tests using ephemeral Docker containers (Postgres). Requires Docker to be running.
+```bash
+make test-integration
+```
+
+### Run All Tests
+```bash
+make test-all
+```
+
+## Project Structure
+```
+.
+├── cmd/server/         # Main entry point
+├── internal/
+│   ├── config/         # Configuration loading
+│   ├── database/       # sqlc generated code & queries
+│   ├── dto/            # Data Transfer Objects (Request/Response)
+│   ├── handler/        # HTTP Handlers
+│   ├── middleware/     # Auth, CORS, Logger middleware
+│   ├── router/         # Route definitions
+│   └── testutils/      # Testing helpers
+├── migrations/         # SQL migration files
+├── tests/integration/  # End-to-end integration tests
+└── schema.sql          # Current database schema
+```
+
+## CI/CD
+This project uses GitHub Actions for continuous integration.
+- **Workflow**: `.github/workflows/ci.yml`
+- **Checks**: Linting (`golangci-lint`), Unit Tests, Integration Tests.

cmd/server/main.go

@@ -44,7 +44,7 @@ func main() {
 	h := handler.New(queries, cfg)
 
 	// Setup router
-	r := router.New(h, queries, cfg.JWT.Secret)
+	r := router.New(h, queries, cfg.JWT.Secret, cfg.Server.AllowedOrigins)
 
 	// Create server
 	addr := cfg.Server.Host + ":" + cfg.Server.Port

go.mod

@@ -8,21 +8,74 @@ require (
 	github.com/google/uuid v1.6.0
 	github.com/ilyakaznacheev/cleanenv v1.5.0
 	github.com/jackc/pgx/v5 v5.8.0
+	github.com/stretchr/testify v1.11.1
+	github.com/testcontainers/testcontainers-go v0.40.0
+	github.com/testcontainers/testcontainers-go/modules/postgres v0.40.0
 	golang.org/x/crypto v0.47.0
 	golang.org/x/oauth2 v0.34.0
 )
 
 require (
-	cloud.google.com/go/compute/metadata v0.3.0 // indirect
+	cloud.google.com/go/compute/metadata v0.9.0 // indirect
+	dario.cat/mergo v1.0.2 // indirect
+	github.com/Azure/go-ansiterm v0.0.0-20210617225240-d185dfc1b5a1 // indirect
 	github.com/BurntSushi/toml v1.2.1 // indirect
+	github.com/Microsoft/go-winio v0.6.2 // indirect
+	github.com/cenkalti/backoff/v4 v4.3.0 // indirect
+	github.com/containerd/errdefs v1.0.0 // indirect
+	github.com/containerd/errdefs/pkg v0.3.0 // indirect
+	github.com/containerd/log v0.1.0 // indirect
+	github.com/containerd/platforms v0.2.1 // indirect
+	github.com/cpuguy83/dockercfg v0.3.2 // indirect
+	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
+	github.com/distribution/reference v0.6.0 // indirect
+	github.com/docker/docker v28.5.1+incompatible // indirect
+	github.com/docker/go-connections v0.6.0 // indirect
+	github.com/docker/go-units v0.5.0 // indirect
+	github.com/ebitengine/purego v0.8.4 // indirect
+	github.com/felixge/httpsnoop v1.0.4 // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/go-ole/go-ole v1.2.6 // indirect
+	github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.7 // indirect
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
 	github.com/jackc/puddle/v2 v2.2.2 // indirect
 	github.com/joho/godotenv v1.5.1 // indirect
-	github.com/kr/text v0.2.0 // indirect
-	github.com/rogpeppe/go-internal v1.14.1 // indirect
+	github.com/klauspost/compress v1.18.0 // indirect
+	github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 // indirect
+	github.com/magiconair/properties v1.8.10 // indirect
+	github.com/moby/docker-image-spec v1.3.1 // indirect
+	github.com/moby/go-archive v0.1.0 // indirect
+	github.com/moby/patternmatcher v0.6.0 // indirect
+	github.com/moby/sys/sequential v0.6.0 // indirect
+	github.com/moby/sys/user v0.4.0 // indirect
+	github.com/moby/sys/userns v0.1.0 // indirect
+	github.com/moby/term v0.5.0 // indirect
+	github.com/morikuni/aec v1.0.0 // indirect
+	github.com/opencontainers/go-digest v1.0.0 // indirect
+	github.com/opencontainers/image-spec v1.1.1 // indirect
+	github.com/pkg/errors v0.9.1 // indirect
+	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+	github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c // indirect
+	github.com/shirou/gopsutil/v4 v4.25.6 // indirect
+	github.com/sirupsen/logrus v1.9.3 // indirect
+	github.com/stretchr/objx v0.5.2 // indirect
+	github.com/tklauser/go-sysconf v0.3.12 // indirect
+	github.com/tklauser/numcpus v0.6.1 // indirect
+	github.com/yusufpapurcu/wmi v1.2.4 // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.54.0 // indirect
+	go.opentelemetry.io/otel v1.38.0 // indirect
+	go.opentelemetry.io/otel/metric v1.38.0 // indirect
+	go.opentelemetry.io/otel/sdk v1.38.0 // indirect
+	go.opentelemetry.io/otel/trace v1.38.0 // indirect
 	golang.org/x/sync v0.19.0 // indirect
+	golang.org/x/sys v0.40.0 // indirect
 	golang.org/x/text v0.33.0 // indirect
+	golang.org/x/time v0.8.0 // indirect
+	google.golang.org/grpc v1.78.0 // indirect
+	google.golang.org/protobuf v1.36.11 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 	olympos.io/encoding/edn v0.0.0-20201019073823-d3554ca0b0a3 // indirect
 )