pytest markers and updated markdowns

Author: SidRichardsQuantum

CHANGELOG.md

@@ -8,6 +8,12 @@ All notable changes to this project will be documented in this file.
 
 ### Changed
 
+- **Faster default pytest target**
+
+  Marked slow chemistry and subprocess CLI integration tests separately so
+  `pytest -q` runs the fast development suite by default. The full integration
+  suite remains available with `pytest -q -o addopts=''`.
+
 - **Tightened public API reference**
 
   Reworked the Sphinx API reference into task-oriented sections for primary

README.md

@@ -401,10 +401,19 @@ Variational_Quantum_Eigensolver/
 
 ## Testing
 
+The default pytest target is the fast development suite. Slow chemistry and
+subprocess CLI integration tests are marked separately.
+
 ```bash
 pytest -q
 ```
 
+Run the full suite, including slow integration coverage, with:
+
+```bash
+pytest -q -o addopts=''
+```
+
 ---
 
 ## Support development

USAGE.md

@@ -850,10 +850,19 @@ qite run-qrte --force
 
 ## Testing
 
+The default pytest target runs the fast development suite. Slow chemistry and
+subprocess CLI integration tests are available behind pytest markers.
+
 ```bash
 pytest -q
 ```
 
+Run every test, including slow integration coverage:
+
+```bash
+pytest -q -o addopts=''
+```
+
 ---
 
 ## Citation

pyproject.toml

@@ -53,6 +53,13 @@ docs = [
 ]
 
 [tool.pytest.ini_options]
+addopts = "-m 'not slow'"
+markers = [
+  "slow: tests that are useful integration coverage but too expensive for the default PR loop",
+  "chemistry: tests that build real chemistry Hamiltonians or invoke expensive quantum chemistry backends",
+  "full_chemistry: broad chemistry coverage across many registered molecules",
+  "cli_subprocess: tests that validate python -m entrypoints in a separate interpreter",
+]
 filterwarnings = [
   "error::pennylane.exceptions.PennyLaneDeprecationWarning",
   "error::DeprecationWarning",

qpe/__main__.py

@@ -87,7 +87,7 @@ def _validated_geometry_inputs(
 # ---------------------------------------------------------------------
 # Arguments
 # ---------------------------------------------------------------------
-def parse_args():
+def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="qpe",
         description="Quantum Phase Estimation (QPE) simulator",
@@ -223,14 +223,18 @@ def parse_args():
         "--force", action="store_true", help="Force rerun even if cached result exists"
     )
 
-    return parser.parse_args()
+    return parser
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    return build_parser().parse_args(argv)
 
 
 # ---------------------------------------------------------------------
 # Main logic
 # ---------------------------------------------------------------------
-def main():
-    args = parse_args()
+def main(argv: list[str] | None = None):
+    args = parse_args(argv)
     ensure_dirs()
     symbols, coordinates = _validated_geometry_inputs(args)
     molecule_label = (

tests/test_cli_help.py

@@ -3,6 +3,10 @@
 import subprocess
 import sys
 
+import pytest
+
+import qite.__main__ as qite_main
+import qpe.__main__ as qpe_main
 import vqe.__main__ as vqe_main
 
 
@@ -16,22 +20,20 @@ def _run_help(module: str) -> subprocess.CompletedProcess[str]:
     )
 
 
-def test_vqe_cli_help() -> None:
-    p = _run_help("vqe")
-    assert p.returncode == 0
-    out = (p.stdout or "") + (p.stderr or "")
-    assert "usage" in out.lower()
-
-
-def test_qpe_cli_help() -> None:
-    p = _run_help("qpe")
-    assert p.returncode == 0
-    out = (p.stdout or "") + (p.stderr or "")
+@pytest.mark.parametrize(
+    "build_parser",
+    [vqe_main.build_parser, qpe_main.build_parser, qite_main.build_parser],
+)
+def test_cli_help_is_available_in_process(build_parser) -> None:
+    out = build_parser().format_help()
     assert "usage" in out.lower()
 
 
-def test_qite_cli_help() -> None:
-    p = _run_help("qite")
+@pytest.mark.slow
+@pytest.mark.cli_subprocess
+@pytest.mark.parametrize("module", ["vqe", "qpe", "qite"])
+def test_module_cli_help(module: str) -> None:
+    p = _run_help(module)
     assert p.returncode == 0
     out = (p.stdout or "") + (p.stderr or "")
     assert "usage" in out.lower()
@@ -48,13 +50,7 @@ def fake_run_vqe(**kwargs):
         return {"energy": -1.0, "energies": [-1.0], "num_qubits": 1}
 
     monkeypatch.setattr(vqe_main, "run_vqe", fake_run_vqe)
-    monkeypatch.setattr(
-        sys,
-        "argv",
-        ["vqe", "--molecule", "H2", "--steps", "1", "--force"],
-    )
-
-    vqe_main.main()
+    vqe_main.main(["--molecule", "H2", "--steps", "1", "--force"])
     out = capsys.readouterr().out
 
     assert captured["stepsize"] is None

tests/test_hamiltonian.py

@@ -6,6 +6,51 @@
 from common.molecules import get_molecule_config
 from common.units import ANGSTROM_PER_BOHR
 
+REPRESENTATIVE_REGISTRY_MOLECULES = [
+    "H",
+    "H2",
+    "H2+",
+    "H3+",
+    "Li",
+    "He",
+    "HeH+",
+]
+
+FULL_REGISTRY_MOLECULES = [
+    "H",
+    "H-",
+    "He",
+    "He+",
+    "H2",
+    "H2+",
+    "H2-",
+    "H3",
+    "H3+",
+    "Li",
+    "Li+",
+    "B",
+    "B+",
+    "C",
+    "C+",
+    "N",
+    "N+",
+    "O",
+    "O+",
+    "F",
+    "F+",
+    "Ne",
+    "H4",
+    "H4+",
+    "Be",
+    "Be+",
+    "He2",
+    "H5+",
+    "H6",
+    "LiH",
+    "BeH2",
+    "HeH+",
+]
+
 
 def test_build_hamiltonian_h2() -> None:
     cfg = get_molecule_config("H2")
@@ -20,47 +65,27 @@ def test_build_hamiltonian_h2() -> None:
     assert all(hasattr(op, "wires") for op in ops)
 
 
-def test_build_hamiltonian_selected_registry_molecules() -> None:
-    for name in [
-        "H",
-        "H-",
-        "He",
-        "He+",
-        "H2",
-        "H2+",
-        "H2-",
-        "H3",
-        "H3+",
-        "Li",
-        "Li+",
-        "B",
-        "B+",
-        "C",
-        "C+",
-        "N",
-        "N+",
-        "O",
-        "O+",
-        "F",
-        "F+",
-        "Ne",
-        "H4",
-        "H4+",
-        "Be",
-        "Be+",
-        "He2",
-        "H5+",
-        "H6",
-        "LiH",
-        "BeH2",
-        "HeH+",
-    ]:
-        cfg = get_molecule_config(name)
-        hamiltonian, n_qubits, hf_state = build_hamiltonian(**cfg)
-
-        assert n_qubits > 0
-        assert len(hf_state) == n_qubits
-        assert len(hamiltonian) > 0
+@pytest.mark.parametrize("name", REPRESENTATIVE_REGISTRY_MOLECULES)
+def test_build_hamiltonian_representative_registry_molecules(name: str) -> None:
+    cfg = get_molecule_config(name)
+    hamiltonian, n_qubits, hf_state = build_hamiltonian(**cfg)
+
+    assert n_qubits > 0
+    assert len(hf_state) == n_qubits
+    assert len(hamiltonian) > 0
+
+
+@pytest.mark.slow
+@pytest.mark.chemistry
+@pytest.mark.full_chemistry
+@pytest.mark.parametrize("name", FULL_REGISTRY_MOLECULES)
+def test_build_hamiltonian_full_registry_molecules(name: str) -> None:
+    cfg = get_molecule_config(name)
+    hamiltonian, n_qubits, hf_state = build_hamiltonian(**cfg)
+
+    assert n_qubits > 0
+    assert len(hf_state) == n_qubits
+    assert len(hamiltonian) > 0
 
 
 def test_registry_mode_rejects_basis_and_charge_overrides() -> None:
@@ -162,6 +187,8 @@ def test_summarize_registry_coverage_returns_expected_rows() -> None:
     assert "exact_ground_energy" in h2_row
 
 
+@pytest.mark.slow
+@pytest.mark.chemistry
 def test_active_space_reduces_lih_qubit_count() -> None:
     full_hamiltonian, full_qubits, full_hf = build_hamiltonian(molecule="LiH")
     active_hamiltonian, active_qubits, active_hf = build_hamiltonian(

tests/test_qpe_smoke.py

@@ -8,6 +8,7 @@
 import numpy as np
 
 from common.hamiltonian import build_hamiltonian
+import qpe.__main__ as qpe_main
 from qpe import run_qpe
 from qpe.visualize import plot_qpe_distribution
 
@@ -189,12 +190,23 @@ def test_qpe_distribution_displays_right_to_left_kets(monkeypatch) -> None:
     assert labels == ["|00⟩", "|01⟩", "|10⟩", "|11⟩"]
 
 
-def test_qpe_cli_supports_explicit_geometry() -> None:
-    p = subprocess.run(
+def test_qpe_cli_supports_explicit_geometry(monkeypatch, capsys) -> None:
+    captured: dict[str, object] = {}
+
+    def fake_run_qpe(**kwargs):
+        captured.update(kwargs)
+        return {
+            "best_bitstring": "0",
+            "energy": -1.0,
+            "hf_energy": -0.9,
+            "num_qubits": 4,
+        }
+
+    monkeypatch.setattr(qpe_main, "ensure_dirs", lambda: None)
+    monkeypatch.setattr(qpe_main, "run_qpe", fake_run_qpe)
+
+    qpe_main.main(
         [
-            sys.executable,
-            "-m",
-            "qpe",
             "--symbols",
             "H,H",
             "--coordinates",
@@ -208,18 +220,27 @@ def test_qpe_cli_supports_explicit_geometry() -> None:
             "--shots",
             "50",
             "--force",
-        ],
-        check=False,
-        capture_output=True,
-        text=True,
-        timeout=20,
+        ]
     )
+    out = capsys.readouterr().out
 
-    assert p.returncode == 0
-    assert "QPE completed" in p.stdout
-    assert "system=4, ancillas=1" in p.stdout
+    assert captured["molecule"] == "H2"
+    assert captured["symbols"] == ["H", "H"]
+    assert np.array_equal(
+        captured["coordinates"],
+        np.array([[0.0, 0.0, 0.0], [0.0, 0.0, 0.7]], dtype=float),
+    )
+    assert captured["charge"] == 0
+    assert captured["basis"] == "sto-3g"
+    assert captured["n_ancilla"] == 1
+    assert captured["shots"] == 50
+    assert captured["force"] is True
+    assert "QPE completed" in out
+    assert "system=4, ancillas=1" in out
 
 
+@pytest.mark.slow
+@pytest.mark.cli_subprocess
 def test_qpe_cli_returns_nonzero_on_failure() -> None:
     p = subprocess.run(
         [sys.executable, "-m", "qpe", "--molecule", "DOES_NOT_EXIST"],

vqe/__main__.py

@@ -586,7 +586,7 @@ def handle_special_modes(args) -> bool:
 # ================================================================
 # MAIN ENTRYPOINT
 # ================================================================
-def main() -> None:
+def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="vqe",
         description="VQE / SSVQE / VQD Simulation Toolkit",
@@ -951,7 +951,12 @@ def main() -> None:
     misc.add_argument("--force", action="store_true", help="Ignore cached results")
     misc.add_argument("--plot", action="store_true", help="Plot convergence")
 
-    args = parser.parse_args()
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
     symbols, coordinates = _validated_geometry_inputs(args)
     explicit_geometry = symbols is not None and coordinates is not None