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

revitdevtool_pytest-0.3.0/AGENTS.md

@@ -0,0 +1,164 @@
+# AGENTS
+
+## Overview
+
+This is the pytest client plugin for RevitDevTool. It bridges local pytest with a live host process via Named Pipe JSON-RPC. Supports Revit, AutoCAD-family, and any host that exposes a `DevToolsPipeServer` pipe.
+
+## Architecture
+
+```
+Local pytest (collect) → Named Pipe → Host process (PytestRunner.py) → Results → Local pytest (report)
+```
+
+### Module Map
+
+| Module | Role |
+|--------|------|
+| `plugin.py` | Hook orchestrator — lifecycle, options, bridge setup |
+| `connection.py` | Bridge lifecycle — discover, connect, lease, launch |
+| `bridge.py` | Wire protocol — Named Pipe framing, request/response |
+| `discovery.py` | Pipe scan, host registry lookup, process launch |
+| `reporting.py` | Map remote CaseResult → pytest TestReport |
+| `suite_leasing.py` | Cross-process host instance allocation (file-based) |
+| `suite_lock.py` | Windows mutex for same-suite concurrency guard |
+| `dialog_resolver.py` | Auto-dismiss host startup dialogs via Win32 |
+| `models.py` | Wire protocol data models (mirrors C# PytestContracts) |
+| `constants.py` | Shared constants, option names, host registry, defaults |
+
+### Host-Side (in RevitDevTool repo)
+
+| File | Role |
+|------|------|
+| `PytestRunner.py` | Embedded script — runs `pytest.main()` inside host |
+| `SetupRevit.py` / `SetupAcad.py` | Runtime setup — API refs, I/O redirection |
+| `PytestExecutionService.cs` | C# orchestrator — receives pipe request, invokes Python |
+| `PytestContracts.cs` | C# wire models (mirrors `models.py`) |
+
+## Multi-Host Support
+
+The plugin supports any host that registers a DevToolsPipeServer Named Pipe.
+
+### Pre-registered Hosts
+
+| 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` |
+| `navisworks` | `Navisworks` | — | — |
+| `rhino` | `Rhino` | — | — |
+| `tekla` | `Tekla` | — | — |
+
+Hosts without an `exe_name` (e.g. Rhino, Tekla) can only be connected via pipe auto-discovery or `--host-pipe`. Any unknown host name also gets a fallback config using the host name as pipe prefix.
+
+### Pipe Name Format
+
+Pipes follow `{Host}_{Version}_{PID}` — mirrors C# `InstanceManager` pattern `^\w+_[^_]+_\d+$`.
+
+Examples:
+- `Revit_2025_12345` (year-based version)
+- `AutoCad_2026_7890` (year-based)
+- `Rhino_8.0_9999` (semver)
+- `Tekla_2024.1_1111` (dotted version)
+
+Version is any non-underscore string — not limited to 4-digit years.
+
+### Executable Discovery
+
+- **Revit**: `HKLM\SOFTWARE\Autodesk\Revit\Autodesk Revit {version}` → `InstallationLocation`
+- **AutoCAD family**: `HKLM\SOFTWARE\Autodesk\AutoCAD` → enumerate releases → match product ID via `ACAD-XXNN` pattern → `GlobUPILocation` / `AcadLocation`
+- **Generic**: Hosts with `registry_key` + `registry_value` use registry lookup, then filesystem fallback under `Program Files\Autodesk\`
+- **No exe_name**: Discovery returns `None`; connect via existing pipes only
+
+## Key Design Decisions
+
+- **Dual pytest model**: Local pytest collects tests; remote pytest executes them. This enables IDE integration (test tree, navigation) while executing in the host's thread.
+- **`--capture=sys`**: Required because fd-level capture (`os.dup2`) doesn't work in embedded Python.NET.
+- **`--disable-plugin-autoload`**: Prevents third-party plugins from interfering with in-host execution.
+- **`sys.__pytest_running__`**: Flag set by PytestRunner to prevent setup scripts from hijacking stdout/stderr during test runs.
+- **Streaming vs batch**: CLI gets real-time progress notifications; IDE adapters get one batch to avoid double-counting.
+- **Suite leasing**: File-based lease store binds suite → host PID across processes. Mutex prevents same-suite parallel runs.
+- **force_launch**: When enabled, spawns new host and waits for its exact PID pipe (ignores existing instances).
+- **Open host registry**: Unknown host names get a fallback `HostConfig(pipe_prefix=host_name)` — any host exposing a DevToolsPipeServer pipe works without pre-registration.
+
+## Running Tests
+
+```bash
+# From project root with .venv activated:
+pytest
+
+# Or via uv / pixi:
+uv run pytest
+pixi run pytest
+
+# Specific test:
+pytest tests/test_active_state.py::test_active_view_info -v
+
+# Target a different host:
+pytest --host autocad --host-version 2026
+pytest --host rhino --host-version 8.0
+```
+
+Plugin auto-enables `-rP` (show captured stdout for passing tests).
+
+## Configuration
+
+All options in `pyproject.toml` under `[tool.pytest.ini_options]`:
+
+```toml
+host_name = "revit"            # Host to connect to (revit, autocad, civil3d, rhino, etc.)
+host_version = "2025"          # Required for launch (accepts any string: year, semver, etc.)
+host_launch = false            # true = always spawn new instance
+host_timeout = "60"            # Per-test timeout (seconds)
+host_launch_timeout = "180"    # Startup wait (seconds)
+host_pipe = ""                 # Explicit pipe (bypass discovery)
+```
+
+CLI equivalents: `--host`, `--host-version`, `--host-timeout`, `--host-pipe`, `--host-launch`, `--host-launch-timeout`.
+
+## Fixtures Pattern
+
+```python
+# conftest.py (Revit)
+@pytest.fixture(scope="session")
+def revit_uiapp():
+    return __revit__  # UIApplication injected by host
+
+@pytest.fixture(scope="session")
+def revit_doc(revit_uiapp):
+    return revit_uiapp.ActiveUIDocument.Document
+
+@pytest.fixture
+def revit_auto_rollback(revit_transaction_service):
+    """Start undo tracking, revert after test."""
+    revit_transaction_service.StartChanges()
+    try:
+        yield revit_transaction_service
+    finally:
+        revit_transaction_service.RevertChanges()
+```
+
+## Common Traps
+
+- Tests execute **inside the host**, not locally. `import` statements for host APIs only work at test runtime.
+- `__revit__` (Revit) or equivalent builtins are injected by host setup scripts — always access via fixtures.
+- Host APIs require main-thread access. All tests run sequentially via FIFO queue (`IHostContextExecutor`).
+- Named Pipe format: `{Host}_{Version}_{PID}` (e.g. `Revit_2025_12345`, `Rhino_8.0_9999`). Version is any non-underscore string.
+- PEP 723 dependencies in `conftest.py` are auto-installed by `PytestDependencyService` before execution.
+- `--host-launch` requires `--host-version` to be set — otherwise exits with config error.
+- Print output inside tests is captured by pytest's `--capture=sys` mechanism and returned via `CaseResult.stdout`.
+
+## Change Rules
+
+- Wire protocol changes must update both `models.py` (Python) and `PytestContracts.cs` (C#).
+- Adding CLI options: register in both `pytest_addoption` (CLI) and `parser.addini` (INI).
+- Connection logic is stateless by design — all functions receive parameters, no module-level mutable state except `plugin.py` globals.
+- After modifying connection/discovery logic, manually test with both `host_launch = true` and `false`.
+- Host registry changes: keep `HOST_REGISTRY` in `constants.py` in sync with `HostApp` enum and `AcadPathResolver.ProductIdMap` in the C# codebase.
+- Any host with a DevToolsPipeServer pipe can be reached without pre-registration (fallback config).

revitdevtool_pytest-0.3.0/CHANGELOG.md

@@ -0,0 +1,151 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.3.0] - 2026-05-31
+
+### Added
+
+- **Multi-host support:** plugin now supports Revit, AutoCAD, Civil3D, Plant3D, Navisworks, Rhino, Tekla, and any host exposing a DevToolsPipeServer Named Pipe.
+- **`--host` option:** new CLI flag and `host_name` INI key to select the target host application (default: `revit`).
+- **`HostConfig` dataclass:** centralized executable discovery and launch configuration per host product, stored in `HOST_REGISTRY`.
+- **AutoCAD-family executable discovery:** registry-based resolver mirrors C# `AcadPathResolver` — enumerates `HKLM\SOFTWARE\Autodesk\AutoCAD` releases, matches product IDs (`ACAD-XXNN`), resolves install path via `GlobUPILocation` / `AcadLocation`.
+- **Open host registry:** `get_host_config()` returns a fallback `HostConfig(pipe_prefix=host_name)` for unknown host names — any host with a DevToolsPipeServer pipe works without pre-registration.
+- **Multi-host dialog resolver:** `StartupDialogResolver` keywords expanded to cover AutoCAD, Civil, and Plant startup dialogs.
+
+### Changed
+
+- **CLI/INI options renamed:** all `--revit-*` / `revit_*` options replaced with `--host-*` / `host_*` equivalents (`--host-version`, `--host-timeout`, `--host-pipe`, `--host-launch`, `--host-launch-timeout`).
+- **Flexible pipe pattern:** `PIPE_PATTERN` changed from `^\w+_\d{4}_\d+$` to `^\w+_[^_]+_\d+$` — version segment accepts any non-underscore string (year, semver, dotted), matching C# `InstanceManager`.
+- **`HostInstance.version` type:** changed from `int` to `str` to support non-year version formats (e.g. `8.0`, `2024.1`, `v3.2.1`).
+- **`--host-version` accepts string:** no longer restricted to 4-digit year integers.
+- **`RevitBridge` → `HostBridge`:** bridge class renamed for host-agnostic semantics.
+- **`RevitInstance` → `HostInstance`:** discovery dataclass renamed.
+- **`find_revit_pipes()` → `find_host_pipes()`:** accepts optional `host_name` filter; returns all matching pipes including unregistered prefixes.
+- **`find_revit_path()` → `find_host_executable()`:** dispatches to Revit registry, AutoCAD-family registry, or returns `None` for hosts without exe discovery.
+- **`start_revit()` → `start_host()`:** uses `HostConfig.launch_args` per host.
+- **`wait_for_revit_pipe()` → `wait_for_host_pipe()`:** host-agnostic pipe polling.
+- **`HostConfig.exe_name` optional:** hosts without a known executable (Rhino, Tekla, etc.) connect via pipe auto-discovery or `--host-pipe` only.
+- **`is_process_alive()`:** handles `exe_name=None` gracefully — checks PID liveness without executable name verification.
+
+### Removed
+
+- **`_opt_int()` helper:** version is now parsed as string, no integer conversion needed.
+
+### Notes
+
+- `0.3.0` is a breaking change from `0.2.x`: all CLI flags and INI keys are renamed. Existing `revit_*` / `--revit-*` options are no longer recognized.
+- The pipe pattern is now aligned with the C# `InstanceManager.HostPipePattern` regex (`^\w+_[^_]+_\d+$`).
+- Revit users: add `host_name = "revit"` to `pyproject.toml` (or rely on the default).
+
+## [0.2.0] - 2026-05-31
+
+### Added
+
+- **Auto print capture:** plugin automatically enables `-rP` behavior — captured `print()` output is shown for both passing and failing tests without any user configuration.
+- **PID-aware pipe discovery:** `wait_for_revit_pipe` can now wait for a specific process ID, ensuring `force_launch` connects to the newly spawned instance only.
+
+### Changed
+
+- **`revit_launch` → force_launch semantics:** renamed internal parameter from `prefer_fresh` to `force_launch`. When enabled, the plugin disconnects any existing bridge, spawns a new Revit instance, and waits for that exact PID's pipe — never reuses existing instances.
+- **`_opt_bool` fix:** corrected boolean option parsing so `revit_launch = true` in `pyproject.toml` is properly respected when no CLI flag is explicitly passed.
+- **Type annotations refactor:** resolved false-positive IDE warnings across `bridge.py`, `connection.py`, `suite_leasing.py`, and `dialog_resolver.py`.
+- **`SetupRevit.py` (Revit-side):** I/O hijacking is now conditional on `sys.__pytest_running__` flag — prevents conflict with pytest capture during test execution.
+- **`PytestRunner.py` (Revit-side):** sets `sys.__pytest_running__ = True` during execution; top-level error handling wraps entire `_run()` to always return structured JSON.
+
+### Removed
+
+- **`discover_tests()`** method from `bridge.py` (client-side dead code; server endpoint remains).
+- **`DiscoverRequest` / `DiscoverResponse`** classes from `models.py` (unused by client).
+- **`BRIDGE_METHOD_TESTS_DISCOVER`** constant (no longer referenced).
+- **`resolve_existing()` / `get_suite_process_id()` / `_prune_stale()`** from `suite_leasing.py` (unused).
+- **`launch_revit()`** from `discovery.py` (replaced by `start_revit` + PID tracking).
+- **`addopts = "-rP"`** from `pyproject.toml` (now automatic via plugin).
+
+### Fixed
+
+- **`revit_launch = true` in INI ignored:** `_opt_bool` now correctly reads INI value when CLI flag is not explicitly set.
+
+## [0.1.0] - 2026-05-03
+
+### Added
+
+- **Real-time streaming:** test progress notifications streamed from Revit to the pytest client during execution.
+- **Suite leasing:** Windows Mutex-based exclusive access prevents multiple pytest processes from connecting to the same Revit instance.
+- **Test discovery:** `PytestRunRequest` + `_BridgePlugin` integration enables `--collect-only` discovery without executing tests.
+- **Reporting module:** remote `CaseResult[]` mapping back to pytest `TestReport`, with `run_remote_session` orchestrating discover + run.
+- **Connection module:** centralized `ensure_bridge()` with auto-connect, lease management, and Revit auto-launch flow.
+- **Schedule API tests:** comprehensive test suite for Revit schedule operations (copy, field mapping, header, template, custom workflow).
+- **Image export tests:** `test_image_export.py` covering `RevitImageExporter`.
+- **Document & transaction tests:** `test_revit_document.py`, `test_revit_transactions.py`.
+- **Session cleanliness tests:** `test_session_cleanliness.py`, `test_active_state.py` verifying state isolation between runs.
+- **Streaming tests:** `test_streaming.py` validating progress notification flow.
+- **Dependencies tests:** `test_dependencies.py` verifying package resolution.
+- **GitNexus integration:** AGENTS.md, CLAUDE.md, and CLI skills for graph-based code intelligence.
+- **Project setup guide:** recommended `uv` and `pixi` workflows in README.
+
+### Changed
+
+- **Architecture rewrite:** `plugin.py` restructured — execution now intercepted via `pytest_runtestloop` instead of `pytest_pyfunc_call`. Remote session orchestrates discover + run in a single round-trip.
+- **Configuration:** primary config via `[tool.pytest.ini_options]` in `pyproject.toml` — CLI flags remain as overrides.
+- **`bridge.py`:** expanded with `discover_tests()`, `run_tests()`, notification dispatch, frame protocol hardening.
+- **`models.py`:** new `DiscoverRequest`, `RunRequest`, `RunResponse`, `CaseResult`, `CollectionError` contracts.
+- **`constants.py`:** centralized all bridge methods, option names, timeouts, pipe patterns.
+- **`pyproject.toml`:** bumped `revit_launch_timeout` to 180s, added `revit_timeout` default.
+
+### Removed
+
+- **`serializer.py`:** deprecated — test code serialization replaced by structured discovery + run flow.
+- **`.vscode/settings.json`:** removed from repo; config lives in `pyproject.toml`.
+
+### Notes
+
+- `0.1.0` represents a major architectural shift from single-test relay to session-oriented orchestration. The plugin now discovers tests remotely, runs them in batch, and streams progress back in real-time.
+- Suite leasing ensures safe concurrent usage across multiple test suits targeting the same Revit year.
+
+## [0.0.3] - 2026-04-10
+
+### Fixed
+
+- Fixed Revit auto-launch dialog handling by starting the startup dialog resolver immediately after spawning Revit, before waiting for the named pipe.
+- Fixed startup dialog button selection to prefer safe allow-list actions such as `Always Load` and `Load Once`.
+- Prevented accidental clicks on destructive dialog actions such as `Do Not Load`, `Cancel`, and `No`.
+
+### Notes
+
+- This release focuses on reliable auto-launch behavior when Revit shows unsigned add-in security dialogs during startup.
+
+## [0.0.2] - 2026-04-10
+
+### Fixed
+
+- Fixed pytest plugin auto-loading via the `pytest11` entry point.
+- Fixed the `pytest_unconfigure` hook signature in `revitdevtool_pytest.plugin` so Pluggy accepts the plugin during pytest startup.
+- Restored the expected standalone package behavior so `RevitDevTool.PyTest` can be discovered and activated by a normal Python/pytest environment before connecting to Revit.
+
+### Changed
+
+- Aligned the published package metadata name with the recommended normalized package name `revitdevtool_pytest`.
+
+### Notes
+
+- This release is intended as a bugfix release for the `0.0.1` package.
+- No user-facing CLI options are changed in this release.
+- This name alignment is intended to remain compatible with existing PyPI installs because Python package indexes and installers normalize `.`, `-`, and `_` in distribution names.
+
+## [0.0.1] - 2026-04-09
+
+### Added
+
+- Initial standalone `pytest` plugin package for running Revit API tests through the RevitDevTool Named Pipe bridge.
+- Automatic discovery of running Revit instances through named pipes.
+- Optional Revit auto-launch flow via `--revit-launch` and `--revit-version`.
+- Remote test execution by intercepting `pytest_pyfunc_call` and forwarding serialized test code to Revit.
+- Support for explicit pipe targeting with `--revit-pipe`.
+- Per-test timeout and launch timeout configuration.
+- Revit startup dialog resolver integration.
+- Example test suite and VS Code integration guidance in the project documentation.
+
+### Notes
+
+- `0.0.1` introduced the core test bridge workflow, but the published package contains a plugin loading issue fixed in `0.0.2`.

revitdevtool_pytest-0.3.0/CLAUDE.md

@@ -0,0 +1 @@
+Refer to [AGENTS.md](./AGENTS.md) for project rules, conventions, and workflow.

revitdevtool_pytest-0.3.0/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: revitdevtool_pytest
+Version: 0.3.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 host applications via RevitDevTool Named Pipe bridge.
+Supports Revit, AutoCAD-family, and any host exposing a DevToolsPipeServer pipe.
+Tests run inside a live host process — write standard pytest, execute remotely.
+
+## Installation
+
+```bash
+pip install revitdevtool_pytest
+```
+
+## Dependencies
+
+| Package | Version |
+|---|---|
+| Python | >= 3.10 |
+| pytest | >= 9.0 |
+| pywin32 | >= 311 |
+
+## Requirements
+
+- Windows (Named Pipes)
+- A host application with [RevitDevTool](https://github.com/trgiangv/RevitDevTool) add-in installed and loaded
+
+## Supported Hosts
+
+### Pre-registered
+
+| 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` |
+| `navisworks` | Navisworks | `Navisworks` |
+| `rhino` | Rhino | `Rhino` |
+| `tekla` | Tekla Structures | `Tekla` |
+
+### Any host
+
+Any host name works — unknown names get a fallback config using the name as pipe prefix. Connect via auto-discovery or `--host-pipe`.
+
+### Pipe Name Format
+
+Pipes follow `{Host}_{Version}_{PID}` (e.g. `Revit_2025_12345`, `Rhino_8.0_9999`). Version can be any format — year, semver, etc.
+
+## Project Setup
+
+**Recommended:** scaffold your project with [uv](https://docs.astral.sh/uv/) or [pixi](https://pixi.sh/):
+
+```bash
+# uv
+uv init my-revit-tests
+cd my-revit-tests
+uv add revitdevtool_pytest
+
+# pixi (uses pyproject.toml as manifest)
+pixi init --format pyproject my-revit-tests
+cd my-revit-tests
+pixi add --pypi revitdevtool_pytest
+```
+
+## Configuration
+
+Add plugin settings to `[tool.pytest.ini_options]` in your `pyproject.toml`:
+
+```toml
+[tool.pytest.ini_options]
+host_name = "revit"
+host_version = "2025"
+host_launch = false
+host_launch_timeout = "180"
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `host_name` | string | `"revit"` | Host application name (see Supported Hosts above). |
+| `host_version` | string | — | Host version (e.g. `"2025"`, `"8.0"`). Required when `host_launch = true`. |
+| `host_launch` | bool | `false` | Force-launch a **new** host instance (skip reusing existing free instances). |
+| `host_timeout` | string | `"60"` | Per-test execution timeout in seconds. |
+| `host_launch_timeout` | string | `"120"` | Seconds to wait for host to start. |
+| `host_pipe` | string | — | Explicit pipe name (bypasses auto-discovery). |
+
+CLI flags override INI settings:
+
+```bash
+# Revit
+pytest --host-launch --host-version=2025 -v
+
+# AutoCAD
+pytest --host autocad --host-version=2026 -v
+
+# Civil 3D
+pytest --host civil3d --host-version=2026 -v
+```
+
+### Connection Behavior
+
+- **Default** (`host_launch = false`): plugin auto-discovers a running host instance matching `host_version` via Named Pipe scan. If none found, exits with error.
+- **Force launch** (`host_launch = true`): always spawns a new host process, waits for its pipe to appear, then connects. Existing instances are ignored.
+
+### Print Output
+
+Captured `print()` output from tests running inside the host is automatically shown in the terminal for passing tests (equivalent to `-rP`). No extra flags needed.
+
+## Usage
+
+### Fixtures
+
+Define fixtures in `conftest.py` that provide host API objects:
+
+```python
+import pytest
+
+# Revit fixtures
+@pytest.fixture(scope="session")
+def revit_uiapp():
+    return __revit__  # UIApplication injected by RevitDevTool
+
+@pytest.fixture(scope="session")
+def revit_app(revit_uiapp):
+    return revit_uiapp.Application
+
+@pytest.fixture(scope="session")
+def revit_doc(revit_uiapp):
+    return revit_uiapp.ActiveUIDocument.Document
+```
+
+### Writing Tests
+
+```python
+def test_active_view(revit_doc):
+    view = revit_doc.ActiveView
+    print(f"Active View: {view.Name}")
+    assert view.Name is not None
+
+def test_revit_version(revit_app):
+    assert "2025" in revit_app.VersionName
+```
+
+### PEP 723 Dependencies
+
+Declare test-suite dependencies in `conftest.py` using PEP 723 metadata. RevitDevTool auto-installs them before test execution:
+
+```python
+# /// script
+# dependencies = [
+#   "numpy>=2.0",
+#   "polars>=1.0",
+# ]
+# ///
+```
+
+### Running Tests
+
+```bash
+# With pyproject.toml configured:
+pytest
+
+# Override version for a single run:
+pytest --host-version=2026 -v
+
+# Target a different host:
+pytest --host autocad --host-version=2026 -v
+
+# Using uv or pixi:
+uv run pytest
+pixi run pytest
+```
+
+## How It Works
+
+1. pytest discovers and collects tests locally
+2. Plugin intercepts `pytest_runtestloop`, connects to the host via Named Pipe
+3. Test nodeids are sent to the host's `PytestRunner.py` (embedded in RevitDevTool)
+4. Tests execute inside the host's Python.NET environment with full API access
+5. Results (pass/fail/skip, stdout, stderr, tracebacks) are returned via pipe
+6. Plugin maps results back to standard pytest reports
+
+## IDE Integration
+
+### VS Code / Cursor
+
+```json
+{
+    "python.testing.pytestEnabled": true,
+    "python.testing.pytestArgs": ["tests"]
+}
+```
+
+### PyCharm
+
+Enable pytest as the test runner. Plugin auto-detects IDE adapters and disables streaming to avoid duplicate results in the test tree.
+
+## License
+
+[MIT](LICENSE)