# How to Run Tests in the Marin Repository: Complete Developer Guide > Learn how to run tests in the Marin repository using uv run pytest for quick checks or the comprehensive test suite with safe defaults. Your complete developer guide. - Repository: [The Marin Project/marin](https://github.com/marin-community/marin) - Tags: how-to-guide - Published: 2026-08-27 --- **To run tests in the Marin repository, use `uv run pytest ` for rapid feedback during development, or `uv run --no-project infra/ci/run_tests.py` to execute the repository-wide test suite with safe defaults, 60-second timeouts, and excluded integration markers.** The marin-community/marin codebase enforces a strict two-step testing workflow designed to balance developer velocity with CI safety. Whether you are iterating on a specific module or validating changes against the full suite, understanding how to run tests in the Marin repository correctly prevents accidental execution of destructive cluster workloads. ## Quick Start: The Two-Command Workflow According to the quick start section in [`README.md`](https://github.com/marin-community/marin/blob/main/README.md) (lines 14-16), the Marin repository supports two primary entry points for test execution: 1. **Focused testing** for rapid iteration on specific modules 2. **Full suite validation** using the repository-sanctioned wrapper script These commands rely on `uv` for environment management and enforce specific marker configurations to exclude expensive or destructive tests by default. ## Running Focused Tests During Development When iterating on a specific module, run targeted tests to receive immediate feedback without the overhead of the entire suite. This approach bypasses the default marker exclusions, allowing you to validate logic in isolation. Execute a single test file or directory: ```bash uv run pytest tests/unit/test_tokenizer.py ``` ```bash uv run pytest tests/unit/ ``` This command operates directly through `pytest` without the wrapper script, making it ideal for local development loops where you need fast confirmation of changes. ## Executing the Full Test Suite Safely To validate your changes against the repository-wide standards, use the dedicated wrapper script located at [`infra/ci/run_tests.py`](https://github.com/marin-community/marin/blob/main/infra/ci/run_tests.py). This script enforces the default marker set that excludes slow, integration, cluster, and Docker tests, and applies a **60-second per-test timeout** to prevent runaway processes. Run the full safe test suite: ```bash uv run --no-project infra/ci/run_tests.py ``` The `--no-project` flag ensures the script runs with the correct isolated environment as specified in the CI configuration. According to the source in [`infra/ci/run_tests.py`](https://github.com/marin-community/marin/blob/main/infra/ci/run_tests.py), this wrapper loads the appropriate `pytest` configuration and guarantees that only tests safe for general execution are included. ## Test Markers and Safety Policies The Marin repository defines strict testing guidelines in [`TESTING.md`](https://github.com/marin-community/marin/blob/main/TESTING.md) (lines 19-23) that govern which markers are excluded from the default run. The standard configuration filters out: - **slow** tests that consume excessive compute resources - **integration** tests requiring external services - **cluster** tests that interact with live infrastructure - **Docker** tests dependent on containerization **Never use custom `-m "not ..."` expressions** when invoking pytest directly. Overriding the marker defaults manually can inadvertently trigger live-cluster tests or other destructive workloads that the repository explicitly gates. The [`infra/ci/run_tests.py`](https://github.com/marin-community/marin/blob/main/infra/ci/run_tests.py) script exists precisely to prevent these accidents by codifying the safe marker profile. ## Module-Specific Overrides via AGENTS.md Individual modules within the repository may define localized testing policies or additional marker categories. These specifications reside in module-specific [`AGENTS.md`](https://github.com/marin-community/marin/blob/main/AGENTS.md) files, such as [`lib/iris/AGENTS.md`](https://github.com/marin-community/marin/blob/main/lib/iris/AGENTS.md). Before running tests with non-default markers (e.g., `-m "fast"` or `-m "slow"`), consult the relevant [`AGENTS.md`](https://github.com/marin-community/marin/blob/main/AGENTS.md) file for that directory. These documents provide explicit permission boundaries and command overrides that supersede general repository rules for their specific sub-projects. ## Advanced: Custom Timeouts and Marker Selection For tests that legitimately require longer execution times, you can override the default timeout on a per-command basis: ```bash uv run pytest tests/integration/test_training.py --timeout=300 ``` However, only extend timeouts or include restricted markers (like `slow` or `integration`) when explicitly instructed by a module's [`AGENTS.md`](https://github.com/marin-community/marin/blob/main/AGENTS.md) or a maintainer. The repository's testing policy treats unauthorized execution of expensive workloads as a safety violation. ## Summary - Use `uv run pytest ` for focused, rapid testing during active development - Use `uv run --no-project infra/ci/run_tests.py` to execute the full safe suite with default markers and 60-second timeouts - Avoid custom `-m` marker filters that override repository defaults, which risks triggering live-cluster tests - The default suite automatically excludes slow, integration, cluster, and Docker tests - Consult module-specific [`AGENTS.md`](https://github.com/marin-community/marin/blob/main/AGENTS.md) files before running tests with non-standard markers or timeouts ## Frequently Asked Questions ### What is the difference between running pytest directly and using run_tests.py? Running `uv run pytest` directly executes pytest with your current environment settings and does not apply the repository's default marker exclusions, making it suitable for targeted development but risky for broad test discovery. In contrast, `uv run --no-project infra/ci/run_tests.py` invokes a wrapper script that enforces the canonical marker configuration, timeouts, and safety filters defined in the repository testing policy, ensuring you never accidentally trigger destructive integration tests. ### Why does the Marin repository restrict custom marker expressions? Custom `-m "not ..."` expressions override the default marker exclusions defined in [`TESTING.md`](https://github.com/marin-community/marin/blob/main/TESTING.md) (lines 19-23), potentially allowing tests marked as `cluster`, `integration`, or `slow` to execute. These tests may interact with live infrastructure, consume expensive cloud resources, or modify persistent state. The restriction prevents developers from inadvertently running destructive workloads on their local machines or in shared CI environments. ### How do I run tests that are marked as slow or integration? You should only run tests marked as `slow`, `integration`, `cluster`, or `docker` when explicitly instructed by the module-specific [`AGENTS.md`](https://github.com/marin-community/marin/blob/main/AGENTS.md) file or by a project maintainer. These markers indicate workloads that require specific infrastructure, credentials, or resource allocations. If authorized, you may run them using `uv run pytest -m "slow"` or similar, but always verify against the local AGENTS.md documentation first. ### Where can I find module-specific testing instructions? Module-specific testing instructions, including permitted marker overrides and custom command variations, are documented in [`AGENTS.md`](https://github.com/marin-community/marin/blob/main/AGENTS.md) files located within individual library directories (for example, [`lib/iris/AGENTS.md`](https://github.com/marin-community/marin/blob/main/lib/iris/AGENTS.md)). These files provide the localized context necessary to safely run specialized tests within that sub-project's scope without violating repository-wide safety policies.