cursor(rules) More cursor rules for libvcs

Author: tony

.cursor/rules/pytest-best-practices.mdc

@@ -0,0 +1,69 @@
+---
+description: 
+globs: tests/**/*.py
+alwaysApply: false
+---
+# Ground Rules for Writing vcspull Tests
+
+## 1. Study First, Be Homogenous
+- **Analyze Existing Tests:** Before writing new tests, study `tests/test_sync.py`, `tests/test_config.py`, and other relevant test files to understand existing patterns, fixture usage, and assertion styles.
+- **Maintain Consistency:** Strive for homogeneity in test structure, naming conventions, and overall style.
+- **Project Conventions:** Adhere to project-specific conventions like using `typing as t` and `pathlib.Path` for all path manipulations.
+
+## 2. Fixture Prioritization and Usage
+- **`libvcs` Fixtures First:** For any VCS-related operations (creating repos, committing, checking status), **always** prioritize using fixtures from `libvcs.pytest_plugin` (available via `vcspull/conftest.py`). Examples:
+    - `create_git_remote_repo`, `create_svn_remote_repo`, `create_hg_remote_repo` (and their `mercurial`/`subversion` counterparts if using those directly) for setting up test repositories.
+    - `git_repo`, `svn_repo`, `hg_repo` for pre-configured `Sync` objects.
+    - `git_commit_envvars` for environment variables needed for git commits.
+- **Pytest Built-in Fixtures:** Utilize standard `pytest` fixtures like `tmp_path` for temporary files and directories.
+- **Custom Project Fixtures:**
+    - For common non-VCS setup (e.g., mocked home/CWD, config file setup), use or create well-defined fixtures.
+    - Place shared fixtures in `vcspull/conftest.py` or `vcspull/tests/conftest.py`. Module-specific fixtures can reside in the test file itself.
+    - Example: `home_path`, `cwd_path` (refactored to use `monkeypatch`), `setup_teardown_test_config_dir`.
+- **`autouse=True`:** Use sparingly, only for fixtures that genuinely apply to *all* tests within their scope.
+
+## 3. Mocking Strategy: `monkeypatch` vs. `mocker`
+- **`monkeypatch` (pytest built-in):**
+    - **Environment & Globals:** Use for modifying global settings, environment variables (`monkeypatch.setenv()`, `monkeypatch.delenv()`), the current working directory (`monkeypatch.chdir()`), or `sys.path`.
+    - **Patching Attributes/Builtins:** Use `monkeypatch.setattr()` to modify attributes of classes/objects (e.g., `pathlib.Path.home`) or to replace functions/methods in external libraries or Python builtins.
+    - **Dictionary Items:** Use `monkeypatch.setitem()` and `monkeypatch.delitem()` for modifying dictionaries.
+    - Refer to [Pytest Monkeypatch Documentation](https://docs.pytest.org/en/stable/how-to/monkeypatch.html).
+- **`mocker` (from `pytest-mock`):**
+    - **Application Code:** Primarily use for patching functions, methods, or objects *within the `vcspull` application code itself* (e.g., `mocker.patch('vcspull.cli.add.some_function')`).
+    - **Assertions:** Use `mocker` when you need to assert how a mock was called, its return values, or to simulate side effects for your application's internal logic.
+- **Clarity in Mocking (CRITICAL):**
+    - For **every** use of `mocker.patch()`, `mocker.patch.object()`, `monkeypatch.setattr()`, `monkeypatch.setenv()`, etc., include comments explaining:
+        - **`# WHAT:`**: What specific function, method, attribute, or environment variable is being simulated or altered.
+        - **`# WHY:`**: The reason for the mock – what behavior is being controlled or isolated for the test's purpose.
+
+## 4. Test Structure and Assertions
+- **Atomic Tests:** Each test function should verify a single, specific piece of functionality or scenario.
+- **Clear Naming:** Test functions and fixtures should have descriptive names (e.g., `test_add_repo_new_config_cwd`).
+- **Docstrings:** Test functions should have a concise docstring explaining what is being tested.
+- **Plain Assertions:** Use standard `assert` statements for verifications.
+- **Logging:** Use the `caplog` fixture to assert specific log messages when testing command output or internal logging.
+- **Error Handling:** Explicitly test for expected exceptions using `pytest.raises()`.
+
+## 5. Code Coverage and Quality
+- **100% Coverage:** Aim for 100% test coverage for all new or modified code in `cli/add.py` and `cli/add_from_fs.py` (and any other modules).
+- **Test All Paths:** Ensure tests cover success cases, failure cases, edge conditions, and all logical branches within the code.
+- **Development Workflow:** Adhere to the project's quality assurance process:
+    ```
+    uv run ruff check . --fix
+    uv run ruff format .
+    uv run mypy
+    uv run py.test --cov -v
+    ```
+  (Run these commands locally to verify changes).
+
+## 6. `vcspull`-Specific Considerations
+- **Configuration Files:**
+    - When testing config loading, mock `find_home_config_files` appropriately.
+    - Use helpers like `vcspull.tests.helpers.save_config_yaml` (which internally uses `write_config`) for creating test configuration files in a controlled manner.
+- **Path Expansion:** Be mindful of `expand_dir`. If testing logic that depends on its behavior, provide controlled mocks for it or ensure `home_path` / `cwd_path` fixtures correctly influence its resolution.
+- **Avoid Manual VCS Subprocesses:**
+    - **Do not** use `subprocess.run(["git", ...])` or similar direct VCS command calls for setting up repository states in tests if a `libvcs` fixture or library function can achieve the same result.
+    - The only exception is when testing a function that *itself* directly uses `subprocess` (e.g., `get_git_origin_url`).
+    - Refactor tests like `test_add_from_fs_integration_with_libvcs` to use `create_git_remote_repo` from `libvcs` instead of manual `git init` calls via `subprocess`.
+
+By following these rules, we can ensure that new tests are robust, maintainable, consistent with the existing test suite, and effectively leverage the capabilities of `pytest` and `libvcs`.