Adding integration tests (#351)

* Add integration tests setup with initial configuration files

- Created .gitignore to exclude unnecessary files and directories from version control.
- Added .python-version to specify the Python version for the integration tests.
- Introduced pyproject.toml for project metadata and dependency management, including required packages for development.
- Configured pytest with pytest.ini to define test discovery patterns.
- Implemented a basic test case in test_basic.py to validate the testing framework setup.
- Generated uv.lock to lock dependencies for consistent environments.

* Update pyproject.toml to define build system requirements

- Added build-system section to specify setuptools and wheel as requirements for building the project, ensuring compatibility and proper packaging.

* Add build-system section to pyproject.toml

- Introduced a build-system section specifying setuptools and wheel as requirements for building the project, ensuring proper packaging and compatibility.

* Update pyproject.toml and uv.lock to enhance dependency management

- Added new dependencies `exospherehost` and `state-manager` to the `pyproject.toml` for improved integration testing.
- Configured dependency groups and specified paths for local development.
- Updated `uv.lock` to include new package versions and their metadata, ensuring consistent environments and access to the latest features.

* 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.

* Add integration tests workflow for Exosphere

- Created a new GitHub Actions workflow for running integration tests, triggered on pushes to the main branch.
- Configured MongoDB service for test environment setup, including health checks and initialization parameters.
- Set up Python environment and installed development dependencies using Uvicorn.
- Implemented steps to run integration tests with pytest, ensuring proper environment variable configuration for database access and API keys.
- Removed release trigger from the publish-state-manager workflow to streamline the process.

* Update integration-tests/pyproject.toml

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: NiveditJain

.github/workflows/integration-tests.yml

@@ -0,0 +1,58 @@
+name: Integration Tests for Exosphere
+
+on:
+    push:
+        branches: [main]
+        paths:
+          - 'integration-tests/**'
+          - 'state-manager/**'
+          - 'python-sdk/**'
+          - '.github/workflows/integration-tests.yml'
+
+jobs:
+    test:
+        runs-on: ubuntu-latest
+        services:
+            mongodb:
+              image: mongo:7
+              ports:
+                - 27017:27017
+              options: >-
+                --health-cmd "mongosh --eval 'db.runCommand(\"ping\")'"
+                --health-interval 10s
+                --health-timeout 5s
+                --health-retries 5
+              env:
+                MONGO_INITDB_ROOT_USERNAME: admin
+                MONGO_INITDB_ROOT_PASSWORD: password
+                MONGO_INITDB_DATABASE: integration_tests
+
+        steps:
+        - name: Checkout code
+          uses: actions/checkout@v4
+
+        - name: Set up Python
+          uses: actions/setup-python@v5
+          with:
+            python-version: '3.12'
+
+        - name: Install uv
+          uses: astral-sh/setup-uv@v2
+          with:
+            cache: true
+
+        - name: Install dev dependencies with uv
+          working-directory: integration-tests
+          run: |
+            uv sync --group dev
+
+        - name: Run integration tests
+          working-directory: integration-tests
+          env:
+            MONGO_URI: mongodb://admin:password@localhost:27017
+            MONGO_DATABASE_NAME: integration_tests
+            STATE_MANAGER_SECRET: test-secret-key
+            EXOSPHERE_API_KEY: test-secret-key
+            SECRETS_ENCRYPTION_KEY: YTzpUlBGLSwm-3yKJRJTZnb0_aQuQQHyz64s8qAERVU=
+          run: |
+            uv run pytest

.github/workflows/publish-state-mangaer.yml

@@ -5,8 +5,6 @@ on:
     branches: [main]
     paths:
       - 'state-manager/**'
-  release:
-    types: [published]
   workflow_dispatch:
 
 env:

integration-tests/.gitignore

@@ -0,0 +1,66 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environment
+venv/
+env/
+ENV/
+.env
+.venv/
+
+# IDE
+.vscode/
+*.swp
+*.swo
+.idea/
+*.iws
+*.iml
+*.ipr
+
+
+# Local development
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Database
+*.db
+*.sqlite3
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+#logs 
+*.log
+logs/*.*
+!logs/.gitkeep
+
+# local files
+files/
+!files/.gitkeep

integration-tests/.python-version

@@ -0,0 +1 @@
+3.12

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!