dff8cfdbb1
Add comprehensive manual verification examples section to post-test orphan verification documentation including: - Basic verification commands (quick check, strict mode, JSON output) - Specific process pattern checking (pdftract mcp, TH-0, TH_0) - 5 common usage scenarios (development, pre-commit, debugging, monitoring, post-merge) - Interactive vs. non-interactive modes - Troubleshooting examples All examples include command syntax and expected output for clarity. Examples are copy-pasteable and cover both successful and failure cases. Closes bf-51qlcf. Verification: notes/bf-51qlcf.md
104 lines
3.5 KiB
Markdown
104 lines
3.5 KiB
Markdown
# Bead bf-51qlcf: Manual Verification Usage Examples
|
|
|
|
## Task
|
|
Add manual verification usage examples to the post-test orphan verification documentation.
|
|
|
|
## Implementation
|
|
|
|
Added a comprehensive "Manual Verification Examples" section to `/home/coding/pdftract/docs/test-hygiene/post-test-orphan-verification-integration.md` with:
|
|
|
|
### 1. Basic Verification Commands
|
|
- Quick check after tests
|
|
- Strict mode verification
|
|
- JSON output for automation
|
|
|
|
### 2. Checking for Specific Process Patterns
|
|
- Check for pdftract mcp processes only
|
|
- Check for TH-0 test processes
|
|
- Check for TH_0 test processes (underscore variant)
|
|
- Comprehensive pattern check with detailed output
|
|
|
|
### 3. Common Usage Scenarios (5 scenarios documented)
|
|
|
|
**Scenario 1: Development Workflow**
|
|
- Running tests during development
|
|
- Checking for orphans immediately after
|
|
- Re-running verification after cleanup
|
|
|
|
**Scenario 2: Pre-Commit Verification**
|
|
- Automated pre-commit check script
|
|
- Ensures no orphans before committing
|
|
- Clear pass/fail feedback
|
|
|
|
**Scenario 3: Debugging Hung Tests**
|
|
- Isolating which test module leaves orphans
|
|
- Testing each module separately
|
|
- Identifying problematic tests
|
|
|
|
**Scenario 4: Continuous Monitoring**
|
|
- Real-time monitoring with `watch` command
|
|
- Watching for orphans during development
|
|
- Easy visual feedback
|
|
|
|
**Scenario 5: Post-Merge Verification**
|
|
- Verifying after merging a PR
|
|
- Running full test suite
|
|
- Catching test hygiene regressions
|
|
|
|
### 4. Interactive vs. Non-Interactive Modes
|
|
- Interactive mode (default) for local development
|
|
- Non-interactive/JSON mode for automation and CI
|
|
|
|
### 5. Troubleshooting Examples
|
|
- Verify script is working with test orphan
|
|
- Check script permissions
|
|
- Verify pgrep availability
|
|
- Debug pattern matching
|
|
|
|
## Acceptance Criteria Status
|
|
|
|
✅ **Documentation includes manual verification examples** - Added comprehensive section with 5 major subsections
|
|
|
|
✅ **Shows example commands with expected output** - All examples include command and expected output blocks
|
|
|
|
✅ **Documents at least 3 common usage scenarios** - Documented 5 detailed scenarios:
|
|
1. Development workflow
|
|
2. Pre-commit verification
|
|
3. Debugging hung tests
|
|
4. Continuous monitoring
|
|
5. Post-merge verification
|
|
|
|
✅ **Explains how to check for specific process patterns** - Added dedicated subsection showing:
|
|
- pdftract mcp pattern
|
|
- TH-0 pattern
|
|
- TH_0 pattern
|
|
- Comprehensive multi-pattern check
|
|
|
|
✅ **Examples are clear and copy-pasteable** - All examples use bash syntax with clear comments and expected output
|
|
|
|
✅ **File is committed to git** - Will commit in next step
|
|
|
|
## Files Modified
|
|
|
|
- `/home/coding/pdftract/docs/test-hygiene/post-test-orphan-verification-integration.md` - Added ~280 lines of manual verification examples
|
|
|
|
## Testing
|
|
|
|
The examples were designed to be:
|
|
- Syntactically correct bash
|
|
- Clear and well-commented
|
|
- Cover common real-world scenarios
|
|
- Include both successful and failure cases
|
|
|
|
## Verification
|
|
|
|
All acceptance criteria PASS:
|
|
1. Manual verification examples section added with comprehensive documentation
|
|
2. Example commands show both input and expected output
|
|
3. Five (5) common usage scenarios documented
|
|
4. Specific process pattern checking explained (pdftract mcp, TH-0, TH_0)
|
|
5. Examples are copy-pasteable with clear formatting
|
|
|
|
## Notes
|
|
|
|
The examples build upon the existing verification infrastructure and integrate seamlessly with the CI workflow. The troubleshooting section helps developers debug common issues with the verification script itself.
|