# How to Run the Test Suite and Contribute Code to mlx-omni-server

> Learn to run pytest tests and contribute code to mlx-omni-server. Clone the repo, install dependencies, run tests, and submit pull requests adhering to project standards.

- Repository: [madroid/mlx-omni-server](https://github.com/madroidmaq/mlx-omni-server)
- Tags: how-to-guide
- Published: 2026-03-06

---

**To run the test suite and contribute code to mlx-omni-server, clone the repository, install dependencies in editable mode with `uv pip install -e .`, execute tests via `uv run pytest`, and submit pull requests following the Black/Isort formatting standards and pre-commit hooks defined in the project documentation.**

MLX Omni Server is a FastAPI-based inference server that delivers OpenAI- and Anthropic-compatible endpoints for local AI models on Apple Silicon. Understanding how to run the test suite and contribute code properly ensures your modifications align with the existing architecture and maintain API compatibility across chat, audio, image, and embedding endpoints.

## Setting Up the Development Environment

Before running tests or submitting changes, configure a local development environment using the project's preferred package manager, `uv`.

Clone the repository and install the package in editable mode:

```bash
git clone https://github.com/madroidmaq/mlx-omni-server.git
cd mlx-omni-server
uv pip install -e .

```

This command installs `mlx-omni-server` along with its development dependencies, allowing you to modify source code in `src/mlx_omni_server/` without reinstallation.

To verify your setup, launch the server in development mode with hot-reloading enabled:

```bash
uvicorn mlx_omni_server.main:app --reload --host 0.0.0.0 --port 10240

```

The `--reload` flag monitors file changes automatically, which accelerates iteration when working on features in [`src/mlx_omni_server/routers.py`](https://github.com/madroidmaq/mlx-omni-server/blob/main/src/mlx_omni_server/routers.py) or endpoint handlers.

## Running the mlx-omni-server Test Suite

The repository includes a comprehensive pytest suite that exercises every public API through FastAPI's `TestClient`, ensuring endpoint contracts match OpenAI and Anthropic specifications.

Execute the full test suite with:

```bash
uv run pytest

```

Target specific API implementations using directory paths:

```bash
uv run pytest tests/chat/openai/     # OpenAI-compatible endpoints

uv run pytest tests/chat/anthropic/  # Anthropic-compatible endpoints

```

### Test Coverage Details

The suite validates functionality across multiple modules:

- **Chat completions** – Non-streaming and streaming responses, body parameter handling, and draft model integration ([`tests/chat/openai/test_chat_completions.py`](https://github.com/madroidmaq/mlx-omni-server/blob/main/tests/chat/openai/test_chat_completions.py))
- **Multimodal endpoints** – Audio transcription, image generation, and text embeddings ([`tests/audio_test.py`](https://github.com/madroidmaq/mlx-omni-server/blob/main/tests/audio_test.py), [`tests/images_test.py`](https://github.com/madroidmaq/mlx-omni-server/blob/main/tests/images_test.py), [`tests/embedding_test.py`](https://github.com/madroidmaq/mlx-omni-server/blob/main/tests/embedding_test.py))
- **MLX-specific features** – Tool calling and structured output wrappers (`tests/chat/mlx/*`)

Tests instantiate an in-process `TestClient` that mimics downstream consumer behavior, validating the exact JSON schemas defined in `src/mlx_omni_server/chat/openai/` and related modules.

## Contributing Code to mlx-omni-server

Contributions follow a standard Git workflow with strict code quality enforcement via CI pipelines.

### Contribution Workflow

1. **Fork and branch** – Create a feature branch: `git checkout -b feature/<description>`
2. **Implement changes** – Modify relevant files in `src/mlx_omni_server/` following the existing architecture
3. **Format code** – Run `black . && isort .` to ensure consistent style
4. **Install pre-commit hooks** – Execute `pre-commit install` then `pre-commit run --all-files` to catch linting errors before submission
5. **Validate locally** – Run `uv run pytest` to confirm all tests pass
6. **Commit** – Follow the conventional commit standards documented in [`docs/git-commit-conventions.md`](https://github.com/madroidmaq/mlx-omni-server/blob/main/docs/git-commit-conventions.md)
7. **Submit PR** – Push to your fork and open a Pull Request against the main branch

GitHub Actions automatically run the full test suite, formatting checks, and type validation on every pull request.

## Key Source Files for Contributors

Understanding the repository structure helps orient new contributions:

- **[`src/mlx_omni_server/main.py`](https://github.com/madroidmaq/mlx-omni-server/blob/main/src/mlx_omni_server/main.py)** – CLI entry point, CORS configuration, logging setup, and Uvicorn server initialization
- **[`src/mlx_omni_server/routers.py`](https://github.com/madroidmaq/mlx-omni-server/blob/main/src/mlx_omni_server/routers.py)** – Central registration of all API routers (`/v1/*`, `/anthropic/*`)
- **`src/mlx_omni_server/chat/openai/`** – OpenAI-compatible adapters, request parsing, and streaming response logic
- **`src/mlx_omni_server/chat/mlx/`** – Core MLX implementation for tool calling and structured outputs
- **[`docs/development_guide.md`](https://github.com/madroidmaq/mlx-omni-server/blob/main/docs/development_guide.md)** – Detailed environment setup and contribution guidelines

## Summary

- **Environment Setup** – Clone the repository and run `uv pip install -e .` to install dependencies in editable mode
- **Test Execution** – Use `uv run pytest` for full validation, or target specific directories like `tests/chat/openai/` for focused testing
- **Contribution Standards** – Follow the fork-branch-PR workflow, enforce code style with Black and Isort, install pre-commit hooks, and adhere to commit conventions documented in [`docs/git-commit-conventions.md`](https://github.com/madroidmaq/mlx-omni-server/blob/main/docs/git-commit-conventions.md)

## Frequently Asked Questions

### How do I run only specific tests in mlx-omni-server?

Target specific test directories or files using pytest's path selector. For example, `uv run pytest tests/chat/openai/` executes only OpenAI-compatible chat tests, while `uv run pytest tests/audio_test.py` runs audio endpoint validation exclusively.

### What code formatting standards does mlx-omni-server require?

The project mandates **Black** for code formatting and **Isort** for import sorting. Run `black . && isort .` before committing, or install pre-commit hooks with `pre-commit install` to automate these checks.

### How do I set up pre-commit hooks for mlx-omni-server?

Execute `pre-commit install` after cloning to register git hooks locally. Then run `pre-commit run --all-files` to validate your changes against the repository's linting rules before submitting a pull request.

### Where are the chat completion tests located?

Chat completion tests reside in [`tests/chat/openai/test_chat_completions.py`](https://github.com/madroidmaq/mlx-omni-server/blob/main/tests/chat/openai/test_chat_completions.py) for OpenAI-compatible endpoints and `tests/chat/anthropic/` for Anthropic-compatible implementations. MLX-specific chat features are tested in `tests/chat/mlx/`.