curdriceaurora · curdriceaurora · Mar 30, 2026 · Mar 30, 2026 · Mar 30, 2026 · Mar 30, 2026
diff --git a/tests/README.md b/tests/README.md
@@ -0,0 +1,143 @@
+# Test Suite Documentation
+
+## Skip Status Overview
+
+This document tracks all skipped tests in the pytest test suite. Every skipped test is documented with a tracking issue explaining why it's skipped and when it can be unskipped.
+
+### Final Skip Count
+
+As of the audit completed on 2026-03-30:
+
+- **@pytest.mark.skip**: 15 decorators (17 test methods; one class-level decorator covers 3 tests in `TestExecutorInterface`)
+- **@pytest.mark.skipif**: 18 decorators (30 test methods; one class-level decorator covers 12 tests in `test_context_menu_macos.py`)
+- **pytest.importorskip**: ~8+ additional skips (optional dependency checks)
+- **Total documented skips**: ~55+ tests with issue references
+
+**Note**: `TestExecutorInterface` in `tests/plugins/test_sandbox_isolation.py` was added as a new
+class-level skip by this PR. The class existed previously and its tests were running; the skip
+decorator was added during this audit to match the documented intent in issue #338.
+
+### Skip Categories
+
+#### 1. Deferred Features (Phase 3 Development)
+
+Tests skipped because features are not yet implemented:
+
+| Issue | Count | Description | Files Affected |
+|-------|-------|-------------|----------------|
+| [#611](https://github.com/curdriceaurora/Local-File-Organizer/issues/611) | 3 | Audio metadata extraction needs real fixtures | `tests/utils/test_audio_metadata.py` |
+| [#1071](https://github.com/curdriceaurora/Local-File-Organizer/issues/1071) | 3 | Audio transcription feature (Phase 3) | `tests/services/test_audio_transcription.py` |
+| [#1073](https://github.com/curdriceaurora/Local-File-Organizer/issues/1073) | 6 | Video processing features (Phase 3) | `tests/services/test_video_processing.py`<br>`tests/utils/test_video_metadata.py` |
+| [#1076](https://github.com/curdriceaurora/Local-File-Organizer/issues/1076) | 1 | SSE routes for file browser | `tests/test_web_files_routes.py` |
+| [#1077](https://github.com/curdriceaurora/Local-File-Organizer/issues/1077) | 3 | SuggestionEngine API implementation | `tests/integration/test_image_quality_para_suggestion.py` |
+| [#1080](https://github.com/curdriceaurora/Local-File-Organizer/issues/1080) | 1 | SSE streaming for organize route | `tests/test_web_organize_routes.py` |
+| [#338](https://github.com/curdriceaurora/Local-File-Organizer/issues/338) | 3 | Stream A executor not yet delivered | `tests/plugins/test_sandbox_isolation.py` |
+
+**Subtotal: 20 tests** (deferred feature skips; #1077 uses `@pytest.mark.skipif`, others use `@pytest.mark.skip`)
+
+#### 2. Platform-Specific Limitations
+
+Tests skipped on specific operating systems due to platform limitations:
+
+| Issue | Platform | Count | Description | Files Affected |
+|-------|----------|-------|-------------|----------------|
+| [#1072](https://github.com/curdriceaurora/Local-File-Organizer/issues/1072) | Cross-platform | 3 | Platform-specific path validation (macOS, Linux, Windows) | `tests/config/test_config_paths.py` |
+| [#1074](https://github.com/curdriceaurora/Local-File-Organizer/issues/1074) | Windows | 3 | Signal pipe not available on Windows | `tests/daemon/test_service_signal_safety.py` |
+| [#1075](https://github.com/curdriceaurora/Local-File-Organizer/issues/1075) | Windows | 2 | `/dev/null` is writable on Windows | `tests/undo/test_rollback_extended.py` |
+| [#1078](https://github.com/curdriceaurora/Local-File-Organizer/issues/1078) | Windows | 2 | `chmod` does not restrict reads on Windows | `tests/integration/test_error_propagation.py` |
+| [#1078](https://github.com/curdriceaurora/Local-File-Organizer/issues/1078) | Windows | 1 | `chmod` does not restrict reads on Windows | `tests/plugins/test_base_coverage.py` |
+| [#1081](https://github.com/curdriceaurora/Local-File-Organizer/issues/1081) | Windows | 1 | Directory fsync is a no-op on Windows | `tests/parallel/test_checkpoint.py` |
+| [#1082](https://github.com/curdriceaurora/Local-File-Organizer/issues/1082) | Windows | 1 | Hardlinks require admin privileges on Windows | `tests/integration/test_organize_text_workflow.py` |
+| [#1083](https://github.com/curdriceaurora/Local-File-Organizer/issues/1083) | macOS | 12 | macOS-only Quick Action feature | `tests/integration/test_context_menu_macos.py` |
+| [#1084](https://github.com/curdriceaurora/Local-File-Organizer/issues/1084) | Any | 1 | pytest-benchmark not installed | `tests/e2e/test_full_pipeline.py` |
+| [#1085](https://github.com/curdriceaurora/Local-File-Organizer/issues/1085) | Windows, macOS | 1 | Creation time sorting is flaky on Windows/macOS | `tests/test_web_files_routes.py` |
+
+**Subtotal: 27 tests** (platform/environment skipif; uses `@pytest.mark.skipif`)
+
+#### 3. Optional Dependencies
+
+Tests skipped when optional dependencies are not installed. These use `pytest.importorskip()` pattern.
+
+**Policy exception**: Tests using `pytest.importorskip()` for `rank_bm25` and `sklearn` do not require tracking issues, as these are standard optional dependency checks that skip automatically when the package is not installed.
+
+| Issue | Dependency | Description | Files Affected |
+|-------|------------|-------------|----------------|
+| [#1079](https://github.com/curdriceaurora/Local-File-Organizer/issues/1079) | `ebooklib` | EPUB file processing | `tests/utils/test_file_readers.py`<br>`tests/unit/utils/test_file_readers.py` |
+| [#1079](https://github.com/curdriceaurora/Local-File-Organizer/issues/1079) | `Pillow` | Image processing (EPUB thumbnails) | `tests/utils/test_epub_enhanced.py` |
+| N/A | `openpyxl` | Excel file processing | Multiple spreadsheet test files |
+| Exception applies | `rank_bm25` | BM25 search indexing | Multiple search/copilot test files |
+| Exception applies | `sklearn` | Machine learning features | Analytics and vector search tests |
+
+**Subtotal: 8+ tests** (optional dependency skips)
+
+### Skip Pattern Reference
+
+#### Pattern 1: Unconditional Skip with Issue Reference
+
+```python
+@pytest.mark.skip(reason="See #1073 - Phase 3 feature not yet implemented")
+def test_future_feature():
+    pass
+```
+
+#### Pattern 2: Platform-Specific Skip
+
+```python
+@pytest.mark.skipif(sys.platform == "win32", reason="See #1074 - signal pipe not available on Windows")
+def test_unix_only_feature():
+    pass
+```
+
+#### Pattern 3: Optional Dependency Skip
+
+Use `pytest.importorskip()` inside an autouse fixture scoped to the class that needs the dependency:
+
+```python
+class TestEpubCoverExtraction:
+    @pytest.fixture(autouse=True)
+    def _require_pillow(self) -> None:
+        pytest.importorskip("PIL.Image")  # See #1079 - Optional image processing dependency
+
+    def test_extract_cover(self, tmp_path):
+        # Test continues if import succeeds, skips if Pillow not installed
+        ...
+```
+
+### Verification Commands
+
+```bash
+# Show all skips with reasons
+pytest tests/ -v -rs
+
+# Count skip decorators by type
+rg '@pytest.mark.skip\(' tests/ --type py -c
+rg '@pytest.mark.skipif' tests/ --type py -c
+rg 'pytest.importorskip' tests/ --type py -c
+
+# Verify all skips have issue references (grep -v filters out lines with reason=)
+rg '@pytest.mark.skip' tests/ --type py | grep -v 'reason='
+
+# List all tracking issues
+rg 'reason="See #(\d+)' tests/ --type py -o -r '$1' | sort | uniq -c | sort -rn
+```
+
+### Maintenance Guidelines
+
+1. **Never leave a skip without a tracking issue** - Every `@pytest.mark.skip` and `@pytest.mark.skipif` must have `reason="See #NNN"`
+2. **Use pytest.importorskip for optional dependencies** - Decorator-based skips should only be used for platform or environment conditions
+3. **Delete irrelevant tests** - If a feature is permanently removed, delete its tests rather than leaving them skipped
+4. **Document in tracking issues** - Each issue should explain:
+   - Why the test is skipped
+   - What needs to happen before it can be unskipped
+   - Whether this is temporary (bug fix, feature implementation) or permanent (platform limitation)
+
+### Related Documentation
+
+- [GitHub Issue #1028](https://github.com/curdriceaurora/Local-File-Organizer/issues/1028) - Original audit task
+- [pytest skip/xfail documentation](https://docs.pytest.org/en/stable/how-to/skipping.html)
+- [pytest.importorskip API](https://docs.pytest.org/en/stable/reference/reference.html#pytest.importorskip)
+
+---
+
+**Last Updated:** 2026-03-30
+**Audit Completed By:** auto-claude task #038
diff --git a/tests/config/test_config_paths.py b/tests/config/test_config_paths.py
@@ -49,7 +49,9 @@ def test_empty_xdg_config_home_falls_back_to_platformdirs(self) -> None:
         assert isinstance(result, Path)
         assert APP_NAME in str(result)
 
-    @pytest.mark.skipif(sys.platform != "darwin", reason="macOS-specific path")
+    @pytest.mark.skipif(
+        sys.platform != "darwin", reason="See #1072 - macOS-specific path validation"
+    )
     def test_macos_path_format(self) -> None:
         """On macOS, config dir should be under ~/Library/Application Support."""
         with mock.patch.dict(os.environ, {}, clear=False):
@@ -60,7 +62,9 @@ def test_macos_path_format(self) -> None:
         home = Path.home()
         assert str(result).startswith(str(home / "Library" / "Application Support"))
 
-    @pytest.mark.skipif(sys.platform != "linux", reason="Linux-specific path")
+    @pytest.mark.skipif(
+        sys.platform != "linux", reason="See #1072 - Linux-specific path validation"
+    )
     def test_linux_path_format(self) -> None:
         """On Linux without XDG override, config dir should be under ~/.config."""
         env = {k: v for k, v in os.environ.items() if k != "XDG_CONFIG_HOME"}
@@ -69,7 +73,9 @@ def test_linux_path_format(self) -> None:
         home = Path.home()
         assert str(result).startswith(str(home / ".config"))
 
-    @pytest.mark.skipif(sys.platform != "win32", reason="Windows-specific path")
+    @pytest.mark.skipif(
+        sys.platform != "win32", reason="See #1072 - Windows-specific path validation"
+    )
     def test_windows_path_format(self) -> None:
         """On Windows, config dir should be under %APPDATA%."""
         result = get_config_dir()

diff --git a/tests/daemon/test_service_signal_safety.py b/tests/daemon/test_service_signal_safety.py
@@ -87,7 +87,9 @@ def test_signal_handler_tolerates_none_pipe(self) -> None:
 class TestRunLoopExitsOnPipeSignal:
     """TestRunLoopExitsOnPipeSignal test suite."""
 
-    @pytest.mark.skipif(sys.platform == "win32", reason="signal pipe not available on Windows")
+    @pytest.mark.skipif(
+        sys.platform == "win32", reason="See #1074 - signal pipe not available on Windows"
+    )
     def test_run_loop_exits_on_pipe_signal(self) -> None:
         """Verify run loop exits when signal is written to pipe."""
         daemon = DaemonService(_make_config())
@@ -129,7 +131,9 @@ def stop_later() -> None:
         assert daemon._stop_event.is_set(), "Stop event should be set after event.wait path"
 
 
-@pytest.mark.skipif(sys.platform == "win32", reason="signal pipe not available on Windows")
+@pytest.mark.skipif(
+    sys.platform == "win32", reason="See #1074 - signal pipe not available on Windows"
+)
 class TestPipeClosedOnRestore:
     """TestPipeClosedOnRestore test suite."""
 
@@ -168,7 +172,9 @@ def test_pipe_closed_on_restore(self) -> None:
 # ---------------------------------------------------------------------------
 
 
-@pytest.mark.skipif(sys.platform == "win32", reason="signal pipe not available on Windows")
+@pytest.mark.skipif(
+    sys.platform == "win32", reason="See #1074 - signal pipe not available on Windows"
+)
 class TestInstallSignalHandlersMainThread:
     """TestInstallSignalHandlersMainThread test suite."""
 

diff --git a/tests/e2e/test_full_pipeline.py b/tests/e2e/test_full_pipeline.py
@@ -309,7 +309,9 @@ def test_collect_files_timing(
         assert elapsed < 1.0, f"_collect_files too slow: {elapsed:.3f}s"
 
     @pytest.mark.benchmark
-    @pytest.mark.skipif(not HAS_PYTEST_BENCHMARK, reason="pytest-benchmark not installed")
+    @pytest.mark.skipif(
+        not HAS_PYTEST_BENCHMARK, reason="See #1084 - pytest-benchmark optional dependency"
+    )
     def test_benchmark_organize(
         self,
         benchmark: Any,

diff --git a/tests/integration/test_context_menu_macos.py b/tests/integration/test_context_menu_macos.py
@@ -8,7 +8,7 @@
 import pytest
 
 
-@pytest.mark.skipif(sys.platform != "darwin", reason="macOS-only test")
+@pytest.mark.skipif(sys.platform != "darwin", reason="See #1083 - macOS-only Quick Action feature")
 class TestMacOSQuickAction(unittest.TestCase):
     def setUp(self):
         self.macos_dir = Path("desktop/context-menus/macos")

diff --git a/tests/integration/test_error_propagation.py b/tests/integration/test_error_propagation.py
@@ -27,7 +27,9 @@
 class TestFileReadErrors:
     """File read errors surface in ProcessedFile results, not exceptions."""
 
-    @pytest.mark.skipif(sys.platform == "win32", reason="chmod does not restrict reads on Windows")
+    @pytest.mark.skipif(
+        sys.platform == "win32", reason="See #1078 - chmod does not restrict reads on Windows"
+    )
     def test_unreadable_file_returns_error_in_result(
         self,
         stub_text_model_init: None,
@@ -120,7 +122,9 @@ def test_missing_input_dir_raises_valueerror(
                 output_path=str(tmp_path / "output"),
             )
 
-    @pytest.mark.skipif(sys.platform == "win32", reason="chmod does not restrict reads on Windows")
+    @pytest.mark.skipif(
+        sys.platform == "win32", reason="See #1078 - chmod does not restrict reads on Windows"
+    )
     def test_mixed_good_and_bad_files_in_batch(
         self,
         stub_all_models: None,

diff --git a/tests/integration/test_image_quality_para_suggestion.py b/tests/integration/test_image_quality_para_suggestion.py
@@ -445,23 +445,35 @@ def test_candidate_larger_returns_false(
     _suggestion_engine_available = False
 
 
-@pytest.mark.skipif(not _suggestion_engine_available, reason="SuggestionEngine not importable")
+@pytest.mark.skipif(
+    not _suggestion_engine_available,
+    reason="See #1077 - SuggestionEngine API not yet implemented (tests expect SuggestionEngine, but PARASuggestionEngine exists)",
+)
 class TestSuggestionEngineInit:
     def test_creates(self) -> None:
         se = SuggestionEngine()
         assert se is not None
 
 
-@pytest.mark.skipif(not _suggestion_engine_available, reason="SuggestionEngine not importable")
+@pytest.mark.skipif(
+    not _suggestion_engine_available,
+    reason="See #1077 - SuggestionEngine API not yet implemented (tests expect SuggestionEngine, but PARASuggestionEngine exists)",
+)
 class TestSuggestionEngineAPI:
     @pytest.fixture()
     def engine(self) -> SuggestionEngine:
         return SuggestionEngine()
 
     def test_has_suggest_method(self, engine: SuggestionEngine) -> None:
-        # Verify the engine has suggest-type methods
-        methods = [m for m in dir(engine) if not m.startswith("_") and callable(getattr(engine, m))]
-        assert len(methods) > 0
+        # Verify the engine exposes at least one of the expected suggest API methods
+        expected_methods = {"suggest_category", "suggest"}
+        public_methods = [
+            m for m in dir(engine) if not m.startswith("_") and callable(getattr(engine, m))
+        ]
+        suggest_methods = {m for m in public_methods if "suggest" in m.lower()}
+        assert suggest_methods & expected_methods, (
+            f"SuggestionEngine must have suggest_category or suggest; found public methods: {public_methods}"
+        )
 
     def test_suggest_category_returns_something(
         self, engine: SuggestionEngine, tmp_path: Path
@@ -476,5 +488,8 @@ def test_suggest_category_returns_something(
             result = engine.suggest(f)
             assert result is not None
         else:
-            # No matching method found — skip silently
-            pytest.skip("No suggest method found on SuggestionEngine")
+            # No matching method found — fail so a SuggestionEngine with no suggest API is caught
+            pytest.fail(
+                "SuggestionEngine has neither suggest_category() nor suggest() — "
+                "at least one must exist for this class to be useful"
+            )
diff --git a/tests/integration/test_organize_text_workflow.py b/tests/integration/test_organize_text_workflow.py
@@ -97,7 +97,7 @@ def mock_process_file(file_path: Path) -> ProcessedFile:
         assert (source_dir / "report.txt").exists()
 
     @pytest.mark.skipif(
-        sys.platform == "win32", reason="Hardlinks require admin privileges on Windows"
+        sys.platform == "win32", reason="See #1082 - Hardlinks require admin privileges on Windows"
     )
     @patch("file_organizer.core.organizer.TextProcessor")
     @patch("file_organizer.core.organizer.VisionProcessor")

diff --git a/tests/parallel/test_checkpoint.py b/tests/parallel/test_checkpoint.py
@@ -443,7 +443,9 @@ def tearDown(self) -> None:
 
         shutil.rmtree(self._tmpdir, ignore_errors=True)
 
-    @pytest.mark.skipif(sys.platform == "win32", reason="directory fsync is a no-op on Windows")
+    @pytest.mark.skipif(
+        sys.platform == "win32", reason="See #1081 - directory fsync is a no-op on Windows"
+    )
     def test_save_checkpoint_calls_fsync(self) -> None:
         """Verify os.fsync is called during save_checkpoint (file + directory)."""
         ckpt = Checkpoint(job_id="fsync-test", file_hashes={})

diff --git a/tests/plugins/test_base_coverage.py b/tests/plugins/test_base_coverage.py
@@ -76,7 +76,9 @@ def test_manifest_preserves_existing_optional_fields(self, tmp_path):
         assert result["license"] == "Apache-2.0"
         assert result["homepage"] == "https://example.com"
 
-    @pytest.mark.skipif(sys.platform == "win32", reason="chmod does not restrict reads on Windows")
+    @pytest.mark.skipif(
+        sys.platform == "win32", reason="See #1078 - chmod does not restrict reads on Windows"
+    )
     def test_unreadable_manifest_raises(self, tmp_path):
         plugin_dir = tmp_path / "plugin"
         plugin_dir.mkdir()

diff --git a/tests/plugins/test_sandbox_isolation.py b/tests/plugins/test_sandbox_isolation.py
@@ -14,9 +14,8 @@
 
 executor_interface
     White-box tests for the ``PluginExecutor`` lifecycle and RPC.
-    Marked ``@pytest.mark.skip`` until Stream A delivers the real
-    implementation.  The full assertion bodies are written here so they are
-    ready to un-skip.
+    Skipped via issue #338 until Stream A delivers the real implementation.
+    The full assertion bodies are written here so they are ready to un-skip.
 
 ipc_protocol
     Unit tests for the IPC dataclasses and encoding/decoding helpers in
@@ -267,12 +266,13 @@ def _guarded_open(path: Any, *args: Any, **kwargs: Any) -> Any:
 
 
 @pytest.mark.unit
+@pytest.mark.skip(reason="See #338 - Stream A executor not yet delivered")
 class TestExecutorInterface:
     """Tests for PluginExecutor lifecycle and RPC.
 
-    All tests in this class are skipped until Stream A delivers a working
-    ``PluginExecutor``.  The test bodies are complete — only remove the
-    ``@pytest.mark.skip`` decorator when the executor is ready.
+    All tests in this class are skipped (see #338) until Stream A delivers a working
+    ``PluginExecutor``.  The test bodies are complete — only remove the skip decorator
+    when the executor is ready.
     """
 
     def test_executor_starts_and_stops(self, tmp_path: Path) -> None:

diff --git a/tests/services/test_audio_transcription.py b/tests/services/test_audio_transcription.py
@@ -30,7 +30,7 @@ def test_transcriber_initialization(self):
         except (ImportError, NotImplementedError):
             pytest.skip("AudioTranscriber not yet fully implemented (Phase 3)")
 
-    @pytest.mark.skip(reason="Phase 3 - Audio transcription not yet implemented")
+    @pytest.mark.skip(reason="See #1071 - Phase 3 audio transcription feature not yet implemented")
     def test_transcribe_mp3_file(self, tmp_path):
         """Test transcribing MP3 file."""
         from file_organizer.services.audio.transcriber import AudioTranscriber
@@ -45,7 +45,7 @@ def test_transcribe_mp3_file(self, tmp_path):
         assert result is not None
         assert "text" in result
 
-    @pytest.mark.skip(reason="Phase 3 - Audio transcription not yet implemented")
+    @pytest.mark.skip(reason="See #1071 - Phase 3 audio transcription feature not yet implemented")
     def test_transcribe_wav_file(self, tmp_path):
         """Test transcribing WAV file."""
         from file_organizer.services.audio.transcriber import AudioTranscriber
@@ -58,7 +58,7 @@ def test_transcribe_wav_file(self, tmp_path):
 
         assert result is not None
 
-    @pytest.mark.skip(reason="Phase 3 - Audio transcription not yet implemented")
+    @pytest.mark.skip(reason="See #1071 - Phase 3 audio transcription feature not yet implemented")
     def test_language_detection(self, tmp_path):
         """Test language detection in transcription."""
         from file_organizer.services.audio.transcriber import AudioTranscriber