@khoaha/spek-cli 1.0.3

package/docs/TESTING.md

@@ -0,0 +1,429 @@
+# Testing Guide
+
+## Prerequisites
+
+1. **Directus Instance:** You need access to a Directus instance with the Vault Export feature
+2. **Access Token:** Generate an access token from your Directus instance
+3. **Test File:** Have a file ID from a Vault Export ready for testing
+
+## Getting Test Data
+
+### From Figma Plugin
+
+1. Open the SpeX Figma plugin
+2. Go to "Vault Export" tab
+3. Configure your Directus connection
+4. Export specs to vault
+5. Copy the file ID from the success dialog
+
+### File ID Format
+
+File IDs are UUIDs, typically in this format:
+```
+abc123-def456-ghi789-jkl012
+```
+
+## Local Testing
+
+### 1. Build the CLI Tool
+
+```bash
+# From monorepo root
+npm run cli:build
+
+# Or from cli-tool directory
+cd cli-tool
+npm run build
+```
+
+### 2. Test Locally (Without Publishing)
+
+```bash
+# From cli-tool directory
+node dist/index.js --help
+node dist/index.js -d <your-file-id>
+```
+
+### 3. Test with npx (Local Link)
+
+```bash
+# From cli-tool directory
+npm link
+
+# Now you can use it globally
+spek-cli -d <your-file-id>
+
+# Unlink when done
+npm unlink -g spek-cli
+```
+
+## Test Scenarios
+
+### Scenario 1: First Run (No Config)
+
+**Expected Behavior:**
+1. CLI prompts for Directus URL
+2. CLI prompts for access token
+3. Config is saved to `~/.spek-cli/config.json`
+4. CLI prompts for file ID (if not provided)
+5. Download and extraction proceeds
+
+**Test Commands:**
+```bash
+# Interactive mode (prompts for everything)
+spek-cli
+
+# Direct mode (prompts for config only)
+spek-cli -d <file-id>
+```
+
+**Validation:**
+- [ ] Config file created at `~/.spek-cli/config.json`
+- [ ] Config contains correct URL and token
+- [ ] Success message displayed
+- [ ] Files extracted to current directory
+
+### Scenario 2: Subsequent Runs (Config Exists)
+
+**Expected Behavior:**
+1. Config loaded from file
+2. No prompts for URL/token
+3. Prompts for file ID if not provided
+4. Download and extraction proceeds
+
+**Test Commands:**
+```bash
+# Interactive mode
+spek-cli
+
+# Direct mode
+spek-cli -d <file-id>
+```
+
+**Validation:**
+- [ ] No config prompts shown
+- [ ] Download proceeds immediately
+- [ ] Files extracted successfully
+
+### Scenario 3: Overwrite Existing Files
+
+**Setup:**
+```bash
+# First download
+spek-cli -d <file-id>
+
+# Second download (same file)
+spek-cli -d <file-id>
+```
+
+**Expected Behavior:**
+1. CLI detects existing files
+2. Prompts: "Files already exist. Overwrite?"
+3. If Yes → Overwrites files
+4. If No → Cancels operation
+
+**Validation:**
+- [ ] Warning message shown
+- [ ] Overwrite prompt appears
+- [ ] Choosing "Yes" overwrites files
+- [ ] Choosing "No" cancels without changes
+
+### Scenario 4: Invalid Authentication
+
+**Setup:**
+```bash
+# Edit config file with invalid token
+# ~/.spek-cli/config.json
+```
+
+**Expected Behavior:**
+1. Download attempt fails
+2. Error message: "Authentication failed. Please check your access token."
+3. Suggests checking config
+
+**Test Commands:**
+```bash
+spek-cli -d <file-id>
+```
+
+**Validation:**
+- [ ] Clear error message
+- [ ] No partial downloads
+- [ ] Temp files cleaned up
+
+### Scenario 5: File Not Found
+
+**Test Commands:**
+```bash
+spek-cli -d invalid-file-id-12345
+```
+
+**Expected Behavior:**
+1. Download attempt fails
+2. Error message: "File not found: invalid-file-id-12345"
+
+**Validation:**
+- [ ] Clear error message
+- [ ] No partial extraction
+- [ ] Temp files cleaned up
+
+### Scenario 6: Network Errors
+
+**Setup:**
+- Disconnect internet or use invalid Directus URL
+
+**Expected Behavior:**
+1. Connection fails
+2. Error message with network details
+
+**Validation:**
+- [ ] Graceful error handling
+- [ ] No hanging processes
+- [ ] Temp files cleaned up
+
+### Scenario 7: Corrupted ZIP File
+
+**Note:** This is difficult to test without modifying the Directus server response.
+
+**Expected Behavior:**
+1. Download completes
+2. ZIP validation fails
+3. Error message: "Invalid or corrupted ZIP file"
+
+**Validation:**
+- [ ] No extraction attempted
+- [ ] Temp files cleaned up
+
+### Scenario 8: User Cancellation
+
+**Test Commands:**
+```bash
+spek-cli
+# Press Ctrl+C during any prompt
+```
+
+**Expected Behavior:**
+1. Graceful exit
+2. No partial operations
+3. No temp files left behind
+
+**Validation:**
+- [ ] Clean exit
+- [ ] No error messages
+- [ ] No temp files
+
+### Scenario 9: Help and Version
+
+**Test Commands:**
+```bash
+spek-cli --help
+spek-cli -h
+spek-cli --version
+spek-cli -v
+```
+
+**Expected Behavior:**
+- Help shows usage, options, examples
+- Version shows current version number
+
+**Validation:**
+- [ ] Help is clear and comprehensive
+- [ ] Version matches package.json
+
+### Scenario 10: Empty Directory vs. Non-Empty
+
+**Test A: Empty Directory**
+```bash
+mkdir test-empty
+cd test-empty
+spek-cli -d <file-id>
+```
+
+**Expected:** Direct extraction, no overwrite prompt
+
+**Test B: Non-Empty Directory**
+```bash
+mkdir test-non-empty
+cd test-non-empty
+echo "test" > README.md
+spek-cli -d <file-id>
+```
+
+**Expected:** Overwrite prompt only if ZIP contains README.md
+
+**Validation:**
+- [ ] Empty dir: No prompt
+- [ ] Non-empty dir with conflicts: Prompt shown
+- [ ] Non-empty dir without conflicts: No prompt
+
+## Manual Testing Checklist
+
+### Setup Phase
+- [ ] Build succeeds without errors
+- [ ] TypeScript compilation clean
+- [ ] All dependencies installed
+
+### Configuration
+- [ ] First run prompts for config
+- [ ] Config saved correctly
+- [ ] Config loaded on subsequent runs
+- [ ] Invalid URL rejected during setup
+- [ ] Empty token rejected during setup
+
+### Download
+- [ ] Valid file ID downloads successfully
+- [ ] Invalid file ID shows error
+- [ ] Network errors handled gracefully
+- [ ] Authentication errors clear
+
+### Extraction
+- [ ] Files extracted to CWD
+- [ ] Directory structure preserved
+- [ ] Overwrite prompt works
+- [ ] Cancellation works
+- [ ] Temp files cleaned up
+
+### User Experience
+- [ ] Help message clear
+- [ ] Version displayed correctly
+- [ ] Error messages helpful
+- [ ] Success messages clear
+- [ ] Colors enhance readability
+
+### Edge Cases
+- [ ] Very large files (>100MB)
+- [ ] Files with special characters
+- [ ] Deeply nested directory structures
+- [ ] Empty ZIP files
+- [ ] ZIP with single file
+- [ ] ZIP with many files (>1000)
+
+## Automated Testing (Future)
+
+### Unit Tests
+
+```typescript
+// Example test structure
+describe('Config Manager', () => {
+  it('should create config directory if not exists', () => {});
+  it('should save config with timestamp', () => {});
+  it('should load existing config', () => {});
+});
+
+describe('Download Handler', () => {
+  it('should detect existing files', () => {});
+  it('should validate ZIP files', () => {});
+  it('should cleanup temp files on error', () => {});
+});
+```
+
+### Integration Tests
+
+```typescript
+describe('Full Download Flow', () => {
+  it('should download and extract valid file', async () => {});
+  it('should handle authentication errors', async () => {});
+  it('should handle file not found', async () => {});
+});
+```
+
+## Performance Testing
+
+### Metrics to Track
+
+1. **Startup Time:** Time from command to first prompt
+2. **Download Speed:** MB/s for various file sizes
+3. **Extraction Time:** Time to extract various ZIP sizes
+4. **Memory Usage:** Peak memory during download/extraction
+
+### Test Files
+
+- Small: <1MB
+- Medium: 1-10MB
+- Large: 10-100MB
+- Very Large: >100MB
+
+## Troubleshooting
+
+### Build Fails
+
+```bash
+# Clean and rebuild
+rm -rf dist node_modules
+npm install
+npm run build
+```
+
+### Config Issues
+
+```bash
+# View config
+cat ~/.spek-cli/config.json
+
+# Delete config (forces re-setup)
+rm ~/.spek-cli/config.json
+```
+
+### Temp Files Not Cleaned
+
+```bash
+# Check temp directory
+ls /tmp/spek-cli-*
+
+# Manual cleanup
+rm /tmp/spek-cli-*
+```
+
+### Permission Errors
+
+```bash
+# Check config directory permissions
+ls -la ~/.spek-cli
+
+# Fix permissions
+chmod 700 ~/.spek-cli
+chmod 600 ~/.spek-cli/config.json
+```
+
+## Reporting Issues
+
+When reporting issues, include:
+
+1. **Command used:** Full command with arguments
+2. **Error message:** Complete error output
+3. **Environment:**
+   - OS and version
+   - Node.js version
+   - npm version
+4. **Config:** Directus URL (redact token)
+5. **File ID:** If applicable (redact if sensitive)
+6. **Steps to reproduce:** Detailed steps
+
+## Test Results Template
+
+```markdown
+## Test Results - [Date]
+
+**Environment:**
+- OS: Windows 10 / macOS 14 / Ubuntu 22.04
+- Node.js: v20.11.0
+- npm: v10.2.4
+
+**Test Scenarios:**
+- [ ] First run setup
+- [ ] Subsequent runs
+- [ ] Overwrite prompt
+- [ ] Invalid auth
+- [ ] File not found
+- [ ] Network errors
+- [ ] User cancellation
+- [ ] Help/Version
+- [ ] Empty directory
+- [ ] Non-empty directory
+
+**Issues Found:**
+1. [Issue description]
+2. [Issue description]
+
+**Overall Status:** ✅ Pass / ❌ Fail
+```