test: Add test suite and CI workflow

.github/workflows/pr-test.yml

@@ -0,0 +1,22 @@
+name: PR Test Workflow
+
+on:
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.12'
+
+    - name: Install uv
+      run: pip install uv
+
+    - name: Run tests
+      run: bash run_tests.sh 

README.md

@@ -1,4 +1,5 @@
 # openai-responses-server
+
 A server the serves any AI provider with OpenAI ChatCompletions as OpenAI's Responses API and hosted tools.
 I means it manages the stateful component of Responses API, and bridges Ollama, Vllm, LiteLLM and any other AI serving library.
 This means you can use OpenAI's new coding assistant "Codex", that needs Responses API endpoints.
@@ -17,10 +18,21 @@ Install today via pip: [openai-responses-server](https://pypi.org/project/openai
 - [ ] State management (long term, not just in-memory)
 - [ ] Web search support ([crawl4ai](https://github.com/unclecode/crawl4ai))
 - [ ] File upload + search
-  - [ ] **[graphiti](https://github.com/getzep/graphiti) (based on neo4j)**
-- [ ] Code interpreter 
+   - [ ] **[graphiti](https://github.com/getzep/graphiti) (based on neo4j)**
+
+- [ ] Code interpreter
 - [ ] Computer use
 
+# Documentation
+
+The following guides are available in the `docs/` directory:
+
+- [CLI Local Documentation](docs/cli-local.md) - Documentation for local CLI usage
+- [Using UV](docs/using-uv.md) - Guide for working with the UV package manager
+- [Pip Publish Instructions](docs/pip-publish-instructions.md) - Instructions for publishing to PyPI
+- [Extension Guide](docs/extend-instructions.md) - How to extend the server functionality
+- [Testing Guide](docs/testing-guide.md) - Documentation for running and writing tests
+
 # OpenAI API Configuration
 
 OPENAI_BASE_URL_INTERNAL=# Your AI Provider host api. localhost for Ollama, Groq and even OpenAI  
@@ -40,6 +52,7 @@ LOG_FILE_PATH=./log/api_adapter.log
 # Installation
 
 ## UV cli
+
 Install uv if not installed yet.
 From: https://docs.astral.sh/uv/getting-started/installation/#standalone-installer
 
@@ -50,50 +63,56 @@ pip install uv
 ```bash
 curl -LsSf https://astral.sh/uv/install.sh | sh
 ```
-or 
+
+or
+
 ```powershell
 powershell -c "irm https://astral.sh/uv/install.ps1 | more"
 ```
 
 Setup environment with:
-```
+
+```text
 uv venv
-``` 
+```
 
 Install dependecies with uv
-```
+
+```sh
 uv pip install .
 uv pip install -e ".[dev]"  # for development
 ```
 
 Run server:
-```
+
+```sh
 uv run src/openai_responses_server/cli.py start
 ```
 
 # 📚 Citation
 
 ## Cited projects
 
-UncleCode. (2024). Crawl4AI: Open-source LLM Friendly Web Crawler & Scraper [Computer software]. 
+UncleCode. (2024). Crawl4AI: Open-source LLM Friendly Web Crawler & Scraper [Computer software].
 GitHub. https://github.com/unclecode/crawl4ai
 
-## Cite this project 
+## Cite this project
 
-If you use openai-responses-server in your research or project, please cite:  
+If you use openai-responses-server in your research or project, please cite:
 
 ### Code citation format
+
 @software{openai-responses-server,
-  author = {TeaBranch},
-  title = {openai-responses-server: Open-source server the serves any AI provider with OpenAI ChatCompletions as OpenAI's Responses API and hosted tools.},
-  year = {2025},
-  publisher = {GitHub},
-  journal = {GitHub Repository},
-  howpublished = {\url{https://github.com/teabranch/openai-responses-server}},
-  commit = {Please use the commit hash you're working with}
+author = {TeaBranch},
+title = {openai-responses-server: Open-source server the serves any AI provider with OpenAI ChatCompletions as OpenAI's Responses API and hosted tools.},
+year = {2025},
+publisher = {GitHub},
+journal = {GitHub Repository},
+howpublished = {\url{https://github.com/teabranch/openai-responses-server}},
+commit = {Please use the commit hash you're working with}
 }
 
 ### Text citation format:
 
-TeaBranch. (2025). openai-responses-server: Open-source server the serves any AI provider with OpenAI ChatCompletions as OpenAI's Responses API and hosted tools. [Computer software]. 
+TeaBranch. (2025). openai-responses-server: Open-source server the serves any AI provider with OpenAI ChatCompletions as OpenAI's Responses API and hosted tools. [Computer software].
 GitHub. https://github.com/teabranch/openai-responses-server

docs/testing-guide.md

@@ -0,0 +1,146 @@
+# Testing Guide
+
+This document provides an overview of the test suite for the OpenAI Responses Server, including how to run tests, what tests are included, and best practices for contributing new tests.
+
+## Running Tests
+
+The project includes a utility script `run_tests.sh` that configures and runs the test suite. This script:
+
+1. Creates a virtual environment using `uv`
+2. Installs the package and test dependencies
+3. Runs all tests using pytest
+
+To run all tests:
+
+```bash
+./run_tests.sh
+```
+
+To run specific tests:
+
+```bash
+# Activate the virtual environment first
+source .venv/bin/activate
+
+# Run a specific test file
+python -m pytest tests/test_cli.py -v
+
+# Run a specific test class
+python -m pytest tests/test_cli.py::TestCLI -v
+
+# Run a specific test method
+python -m pytest tests/test_cli.py::TestCLI::test_start_server_imports -v
+```
+
+## Test Suite Structure
+
+The test suite is organized into several files:
+
+- `tests/test_cli.py`: Tests for CLI functionality
+- `tests/test_server.py`: Tests for server API endpoints
+- `tests/test_e2e.py`: End-to-end integration tests
+
+### Fixtures and Utilities
+
+Test fixtures are defined in `tests/conftest.py` and include:
+
+- `python_executable`: Detects Python version and executable path
+- `ensure_uv`: Verifies that the uv package manager is installed
+- `temp_env_file`: Creates a temporary .env file for testing
+- `server_process`: Starts the server as a separate process for testing
+- `mock_httpx_client`: Mocks HTTP client responses for unit testing
+
+## Writing Tests
+
+When adding new functionality, please include corresponding tests. Follow these guidelines:
+
+### Unit Tests
+
+Unit tests should focus on testing individual functions or methods in isolation:
+
+```python
+def test_specific_function():
+    # Arrange
+    input_data = ...
+
+    # Act
+    result = function_under_test(input_data)
+
+    # Assert
+    assert result == expected_result
+```
+
+### Mock External Dependencies
+
+When testing code that depends on external systems, use mocks to isolate your tests:
+
+```python
+@patch('module.external_dependency')
+def test_with_mock(mock_dependency):
+    mock_dependency.return_value = expected_mock_value
+
+    # Test with the mocked dependency
+    result = function_using_dependency()
+
+    assert result == expected_result
+```
+
+### Testing the CLI
+
+CLI tests use `unittest.mock` to patch dependencies and avoid actual server startup:
+
+```python
+with patch('sys.argv', ['command_name', 'subcommand']):
+    with patch('module.function_to_mock') as mock_function:
+        main()  # Call the CLI entry point
+        mock_function.assert_called_once()
+```
+
+### Testing Async Code
+
+The project uses `pytest-asyncio` for testing asynchronous code. Mark your test functions with `@pytest.mark.asyncio`:
+
+```python
+@pytest.mark.asyncio
+async def test_async_function():
+    result = await async_function()
+    assert result == expected_result
+```
+
+## Troubleshooting Common Test Issues
+
+### ImportError in Subprocess Fallback Test
+
+If encountering an `ImportError` in `test_start_server_subprocess_fallback`, verify that the mocking is correctly set up. The test should mock imports by manipulating `sys.modules`:
+
+```python
+with patch.dict('sys.modules', {'uvicorn': None, 'openai_responses_server.server': None}):
+    # The import will fail with ImportError
+    with patch('module.subprocess') as mock_subprocess:
+        # Test subprocess fallback
+```
+
+### Missing Dependencies
+
+If tests fail with missing dependencies, ensure you've installed the test requirements:
+
+```bash
+uv pip install -e ".[dev]"
+uv pip install pytest-asyncio httpx
+```
+
+## Test Coverage
+
+To generate a test coverage report:
+
+```bash
+python -m pytest --cov=openai_responses_server tests/
+```
+
+For HTML coverage report:
+
+```bash
+python -m pytest --cov=openai_responses_server --cov-report=html tests/
+```
+
+The HTML report will be generated in the `htmlcov` directory. 

run_tests.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+# Script to run tests for openai-responses-server using uv
+
+set -e  # Exit on error
+
+# Detect Python version and executable
+PYTHON_VERSION=$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')
+PYTHON_EXECUTABLE=$(which python3)
+
+echo "Detected Python $PYTHON_VERSION at $PYTHON_EXECUTABLE"
+
+# Check if uv is installed
+if ! command -v uv &> /dev/null; then
+    echo "uv is not installed. Installing now..."
+    $PYTHON_EXECUTABLE -m pip install uv
+fi
+
+# Create a virtual environment using uv
+echo "Creating a virtual environment with uv..."
+uv venv .venv
+
+# Activate the virtual environment
+echo "Activating virtual environment..."
+source .venv/bin/activate
+
+# Install the package and test dependencies
+echo "Installing dependencies with uv..."
+uv pip install -e ".[dev]"
+uv pip install pytest-asyncio httpx
+
+# Create log directory if it doesn't exist
+mkdir -p log
+
+# Run the tests
+echo "Running tests..."
+python -m pytest tests/ -v
+
+# Clean up
+echo "Tests completed. Deactivating virtual environment..."
+deactivate
+
+echo "All tests completed successfully!"