mirror of
https://github.com/samsonjs/Peekaboo.git
synced 2026-04-01 10:35:47 +00:00
271814cc90
✅ **Merge Conflicts Resolved** - Merged latest changes from main branch - Resolved conflicts in docs/spec.md by keeping comprehensive specification - Added PEEKABOO_CLI_TIMEOUT environment variable documentation 🧪 **Test Suite Updates for Linux Compatibility** - Added platform-specific test skipping for Swift-dependent tests - Created tests/setup.ts for global test configuration - Updated vitest.config.ts with platform detection - Modified integration tests to skip on non-macOS platforms: - tests/integration/peekaboo-cli-integration.test.ts - tests/integration/image-tool.test.ts - tests/integration/analyze-tool.test.ts 📦 **New Test Scripts** - `npm run test:unit` - Run only unit tests (any platform) - `npm run test:typescript` - Run TypeScript tests, skip Swift (Linux-friendly) - `npm run test:typescript:watch` - Watch mode for TypeScript-only tests 🌍 **Platform Support** - **macOS**: All tests run (unit + integration + Swift) - **Linux/CI**: Only TypeScript tests run (Swift tests auto-skipped) - **Environment Variables**: - `SKIP_SWIFT_TESTS=true` - Force skip Swift tests - `CI=true` - Auto-skip Swift tests in CI 📚 **Documentation Updates** - Added comprehensive testing section to README.md - Documented platform-specific test behavior - Added environment variable documentation for test control This allows the TypeScript parts of Peekaboo to be tested on Linux while maintaining full test coverage on macOS. |
||
|---|---|---|
| .. | ||
| integration | ||
| mocks | ||
| unit | ||
| README.md | ||
| setup.ts | ||
Peekaboo Test Suite
Overview
The Peekaboo test suite is designed to be fully portable and runnable on any operating system without requiring:
- macOS
- Screen recording permissions
- The Swift CLI binary
- Any specific system configuration
Test Structure
tests/
├── unit/ # Unit tests for individual components
│ ├── tools/ # Tests for each tool (image, list, analyze)
│ └── utils/ # Tests for utility functions
├── integration/ # Integration tests for tool interactions
└── mocks/ # Mock implementations
Key Design Decisions
All Tests Use Mocks
Every test in this suite uses mocked implementations of the Swift CLI. This means:
- Cross-platform compatibility - Tests run on Linux, Windows, and macOS
- No permissions required - No screen recording or system permissions needed
- Fast execution - No actual screen captures or file I/O
- Deterministic results - Tests always produce the same output
- CI/CD friendly - Can run in any continuous integration environment
What We Test
- Business Logic - Tool parameter validation, response formatting
- Error Handling - All error scenarios including permissions, timeouts, invalid inputs
- Integration - How tools work together and with the MCP protocol
- Type Safety - TypeScript types and Zod schema validation
- Edge Cases - Long file paths, special characters, concurrent execution
What We Don't Test
- Actual Swift CLI binary execution
- Real screen capture functionality
- macOS-specific permissions
- Binary file permissions/existence
Running Tests
# Run all tests
npm test
# Run with coverage
npm run test:coverage
# Run in watch mode
npm run test:watch
# Run specific test file
npm test -- tests/unit/tools/image.test.ts
Coverage Goals
We aim for high test coverage while acknowledging that some code paths (actual Swift CLI execution) cannot be tested in this portable test suite:
- Overall coverage target: >85%
- Critical business logic: >95%
- Error handling paths: 100%
Future Considerations
For true end-to-end testing that exercises the real Swift CLI, consider creating a separate e2e test suite that:
- Only runs on macOS with proper permissions
- Is excluded from regular CI runs
- Tests actual screen capture functionality
- Validates Swift CLI binary behavior
Example structure:
tests/
├── e2e/ # End-to-end tests (macOS only)
│ ├── real-capture.test.ts
│ └── permissions.test.ts
These tests would be run manually or in specialized macOS CI environments.