# How to Run the Pytest Test Suite to Verify Agent-Reach Changes > Verify Agent-Reach changes by running the pytest test suite. Install in editable mode and execute `pytest tests/ -v` to ensure your modifications are correct. - Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach) - Tags: testing - Published: 2026-07-03 --- **Run `pytest tests/ -v` after installing the package in editable mode with `pip install -e .` to execute the full Agent-Reach test suite.** Agent-Reach ships with a comprehensive pytest test suite that validates the CLI, core routing logic, and platform-specific channel integrations. Running the pytest test suite to verify Agent-Reach changes ensures that modifications to [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) or [`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py) do not break existing functionality across the supported channels. The repository requires **Python 3.10+** and pins **pytest 8.0** in [`constraints.txt`](https://github.com/Panniantong/Agent-Reach/blob/main/constraints.txt) to guarantee consistent results across local and CI environments. ## Prerequisites and Environment Setup ### Python Version Requirements The project strictly targets **Python 3.10 or higher**, as documented in the Quick-Start section of the README. Attempting to run the suite on older versions will result in dependency resolution failures or syntax errors due to modern language features used throughout the codebase. ### Install in Editable Mode Before running tests, install the package in editable mode to link the source code and pull development dependencies. The [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml) file declares `pytest>=8.0` as a development requirement alongside the core package. ```bash pip install -e . ``` This command installs the `agent-reach` package and configures your environment with the exact test runner version specified in [`constraints.txt`](https://github.com/Panniantong/Agent-Reach/blob/main/constraints.txt). ## Executing the Pytest Test Suite ### Run the Full Test Suite To execute every test module with verbose output, run the canonical command from the repository root: ```bash pytest tests/ -v ``` This invocation runs all test files under the `tests/` directory, including [`test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/test_cli.py), [`test_core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/test_core.py), and [`test_channel_contracts.py`](https://github.com/Panniantong/Agent-Reach/blob/main/test_channel_contracts.py), providing detailed pass/fail information for each test case. ### Run Specific Test Categories For rapid feedback during iterative development, target specific test files rather than the entire suite: - **`pytest tests/test_cli.py -v`** – Validates argument parsing, error handling, and the `agent-reach doctor` diagnostics command defined in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py). - **`pytest tests/test_core.py`** – Exercises the routing engine in [`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py) that determines which backend to invoke for a given URL or query. - **`pytest tests/test_channel_contracts.py -q`** – Verifies that every channel implements the required interface methods: `can_handle`, `read`, `search`, and `check`. ### Debug Individual Test Failures When troubleshooting a specific failure, re-run the exact test with maximum verbosity: ```bash pytest tests/test_cli.py::TestCli::test_help -vv ``` ## Understanding the Test Structure The pytest suite validates multiple architectural layers according to the following mapping: - **[`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py)** – Covers the command-line interface including the `agent-reach doctor` diagnostics and argument parsing logic. - **[`tests/test_core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_core.py)** – Tests the routing engine that decides which backend to call for read or search requests. - **[`tests/test_channel_contracts.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_channel_contracts.py)** – Ensures every channel implements the required contract methods (`can_handle`, `read`, `search`, `check`). - **`tests/test_*_channel.py`** – Contains platform-specific sanity checks for integrations like Twitter, Reddit, and YouTube. - **[`tests/test_config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_config.py)** – Confirms that configuration files parse correctly and that environment-variable overrides function as expected. - **[`tests/test_probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_probe.py)**, **[`tests/test_doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_doctor.py)**, **[`tests/test_transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_transcribe.py)** – Cover auxiliary utilities, health-check diagnostics, and the optional transcription feature. ## CI Verification and Version Constraints Ensure your local environment matches the continuous integration pipeline. The [`constraints.txt`](https://github.com/Panniantong/Agent-Reach/blob/main/constraints.txt) file pins the exact pytest version (8.0.0) used in the GitHub Actions workflow. ```bash pytest --version ``` The CI workflow defined in [`.github/workflows/pytest.yml`](https://github.com/Panniantong/Agent-Reach/blob/main/.github/workflows/pytest.yml) executes `pytest -q` on each push to validate that changes do not introduce regressions across CLI, core, or channel layers. ## Summary - **Install**: Use `pip install -e .` to install Agent-Reach in editable mode with `pytest>=8.0` and all development dependencies. - **Version**: Verify Python 3.10+ and pytest 8.0+ are installed according to [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml) and [`constraints.txt`](https://github.com/Panniantong/Agent-Reach/blob/main/constraints.txt). - **Execute**: Run `pytest tests/ -v` for the full suite, or target specific files like [`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py) for focused validation. - **Validate**: The suite covers CLI logic ([`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)), core routing ([`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py)), channel contracts, and platform-specific integrations. ## Frequently Asked Questions ### What Python version is required to run Agent-Reach tests? The test suite requires **Python 3.10 or higher**, as specified in the Quick-Start section of the README. Older versions may fail due to dependency conflicts or modern syntax features used in the codebase. ### How do I run only the CLI tests after modifying the command-line interface? Execute `pytest tests/test_cli.py -v` to run only the CLI validation tests. This file specifically exercises the argument parsing and the `agent-reach doctor` command implemented in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py). ### Where does the CI workflow define the test execution? The GitHub Actions workflow is defined in [`.github/workflows/pytest.yml`](https://github.com/Panniantong/Agent-Reach/blob/main/.github/workflows/pytest.yml). It runs `pytest -q` on each push to ensure all changes pass the automated test suite before merging. ### Why should I install the package in editable mode before testing? Installing with `pip install -e .` ensures that the `agent-reach` package is linked to your live source code changes and pulls in the `pytest>=8.0` dependency declared in [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml), guaranteeing the test runner matches the project's requirements.