Add integration testing setup with UvicornTestServer

- Introduced UvicornTestServer class for running a uvicorn server in a background thread, allowing for real HTTP endpoint testing without blocking.
- Added pytest fixture `running_server` for session-scoped server management, ensuring isolation between tests.
- Created README.md with detailed instructions on integration testing approaches and usage examples.
- Removed outdated test_basic.py file and added test_health.py to validate the health endpoint using the new server setup.

Author: NiveditJain

integration-tests/README.md

@@ -0,0 +1,207 @@
+# Integration Testing with Uvicorn Server
+
+This directory contains examples of how to properly run and stop uvicorn servers for integration testing. Unlike the problematic approach of using `uvicorn.run()` (which blocks forever), these examples show you how to create real HTTP endpoints that you can send requests to.
+
+## 🚨 The Problem with `uvicorn.run()`
+
+The original code had this issue:
+
+```python
+@pytest.mark.asyncio
+async def test_basic():
+    uvicorn.run(app, host="127.0.0.1", port=8000)  # ❌ This blocks forever!
+    async with ClientSession() as session:  # ❌ This never executes
+        # ... test code that never runs
+```
+
+**Problem**: `uvicorn.run()` is a blocking call that never returns, so your test code after it never executes.
+
+## ✅ Proper Solutions
+
+### 1. UvicornTestServer Class (Recommended)
+
+The `UvicornTestServer` class in `test_basic.py` provides a clean way to start and stop uvicorn servers:
+
+```python
+from test_basic import UvicornTestServer
+
+# Create and start server
+server = UvicornTestServer(app, host="127.0.0.1", port=8000)
+server.start()
+
+# Make HTTP requests
+async with ClientSession() as session:
+    async with session.get(f"{server.base_url}/health") as response:
+        assert response.status == 200
+
+# Stop server
+server.stop()
+```
+
+**Features:**
+- ✅ Automatic port detection (avoids conflicts)
+- ✅ Proper startup/shutdown lifecycle
+- ✅ Thread-based server execution
+- ✅ Waits for server to be ready
+- ✅ Graceful cleanup
+
+### 2. Pytest Fixtures
+
+Use pytest fixtures for automatic server management:
+
+```python
+@pytest.fixture(scope="session")
+def running_server():
+    """Server shared across all tests in the session."""
+    server = UvicornTestServer(app)
+    server.start()
+    yield server
+    server.stop()
+
+@pytest.fixture(scope="function")
+def fresh_server():
+    """Fresh server for each test."""
+    server = UvicornTestServer(app)
+    server.start()
+    yield server
+    server.stop()
+```
+
+### 3. Manual Server Management
+
+For full control over server lifecycle:
+
+```python
+@pytest.mark.asyncio
+async def test_manual_server():
+    server = UvicornTestServer(app)
+    
+    try:
+        server.start()
+        # Your test code here
+        async with ClientSession() as session:
+            async with session.get(f"{server.base_url}/health") as response:
+                assert response.status == 200
+    finally:
+        server.stop()  # Always cleanup
+```
+
+## 🏃‍♂️ Running the Examples
+
+### Install Dependencies
+
+```bash
+cd integration-tests
+uv sync
+```
+
+### Run Tests
+
+```bash
+# Run all tests
+uv run python -m pytest test_basic.py -v
+
+# Run specific test
+uv run python -m pytest test_basic.py::test_basic_with_session_server -v -s
+
+# Run with output
+uv run python -m pytest test_basic.py -v -s
+```
+
+### Run Demo Server
+
+```bash
+# Start a server you can send requests to
+uv run python demo_server.py
+```
+
+Then in another terminal:
+```bash
+curl http://127.0.0.1:8000/health
+curl http://127.0.0.1:8000/test
+```
+
+## 📁 File Overview
+
+- **`test_basic.py`** - Main test file with UvicornTestServer class and examples
+- **`test_server_examples.py`** - Comprehensive examples of different testing approaches
+- **`demo_server.py`** - Simple script to run a server manually
+- **`pyproject.toml`** - Project dependencies
+
+## 🎯 When to Use Each Approach
+
+### Session-Scoped Server (`running_server` fixture)
+- ✅ Fast test execution (server starts once)
+- ✅ Good for multiple tests that don't interfere
+- ❌ Tests share state
+- **Use for**: Most integration tests
+
+### Function-Scoped Server (`fresh_server` fixture)  
+- ✅ Complete isolation between tests
+- ✅ Clean state for each test
+- ❌ Slower (starts server for each test)
+- **Use for**: Tests that modify server state
+
+### Manual Server Management
+- ✅ Full control over lifecycle
+- ✅ Can test server startup/shutdown
+- ❌ More verbose
+- **Use for**: Complex scenarios, debugging
+
+### Demo Server Script
+- ✅ Perfect for development and debugging
+- ✅ Can send real HTTP requests
+- ✅ Easy to test endpoints manually
+- **Use for**: Development, manual testing
+
+## 🔧 Key Features of UvicornTestServer
+
+1. **Automatic Port Detection**: Finds free ports to avoid conflicts
+2. **Proper Lifecycle**: Clean startup and shutdown
+3. **Thread Safety**: Runs server in background thread
+4. **Health Checking**: Waits for server to be ready
+5. **Graceful Shutdown**: Proper cleanup on exit
+6. **Error Handling**: Robust error handling and timeouts
+
+## 🚀 Making HTTP Requests
+
+Once you have a running server, you can make requests using:
+
+### With aiohttp (async)
+```python
+async with ClientSession() as session:
+    async with session.get(f"{server.base_url}/health") as response:
+        data = await response.json()
+        assert data["message"] == "OK"
+```
+
+### With httpx (async)
+```python
+async with httpx.AsyncClient() as client:
+    response = await client.get(f"{server.base_url}/health")
+    assert response.status_code == 200
+```
+
+### With curl (command line)
+```bash
+curl http://127.0.0.1:8000/health
+curl -X POST http://127.0.0.1:8000/api/data -H "Content-Type: application/json" -d '{"key": "value"}'
+```
+
+### With requests (sync)
+```python
+import requests
+response = requests.get(f"{server.base_url}/health")
+assert response.status_code == 200
+```
+
+## 🎉 Success!
+
+Now you have a proper way to run uvicorn servers for integration testing that:
+- ✅ Actually starts and stops properly
+- ✅ Provides real HTTP endpoints
+- ✅ Handles cleanup automatically
+- ✅ Avoids port conflicts
+- ✅ Works reliably in CI/CD
+
+No more blocking `uvicorn.run()` calls or tests that never execute! 

integration-tests/conftest.py

@@ -0,0 +1,108 @@
+import pytest
+import asyncio
+import threading
+import time
+import uvicorn
+from app.main import app
+
+
+class UvicornTestServer:
+    """
+    A proper uvicorn server for integration testing with real HTTP endpoints.
+    This runs the server in a background thread with proper startup and shutdown.
+    """
+    
+    def __init__(self, app, host="127.0.0.1", port=None):
+        self.app = app
+        self.host = host
+        self.port = port or self._find_free_port()
+        self.server = None
+        self.thread = None
+        self.started = False
+    
+    def _find_free_port(self):
+        """Find a free port to avoid conflicts."""
+        import socket
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.bind(('', 0))
+            s.listen(1)
+            port = s.getsockname()[1]
+        return port
+    
+    def start(self):
+        """Start the uvicorn server in a background thread."""
+        if self.started:
+            return
+        
+        config = uvicorn.Config(
+            app=self.app,
+            host=self.host,
+            port=self.port,
+            log_level="info",
+            access_log=True
+        )
+        self.server = uvicorn.Server(config)
+        
+        def run_server():
+            """Run the server in the thread."""
+            assert self.server is not None
+            asyncio.run(self.server.serve())
+        
+        self.thread = threading.Thread(target=run_server, daemon=True)
+        self.thread.start()
+        
+        # Wait for server to be ready
+        self._wait_for_server()
+        self.started = True
+        print(f"🚀 Server started on http://{self.host}:{self.port}")
+    
+    def stop(self):
+        """Stop the server gracefully."""
+        if not self.started:
+            return
+        
+        print("🛑 Stopping server...")
+        if self.server:
+            self.server.should_exit = True
+        
+        if self.thread and self.thread.is_alive():
+            self.thread.join(timeout=10)
+        
+        self.started = False
+        print("✅ Server stopped")
+    
+    def _wait_for_server(self, timeout=30):
+        """Wait for the server to accept connections."""
+        import socket
+        start_time = time.time()
+        
+        while time.time() - start_time < timeout:
+            try:
+                with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+                    sock.settimeout(1)
+                    result = sock.connect_ex((self.host, self.port))
+                    if result == 0:
+                        return
+            except Exception:
+                pass
+            time.sleep(0.2)
+        
+        raise RuntimeError(f"Server failed to start within {timeout} seconds")
+    
+    @property
+    def base_url(self):
+        """Get the base URL of the running server."""
+        return f"http://{self.host}:{self.port}"
+
+
+@pytest.fixture(scope="session")
+def running_server():
+    """
+    Session-scoped fixture that provides a fresh server for each test.
+    Use this when you need isolation between tests.
+    """
+    server = UvicornTestServer(app)
+    server.start()
+    yield server
+    server.stop()
+

integration-tests/test_basic.py

@@ -0,0 +1,11 @@
+import pytest
+from aiohttp import ClientSession
+
+@pytest.mark.asyncio
+async def test_health_endpoint(running_server):
+    """Test using the session-scoped server (shared across tests)."""
+    async with ClientSession() as session:
+        async with session.get(f"{running_server.base_url}/health") as response:
+            assert response.status == 200
+            data = await response.json()
+            assert data["message"] == "OK"