revitdevtool-pytest 0.3.0__tar.gz → 0.4.0__tar.gz

{revitdevtool_pytest-0.3.0 → revitdevtool_pytest-0.4.0}/.gitignore

@@ -16,3 +16,4 @@ build/
 venv/
 .idea/
 .gitnexus
+.cocoindex_code/

revitdevtool_pytest-0.4.0/.run/Attach.run.xml

@@ -0,0 +1,8 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Attach Host: Python" type="PythonDapAttachConfiguration">
+    <option name="localRoot" value="$PROJECT_DIR$" />
+    <option name="remoteAddress" value="localhost:5678" />
+    <option name="remoteRoot" value="$PROJECT_DIR$" />
+    <method v="2" />
+  </configuration>
+</component>

{revitdevtool_pytest-0.3.0 → revitdevtool_pytest-0.4.0}/.vscode/settings.json

@@ -21,5 +21,5 @@
     ],
     "basedpyright.importStrategy": "useBundled",
     "basedpyright.analysis.typeCheckingMode": "off",
-    "python.testing.pytestEnabled": true,
+    "python.testing.pytestEnabled": true
 }

revitdevtool_pytest-0.4.0/AGENTS.md

@@ -0,0 +1,202 @@
+# AGENTS
+
+## Overview
+
+pytest client plugin for [RevitDevTool](https://github.com/trgiangv/RevitDevTool). Collects tests locally, executes them inside a live host via Named Pipe JSON-RPC (`BridgeMessage` framing).
+
+**Supported today:** **Revit** and **AutoCAD family** (AutoCAD, Civil 3D, Plant 3D, Architecture / Mechanical / MEP / Electrical / Map 3D). Other hosts may appear in the registry but are **in progress** — not validated end-to-end yet.
+
+**Package:** `revitdevtool_pytest` (PyPI) · **Entry point:** `revitdevtool` · **Version:** see `pyproject.toml`
+
+## Architecture
+
+```mermaid
+flowchart LR
+    Collect[Local collect] --> Pipe["DevTools_*"]
+    Pipe --> CPython[PytestRunner.py]
+    Pipe --> IPy[IpyTestDriver.py]
+    CPython --> Report[Local report]
+    IPy --> Report
+```
+
+Do **not** connect to `DevToolsMcp_*` (MCP SDK). Pytest uses `DevTools_{Host}_{Version}_{PID}` on `DevToolsPipeServer`.
+
+### Client modules (`src/revitdevtool_pytest/`)
+
+| Module | Role |
+|--------|------|
+| `plugin.py` | Hook orchestrator — lifecycle, options, bridge setup |
+| `ipy_collect.py` | Pytest collect convention `test_*_ipy.py` → `ipytests/run` (no CPython import) |
+| `connection.py` | Discover, connect, lease, launch, retry |
+| `bridge.py` | Named Pipe framing, `tests/run` / `ipytests/run` RPC |
+| `discovery.py` | Pipe scan, host registry, process launch |
+| `reporting.py` | Remote `CaseResult` → pytest `TestReport` |
+| `suite_leasing.py` | File-based suite → host PID allocation |
+| `suite_lock.py` | Windows mutex — same suite, one pytest process |
+| `dialog_resolver.py` | Auto-dismiss host startup dialogs (Win32) |
+| `models.py` | Wire models (mirror C# `PytestContracts`) |
+| `constants.py` | Options, host registry, pipe pattern |
+
+### Host-side (RevitDevTool repo)
+
+| Location | Role |
+|----------|------|
+| `DevTools.Execution/External/DevToolsPipeServer.cs` | Pytest/control pipe server |
+| `DevTools.Execution/External/Handlers/PytestRequestHandler.cs` | Routes `tests/run` |
+| `DevTools.Execution/External/Handlers/IpyTestRequestHandler.cs` | Routes `ipytests/run` |
+| `DevTools.Execution/External/Testing/` | `PytestExecutionService`, `IpyTestExecutionService`, `PytestContracts` |
+| `DevTools.Execution/Resources/scripts/PytestRunner.py` | In-host `pytest.main()` runner |
+| `DevTools.Execution/Resources/scripts/IpyTestDriver.py` | In-host IronPython test driver (2.7 / 3.4) |
+
+Wire methods: `tests/run` (CPython pytest), `ipytests/run` (IronPython unittest, pyRevit-first). Progress notifications: `notifications/tests/progress`.
+
+**IPy collect convention is `test_*_ipy.py`** (pytest `test_` + `_ipy` marker). That name is only how the plugin routes onto `ipytests/run`; the host runs unittest on the requested paths and does not require it. Dialect: 2.7 / 3.4, `unittest.TestCase`, no pytest fixtures / PEP 723 (CPython `tests/run` still installs `# /// script` via pixi). `*_ipy_script.py` is execution-tree script, not a test file. Library modules use normal names (`ipylib/geom.py`).
+
+## This repo layout
+
+Integration tests for the plugin — not shipped in the wheel.
+
+```
+tests/
+  plugin/                # local plugin unit tests (no host); sets REVITDEVTOOL_PYTEST_DISABLE
+  Revit/                 # default testpaths in pyproject.toml
+    conftest.py          # PEP 723 deps (CPython tests/run only), revit_doc, rollback fixtures
+    schedule/            # shared schedule helpers (import as schedule.*)
+    test_*.py            # CPython pytest → tests/run
+    test_*_ipy.py        # mixed-tree IronPython unittest → ipytests/run
+  Revit_Ipy/             # IPy libs + more test_*_ipy.py (folder is not identity)
+    ipylib/              # 2.7/3.4 helpers imported by tests
+    test_*_ipy.py
+  Civil3d/
+    conftest.py          # acad_app, acad_doc, transaction fixtures
+    test_*.py
+```
+
+Switch suites via `pyproject.toml`:
+
+```toml
+testpaths = ["tests/Revit"]   # or tests/Civil3d
+host_name = "revit"           # or civil3d, autocad, …
+host_version = "2025"
+```
+
+Schedule helpers live under `tests/Revit/schedule/`. Imports use the `schedule` package name (e.g. `from schedule.constants import …`), with `pythonpath = ["tests/Revit"]` in `pyproject.toml`.
+
+`revit_doc` opens `REVIT_TEST_MODEL_PATH` (default `F:\Project1.rvt`) when set.
+
+## Host support
+
+### Supported (tested)
+
+| Host Name | Pipe Prefix | Executable | Product ID |
+|-----------|------------|------------|------------|
+| `revit` | `Revit` | `Revit.exe` | — |
+| `autocad` | `AutoCad` | `acad.exe` | `01` |
+| `civil3d` | `Civil3D` | `acad.exe` | `00` |
+| `plant3d` | `Plant3D` | `acad.exe` | `17` |
+| `acadarch` | `AcadArch` | `acad.exe` | `04` |
+| `acadmech` | `AcadMech` | `acad.exe` | `05` |
+| `acadmep` | `AcadMep` | `acad.exe` | `06` |
+| `acadelec` | `AcadElec` | `acad.exe` | `07` |
+| `acadmap3d` | `AcadMap3D` | `acad.exe` | `02` |
+
+### In progress (not supported yet)
+
+| Host Name | Pipe Prefix | Notes |
+|-----------|------------|--------|
+| `navisworks` | `Navisworks` | Registry stub only |
+| `rhino` | `Rhino` | Registry stub only |
+| `tekla` | `Tekla` | Registry stub only |
+
+Unknown host names still get a fallback `HostConfig(pipe_prefix=host_name)` for experimentation, but are not supported. Do not document or rely on them until promoted to **Supported**.
+
+### Pipe format
+
+`DevTools_{Host}_{Version}_{PID}` — regex `^DevTools_\w+_[^_]+_\d+$`
+
+Examples: `DevTools_Revit_2025_12345`, `DevTools_AutoCad_2026_7890`
+
+## Key design decisions
+
+- **Dual pytest model:** collect locally, execute in-host (IDE tree + host thread).
+- **`--capture=sys`:** required in embedded Python.NET (no fd-level `dup2`).
+- **`sys.__pytest_running__`:** set by `PytestRunner.py`; setup scripts skip I/O hijack during runs.
+- **Streaming vs batch:** CLI streams progress; IDE adapters (`vscode_pytest`, `TEST_RUN_PIPE`) get one batch.
+- **Suite leasing + mutex:** one pytest process per host+version+workspace; CPython and IronPython tests in that workspace reuse the same host PID. One invocation still cannot mix two `conftest.py` trees — run `tests/Revit` then `tests/Revit_Ipy` separately (same Revit). Mixed `test_*.py` + `test_*_ipy.py` under one conftest is fine (`tests/run` then `ipytests/run` on the same pipe).
+- **`force_launch`:** force new host + wait for that PID's pipe; skip reuse.
+- **No matching instance:** after discovery fails, plugin auto-launches when `host_version` is set.
+
+## Running tests
+
+Always **`uv run pytest`** from this repo root — do not use system Python or bare `pytest`.
+
+```powershell
+cd c:\Users\truon\source\repos\RevitDevTool.PyTest
+uv run pytest -v
+uv run pytest tests/Revit/test_active_state.py::test_active_view_info -v
+uv run pytest --host-version=2025 -v
+uv run pytest --host autocad --host-version 2026 -v
+uv run pytest --force-launch --host-version=2025 -v
+uv run pytest tests/Revit_Ipy -v --host-version=2025
+```
+
+Plugin auto-enables `-rP` (stdout for passing tests).
+
+## Configuration
+
+`[tool.pytest.ini_options]` in `pyproject.toml`:
+
+```toml
+testpaths = ["tests/Revit"]
+pythonpath = ["tests/Revit"]
+host_name = "revit"
+host_version = "2025"
+force_launch = false
+per_test_timeout = "60"
+launch_timeout = "180"
+host_pipe = ""
+```
+
+CLI: `--host`, `--host-version`, `--per-test-timeout`, `--host-pipe`, `--force-launch`, `--launch-timeout`.
+
+## Fixtures pattern
+
+```python
+# conftest.py (Revit)
+@pytest.fixture(scope="session")
+def revit_uiapp():
+    return __revit__  # noqa: F821
+
+@pytest.fixture(scope="session")
+def revit_doc(revit_uiapp):
+    return revit_uiapp.ActiveUIDocument.Document
+
+@pytest.fixture
+def revit_auto_rollback(revit_transaction_service):
+    revit_transaction_service.StartChanges()
+    try:
+        yield revit_transaction_service
+    finally:
+        revit_transaction_service.RevertChanges()
+```
+
+Host API imports belong **inside test bodies** (or fixture bodies), not at module top level.
+
+## Common traps
+
+- Tests run **inside the host**, not locally.
+- `__revit__` only exists at runtime — use fixtures.
+- Host APIs need the main thread; execution is sequential via `IHostContextExecutor`.
+- Pytest pipe ≠ MCP pipe (`DevTools_*` vs `DevToolsMcp_*`).
+- PEP 723 deps in CPython `conftest.py` / `test_*.py` are installed by `PytestDependencyService` before `tests/run`. **IronPython `test_*_ipy.py` does not use PEP 723** — `ipytests/run` never calls that service; IPy 2.7/3.4 cannot import CPython wheels.
+- `--force-launch` requires `--host-version`.
+- `print()` captured via `--capture=sys` → `CaseResult.stdout`.
+- IronPython tests: no pytest fixtures; **no PEP 723**; host APIs inside methods; `test_*_ipy.py` is pytest routing only, not a host filename contract.
+
+## Change rules
+
+- Wire protocol: sync `models.py` ↔ `PytestContracts.cs` / `PytestBridgeMethods.cs`.
+- New CLI options: `pytest_addoption` + `parser.addini`.
+- `connection.py` stays stateless; only `plugin.py` holds session globals.
+- After connection/discovery changes: test `force_launch = true` and `false`.
+- `HOST_REGISTRY` ↔ C# `HostApp` enum + `AcadPathResolver.ProductIdMap`.

{revitdevtool_pytest-0.3.0 → revitdevtool_pytest-0.4.0}/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.4.0] - 2026-08-31
+
+### Added
+
+- IronPython tests: files named `test_*_ipy.py` run on the host via `ipytests/run`
+  (`unittest`). CPython `test_*.py` still uses `tests/run`.
+- CPython and IronPython suites in the same workspace reuse one host instance.
+
+### Changed
+
+- Pipe name is `DevTools_{Host}_{Version}_{PID}` (was `{Host}_{Version}_{PID}`).
+  Pytest does not use the MCP pipe `DevToolsMcp_*`.
+- CLI/INI names match RevitDevTool.TestAdapter (breaking vs 0.3.0):
+  `--host-launch` → `--force-launch`, `--host-timeout` → `--per-test-timeout`,
+  `--host-launch-timeout` → `--launch-timeout`. `--host` / `--host-version` unchanged.
+- PEP 723 `# /// script` is installed only for CPython `tests/run`. IronPython
+  tests cannot use CPython wheels.
+
 ## [0.3.0] - 2026-05-31
 
 ### Added

revitdevtool_pytest-0.4.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.5
+Name: revitdevtool_pytest
+Version: 0.4.0
+Summary: pytest plugin for testing CAD/BIM API code inside host applications via RevitDevTool Named Pipe bridge
+Project-URL: Homepage, https://github.com/trgiangv/RevitDevTool.PyTest
+Project-URL: Repository, https://github.com/trgiangv/RevitDevTool.PyTest
+Project-URL: Issues, https://github.com/trgiangv/RevitDevTool.PyTest/issues
+Author: Truong Giang Vu
+License-Expression: MIT
+License-File: LICENSE
+Keywords: autocad,bim,civil3d,multi-host,pytest,revit,revit-api,revitdevtool,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: pytest>=9.0
+Requires-Dist: pywin32>=311
+Description-Content-Type: text/markdown
+
+# RevitDevTool.PyTest
+
+[![PyPI version](https://img.shields.io/pypi/v/revitdevtool_pytest)](https://pypi.org/project/revitdevtool-pytest/)
+[![Python](https://img.shields.io/pypi/pyversions/revitdevtool_pytest)](https://pypi.org/project/revitdevtool-pytest/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+pytest plugin for testing CAD/BIM API code inside live host applications via the RevitDevTool Named Pipe bridge.
+
+Write tests locally with pytest; execution happens inside the host process. **Currently supported:** **Revit** and **AutoCAD family** only. Navisworks, Rhino, Tekla, and other hosts are **in progress**.
+
+## Installation
+
+```bash
+pip install revitdevtool_pytest
+# or
+uv add revitdevtool_pytest
+```
+
+| Requirement | Version |
+|---|---|
+| Python | >= 3.10 |
+| pytest | >= 9.0 |
+| pywin32 | >= 311 |
+| OS | Windows (Named Pipes) |
+| Host | [RevitDevTool](https://github.com/trgiangv/RevitDevTool) add-in loaded |
+
+## Supported hosts
+
+### Supported today
+
+| `host_name` | Application | Pipe prefix |
+|---|---|---|
+| `revit` | Autodesk Revit | `Revit` |
+| `autocad` | AutoCAD | `AutoCad` |
+| `civil3d` | Civil 3D | `Civil3D` |
+| `plant3d` | Plant 3D | `Plant3D` |
+| `acadarch` | AutoCAD Architecture | `AcadArch` |
+| `acadmech` | AutoCAD Mechanical | `AcadMech` |
+| `acadmep` | AutoCAD MEP | `AcadMep` |
+| `acadelec` | AutoCAD Electrical | `AcadElec` |
+| `acadmap3d` | AutoCAD Map 3D | `AcadMap3D` |
+
+### In progress
+
+| `host_name` | Application | Status |
+|---|---|---|
+| `navisworks` | Navisworks | Not validated |
+| `rhino` | Rhino | Not validated |
+| `tekla` | Tekla Structures | Not validated |
+
+The plugin registry may list additional names for future work. Treat them as experimental until documented here as **Supported today**.
+
+### Pipe names (pytest only)
+
+The plugin connects to the **pytest/control** pipe:
+
+`DevTools_{Host}_{Version}_{PID}`
+
+Examples: `DevTools_Revit_2025_12345`, `DevTools_AutoCad_2026_7890`
+
+MCP clients use a separate pipe: `DevToolsMcp_{Host}_{Version}_{PID}`. Do not point pytest at an MCP pipe.
+
+## Quick start (consumer project)
+
+```bash
+uv init my-host-tests && cd my-host-tests
+uv add revitdevtool_pytest pytest
+```
+
+`pyproject.toml`:
+
+```toml
+[tool.pytest.ini_options]
+host_name = "revit"
+host_version = "2025"
+force_launch = false
+per_test_timeout = "60"
+launch_timeout = "180"
+```
+
+`tests/conftest.py`:
+
+```python
+import pytest
+
+@pytest.fixture(scope="session")
+def revit_uiapp():
+    return __revit__
+
+@pytest.fixture(scope="session")
+def revit_doc(revit_uiapp):
+    return revit_uiapp.ActiveUIDocument.Document
+```
+
+`tests/test_smoke.py`:
+
+```python
+def test_active_view(revit_doc):
+    assert revit_doc.ActiveView is not None
+```
+
+```bash
+uv run pytest -v
+```
+
+## Configuration
+
+| Option | Default | Description |
+|---|---|---|
+| `host_name` | `"revit"` | Target host — use **Supported today** names only. |
+| `host_version` | — | Version string (`"2025"`, `"8.0"`, …). Required for launch. |
+| `force_launch` | `false` | Force a **new** host instance (skip reuse). Requires `host_version`. |
+| `per_test_timeout` | `"60"` | Per-test budget (seconds). The `tests/run` pipe wait is this × collected tests. |
+| `launch_timeout` | `"180"` | Wait for host pipe after launch (seconds). |
+| `host_pipe` | — | Explicit pipe name (skip discovery). |
+
+CLI flags override INI: `--host`, `--host-version`, `--force-launch`, `--per-test-timeout`, `--launch-timeout`, `--host-pipe`.
+
+### Connection behavior
+
+1. **`force_launch = false` (default):** scan for `DevTools_*` pipes matching `host_name` / `host_version`, reuse a free instance (suite leasing), or reconnect to a leased PID.
+2. **No matching instance:** auto-launch host when `host_version` is set (unless `--host-pipe` pins an existing pipe).
+3. **`force_launch = true`:** always spawn a new process and wait for its pipe.
+
+### Print output
+
+Captured `print()` from in-host tests is shown for passing tests (same as `-rP`). No extra flags needed.
+
+## Writing tests
+
+- Put **host API imports inside functions** — collection runs on your machine, execution in the host.
+- Use fixtures for `__revit__`, documents, and rollback helpers.
+- Declare suite dependencies with **PEP 723** in CPython `conftest.py` (or `test_*.py`); RevitDevTool installs them before `tests/run`. IronPython `test_*_ipy.py` **does not** use PEP 723 — `ipytests/run` never installs packages.
+
+```python
+# /// script
+# dependencies = ["numpy>=2.0", "polars>=1.0"]
+# ///
+```
+
+### Revit rollback fixture
+
+```python
+@pytest.fixture
+def revit_auto_rollback(revit_transaction_service):
+    revit_transaction_service.StartChanges()
+    try:
+        yield revit_transaction_service
+    finally:
+        revit_transaction_service.RevertChanges()
+```
+
+## How it works
+
+1. Local pytest collects tests.
+2. Plugin connects to `DevTools_{Host}_{Version}_{PID}`.
+3. Node IDs sent via JSON-RPC method `tests/run` (`BridgeMessage` length-prefixed frames).
+4. Host runs `PytestRunner.py` embedded in RevitDevTool (`PytestExecutionService` on main thread).
+5. Results and optional progress notifications return to the client.
+6. Plugin maps `CaseResult` → standard pytest reports.
+
+## Developing this repository
+
+Clone and run integration tests against a live host:
+
+```powershell
+cd RevitDevTool.PyTest
+uv run pytest -v                          # Revit suite (default)
+uv run pytest tests/Revit/test_smoke.py -v
+uv run pytest --host civil3d --host-version 2026  # after switching testpaths/host in pyproject.toml
+```
+
+### Layout
+
+| Path | Purpose |
+|---|---|
+| `src/revitdevtool_pytest/` | Plugin source (published wheel) |
+| `tests/Revit/` | Revit integration tests + `schedule/` helpers |
+| `tests/Civil3d/` | Civil 3D / AutoCAD API tests |
+
+Revit suite settings in `pyproject.toml`: `testpaths = ["tests/Revit"]`, `pythonpath = ["tests/Revit"]` for local `schedule` imports.
+
+Optional env: `REVIT_TEST_MODEL_PATH` — path to `.rvt` for `revit_doc` fixture (default `F:\Project1.rvt`).
+
+## IDE integration
+
+**VS Code / Cursor** — `python.testing.pytestEnabled: true`. Plugin detects `vscode_pytest` / `TEST_RUN_PIPE` and disables CLI streaming to avoid duplicate tree entries.
+
+**PyCharm** — enable pytest as test runner.
+
+## License
+
+[MIT](LICENSE)

revitdevtool_pytest-0.4.0/README.md

@@ -0,0 +1,193 @@
+# RevitDevTool.PyTest
+
+[![PyPI version](https://img.shields.io/pypi/v/revitdevtool_pytest)](https://pypi.org/project/revitdevtool-pytest/)
+[![Python](https://img.shields.io/pypi/pyversions/revitdevtool_pytest)](https://pypi.org/project/revitdevtool-pytest/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+pytest plugin for testing CAD/BIM API code inside live host applications via the RevitDevTool Named Pipe bridge.
+
+Write tests locally with pytest; execution happens inside the host process. **Currently supported:** **Revit** and **AutoCAD family** only. Navisworks, Rhino, Tekla, and other hosts are **in progress**.
+
+## Installation
+
+```bash
+pip install revitdevtool_pytest
+# or
+uv add revitdevtool_pytest
+```
+
+| Requirement | Version |
+|---|---|
+| Python | >= 3.10 |
+| pytest | >= 9.0 |
+| pywin32 | >= 311 |
+| OS | Windows (Named Pipes) |
+| Host | [RevitDevTool](https://github.com/trgiangv/RevitDevTool) add-in loaded |
+
+## Supported hosts
+
+### Supported today
+
+| `host_name` | Application | Pipe prefix |
+|---|---|---|
+| `revit` | Autodesk Revit | `Revit` |
+| `autocad` | AutoCAD | `AutoCad` |
+| `civil3d` | Civil 3D | `Civil3D` |
+| `plant3d` | Plant 3D | `Plant3D` |
+| `acadarch` | AutoCAD Architecture | `AcadArch` |
+| `acadmech` | AutoCAD Mechanical | `AcadMech` |
+| `acadmep` | AutoCAD MEP | `AcadMep` |
+| `acadelec` | AutoCAD Electrical | `AcadElec` |
+| `acadmap3d` | AutoCAD Map 3D | `AcadMap3D` |
+
+### In progress
+
+| `host_name` | Application | Status |
+|---|---|---|
+| `navisworks` | Navisworks | Not validated |
+| `rhino` | Rhino | Not validated |
+| `tekla` | Tekla Structures | Not validated |
+
+The plugin registry may list additional names for future work. Treat them as experimental until documented here as **Supported today**.
+
+### Pipe names (pytest only)
+
+The plugin connects to the **pytest/control** pipe:
+
+`DevTools_{Host}_{Version}_{PID}`
+
+Examples: `DevTools_Revit_2025_12345`, `DevTools_AutoCad_2026_7890`
+
+MCP clients use a separate pipe: `DevToolsMcp_{Host}_{Version}_{PID}`. Do not point pytest at an MCP pipe.
+
+## Quick start (consumer project)
+
+```bash
+uv init my-host-tests && cd my-host-tests
+uv add revitdevtool_pytest pytest
+```
+
+`pyproject.toml`:
+
+```toml
+[tool.pytest.ini_options]
+host_name = "revit"
+host_version = "2025"
+force_launch = false
+per_test_timeout = "60"
+launch_timeout = "180"
+```
+
+`tests/conftest.py`:
+
+```python
+import pytest
+
+@pytest.fixture(scope="session")
+def revit_uiapp():
+    return __revit__
+
+@pytest.fixture(scope="session")
+def revit_doc(revit_uiapp):
+    return revit_uiapp.ActiveUIDocument.Document
+```
+
+`tests/test_smoke.py`:
+
+```python
+def test_active_view(revit_doc):
+    assert revit_doc.ActiveView is not None
+```
+
+```bash
+uv run pytest -v
+```
+
+## Configuration
+
+| Option | Default | Description |
+|---|---|---|
+| `host_name` | `"revit"` | Target host — use **Supported today** names only. |
+| `host_version` | — | Version string (`"2025"`, `"8.0"`, …). Required for launch. |
+| `force_launch` | `false` | Force a **new** host instance (skip reuse). Requires `host_version`. |
+| `per_test_timeout` | `"60"` | Per-test budget (seconds). The `tests/run` pipe wait is this × collected tests. |
+| `launch_timeout` | `"180"` | Wait for host pipe after launch (seconds). |
+| `host_pipe` | — | Explicit pipe name (skip discovery). |
+
+CLI flags override INI: `--host`, `--host-version`, `--force-launch`, `--per-test-timeout`, `--launch-timeout`, `--host-pipe`.
+
+### Connection behavior
+
+1. **`force_launch = false` (default):** scan for `DevTools_*` pipes matching `host_name` / `host_version`, reuse a free instance (suite leasing), or reconnect to a leased PID.
+2. **No matching instance:** auto-launch host when `host_version` is set (unless `--host-pipe` pins an existing pipe).
+3. **`force_launch = true`:** always spawn a new process and wait for its pipe.
+
+### Print output
+
+Captured `print()` from in-host tests is shown for passing tests (same as `-rP`). No extra flags needed.
+
+## Writing tests
+
+- Put **host API imports inside functions** — collection runs on your machine, execution in the host.
+- Use fixtures for `__revit__`, documents, and rollback helpers.
+- Declare suite dependencies with **PEP 723** in CPython `conftest.py` (or `test_*.py`); RevitDevTool installs them before `tests/run`. IronPython `test_*_ipy.py` **does not** use PEP 723 — `ipytests/run` never installs packages.
+
+```python
+# /// script
+# dependencies = ["numpy>=2.0", "polars>=1.0"]
+# ///
+```
+
+### Revit rollback fixture
+
+```python
+@pytest.fixture
+def revit_auto_rollback(revit_transaction_service):
+    revit_transaction_service.StartChanges()
+    try:
+        yield revit_transaction_service
+    finally:
+        revit_transaction_service.RevertChanges()
+```
+
+## How it works
+
+1. Local pytest collects tests.
+2. Plugin connects to `DevTools_{Host}_{Version}_{PID}`.
+3. Node IDs sent via JSON-RPC method `tests/run` (`BridgeMessage` length-prefixed frames).
+4. Host runs `PytestRunner.py` embedded in RevitDevTool (`PytestExecutionService` on main thread).
+5. Results and optional progress notifications return to the client.
+6. Plugin maps `CaseResult` → standard pytest reports.
+
+## Developing this repository
+
+Clone and run integration tests against a live host:
+
+```powershell
+cd RevitDevTool.PyTest
+uv run pytest -v                          # Revit suite (default)
+uv run pytest tests/Revit/test_smoke.py -v
+uv run pytest --host civil3d --host-version 2026  # after switching testpaths/host in pyproject.toml
+```
+
+### Layout
+
+| Path | Purpose |
+|---|---|
+| `src/revitdevtool_pytest/` | Plugin source (published wheel) |
+| `tests/Revit/` | Revit integration tests + `schedule/` helpers |
+| `tests/Civil3d/` | Civil 3D / AutoCAD API tests |
+
+Revit suite settings in `pyproject.toml`: `testpaths = ["tests/Revit"]`, `pythonpath = ["tests/Revit"]` for local `schedule` imports.
+
+Optional env: `REVIT_TEST_MODEL_PATH` — path to `.rvt` for `revit_doc` fixture (default `F:\Project1.rvt`).
+
+## IDE integration
+
+**VS Code / Cursor** — `python.testing.pytestEnabled: true`. Plugin detects `vscode_pytest` / `TEST_RUN_PIPE` and disables CLI streaming to avoid duplicate tree entries.
+
+**PyCharm** — enable pytest as test runner.
+
+## License
+
+[MIT](LICENSE)