How to Run the Pytest Test Suite to Verify Agent-Reach Changes

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 or 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 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 file declares pytest>=8.0 as a development requirement alongside the core package.

pip install -e .

This command installs the agent-reach package and configures your environment with the exact test runner version specified in 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:

pytest tests/ -v

This invocation runs all test files under the tests/ directory, including test_cli.py, test_core.py, and 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.
• pytest tests/test_core.py – Exercises the routing engine in 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:

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 – Covers the command-line interface including the agent-reach doctor diagnostics and argument parsing logic.
• tests/test_core.py – Tests the routing engine that decides which backend to call for read or search requests.
• 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 – Confirms that configuration files parse correctly and that environment-variable overrides function as expected.
• tests/test_probe.py, tests/test_doctor.py, 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 file pins the exact pytest version (8.0.0) used in the GitHub Actions workflow.

pytest --version

The CI workflow defined in .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 and constraints.txt.
• Execute: Run pytest tests/ -v for the full suite, or target specific files like tests/test_cli.py for focused validation.
• Validate: The suite covers CLI logic (agent_reach/cli.py), core routing (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.

Where does the CI workflow define the test execution?

The GitHub Actions workflow is defined in .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, guaranteeing the test runner matches the project's requirements.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}