arsvendg/Stirling-PDF
1
0
Fork 0
mirror of https://github.com/arsvendg/Stirling-PDF.git synced 2026-07-16 03:20:46 +02:00
Code Issues Actions 3 Packages Projects Releases 1 Wiki Activity

V2: Convert Tool (#3828)

Browse Source 
🔄 Dynamic Processing Strategies

- Adaptive routing: Same tool uses different backend endpoints based on
file analysis
- Combined vs separate processing: Intelligently chooses between merge
operations and individual file processing
- Cross-format workflows: Enable complex conversions like "mixed files →
PDF" that other tools can't handle

  ⚙️ Format-Specific Intelligence

  Each conversion type gets tailored options:
  - HTML/ZIP → PDF: Zoom controls (0.1-3.0 increments) with live preview
  - Email → PDF: Attachment handling, size limits, recipient control
  - PDF → PDF/A: Digital signature detection with warnings
  - Images → PDF: Smart combining vs individual file options

 File Architecture

  Core Implementation:
  ├── Convert.tsx                     # Main stepped workflow UI
├── ConvertSettings.tsx # Centralized settings with smart detection
├── GroupedFormatDropdown.tsx # Enhanced format selector with grouping
├── useConvertParameters.ts # Smart detection & parameter management
  ├── useConvertOperation.ts         # Multi-strategy processing logic
  └── Settings Components:
      ├── ConvertFromWebSettings.tsx      # HTML zoom controls
      ├── ConvertFromEmailSettings.tsx    # Email attachment options
├── ConvertToPdfaSettings.tsx # PDF/A with signature detection
      ├── ConvertFromImageSettings.tsx    # Image PDF options
      └── ConvertToImageSettings.tsx      # PDF to image options

 Utility Layer

  Utils & Services:
├── convertUtils.ts # Format detection & endpoint routing
  ├── fileResponseUtils.ts          # Generic API response handling
└── setupTests.ts # Enhanced test environment with crypto mocks

  Testing & Quality

  Comprehensive Test Coverage

  Test Suite:
├── useConvertParameters.test.ts # Parameter logic & smart detection
  ├── useConvertParametersAutoDetection.test.ts  # File type analysis
├── ConvertIntegration.test.tsx # End-to-end conversion workflows
  ├── ConvertSmartDetectionIntegration.test.tsx  # Mixed file scenarios
  ├── ConvertE2E.spec.ts                     # Playwright browser tests
├── convertUtils.test.ts # Utility function validation
  └── fileResponseUtils.test.ts              # API response handling

  Advanced Test Features

  - Crypto API mocking: Proper test environment for file hashing
  - File.arrayBuffer() polyfills: Complete browser API simulation
  - Multi-file scenario testing: Complex batch processing validation
- CI/CD integration: Vitest runs in GitHub Actions with proper artifacts

---------

Co-authored-by: Connor Yoh <[email protected]>
Co-authored-by: Anthony Stirling <[email protected]>
This commit is contained in:
ConnorYoh
2025-08-01 16:08:04 +01:00
committed by GitHub
co-authored by Connor Yoh Anthony Stirling
parent 8881f19b03
commit 9c9acbfb5b
68 changed files with 9173 additions and 87 deletions
Download Patch File Download Diff File Expand all files Collapse all files
frontend/src/tests/convert/README.md
+264
View File
@@ -0,0 +1,264 @@
# Convert Tool Test Suite
This directory contains comprehensive tests for the Convert Tool functionality.
## Test Files Overview
### 1. ConvertTool.test.tsx
**Purpose**: Unit/Component testing for the Convert Tool UI components
- Tests dropdown behavior and navigation
- Tests format availability based on endpoint status
- Tests UI state management and form validation
- Mocks backend dependencies for isolated testing
**Key Test Areas**:
- FROM dropdown enables/disables formats based on endpoint availability
- TO dropdown shows correct conversions for selected source format
- Format-specific options appear/disappear correctly
- Parameter validation and state management
### 2. ConvertIntegration.test.ts
**Purpose**: Integration testing for Convert Tool business logic
- Tests parameter validation and conversion matrix logic
- Tests endpoint resolution and availability checking
- Tests file extension detection
- Provides framework for testing actual conversions (requires backend)
**Key Test Areas**:
- Endpoint availability checking matches real backend status
- Conversion parameters are correctly validated
- File extension detection works properly
- Conversion matrix returns correct available formats
### 3. ConvertE2E.spec.ts
**Purpose**: End-to-End testing using Playwright with Dynamic Endpoint Discovery
- **Automatically discovers available conversion endpoints** from the backend
- Tests complete user workflows from file upload to download
- Tests actual file conversions with real backend
- **Skips tests for unavailable endpoints** automatically
- Tests error handling and edge cases
- Tests UI/UX flow and user interactions
**Key Test Areas**:
- **Dynamic endpoint discovery** using `/api/v1/config/endpoints-enabled` API
- Complete conversion workflows for **all available endpoints**
- **Unavailable endpoint testing** - verifies disabled conversions are properly blocked
- File upload, conversion, and download process
- Error handling for corrupted files and network issues
- Performance testing with large files
- UI responsiveness and progress indicators
**Supported Conversions** (tested if available):
- PDF ↔ Images (PNG, JPG, GIF, BMP, TIFF, WebP)
- PDF ↔ Office (DOCX, PPTX)
- PDF ↔ Text (TXT, HTML, XML, CSV, Markdown)
- Office → PDF (DOCX, PPTX, XLSX, etc.)
- Email (EML) → PDF
- HTML → PDF, URL → PDF
- Markdown → PDF
## Running the Tests
**Important**: All commands should be run from the `frontend/` directory:
```bash
cd frontend
```
### Setup (First Time Only)
```bash
# Install dependencies (includes test frameworks)
npm install
# Install Playwright browsers for E2E tests
npx playwright install
```
### Unit Tests (ConvertTool.test.tsx)
```bash
# Run all unit tests
npm test
# Run specific test file
npm test ConvertTool.test.tsx
# Run with coverage
npm run test:coverage
# Run in watch mode (re-runs on file changes)
npm run test:watch
# Run specific test pattern
npm test -- --grep "dropdown"
```
### Integration Tests (ConvertIntegration.test.ts)
```bash
# Run integration tests
npm test ConvertIntegration.test.ts
# Run with verbose output
npm test ConvertIntegration.test.ts -- --reporter=verbose
```
### E2E Tests (ConvertE2E.spec.ts)
```bash
# Prerequisites: Backend must be running on localhost:8080
# Start backend first, then:
# Run all E2E tests (automatically discovers available endpoints)
npm run test:e2e
# Run specific E2E test file
npx playwright test ConvertE2E.spec.ts
# Run with UI mode for debugging
npx playwright test --ui
# Run specific test by endpoint name (dynamic)
npx playwright test -g "pdf-to-img:"
# Run only available conversion tests
npx playwright test -g "Dynamic Conversion Tests"
# Run only unavailable conversion tests
npx playwright test -g "Unavailable Conversions"
# Run in headed mode (see browser)
npx playwright test --headed
# Generate HTML report
npx playwright test ConvertE2E.spec.ts --reporter=html
```
**Test Discovery Process:**
1. Tests automatically query `/api/v1/config/endpoints-enabled` to discover available conversions
2. Tests are generated dynamically for each available endpoint
3. Tests for unavailable endpoints verify they're properly disabled in the UI
4. Console output shows which endpoints were discovered
## Test Requirements
### For Unit Tests
- No special requirements
- All dependencies are mocked
- Can run in any environment
### For Integration Tests
- May require backend API for full functionality
- Uses mock data for endpoint availability
- Tests business logic in isolation
### For E2E Tests
- **Requires running backend server** (localhost:8080)
- **Requires test fixture files** (see ../test-fixtures/README.md)
- Requires frontend dev server (localhost:5173)
- Tests real conversion functionality
## Test Data
The tests use realistic endpoint availability data based on your current server configuration:
**Available Endpoints** (should pass):
- `file-to-pdf`: true (DOCX, XLSX, PPTX → PDF)
- `img-to-pdf`: true (PNG, JPG, etc. → PDF)
- `markdown-to-pdf`: true (MD → PDF)
- `pdf-to-csv`: true (PDF → CSV)
- `pdf-to-img`: true (PDF → PNG, JPG, etc.)
- `pdf-to-text`: true (PDF → TXT)
**Disabled Endpoints** (should be blocked):
- `eml-to-pdf`: false
- `html-to-pdf`: false
- `pdf-to-html`: false
- `pdf-to-markdown`: false
- `pdf-to-pdfa`: false
- `pdf-to-presentation`: false
- `pdf-to-word`: false
- `pdf-to-xml`: false
## Test Scenarios
### Success Scenarios (Available Endpoints)
1. **PDF → Image**: PDF to PNG/JPG with various DPI and color settings
2. **PDF → Data**: PDF to CSV (table extraction), PDF to TXT (text extraction)
3. **Office → PDF**: DOCX/XLSX/PPTX to PDF conversion
4. **Image → PDF**: PNG/JPG to PDF with image options
5. **Markdown → PDF**: MD to PDF with formatting preservation
### Blocked Scenarios (Disabled Endpoints)
1. **EML conversions**: Should be disabled in FROM dropdown
2. **PDF → Office**: PDF to Word/PowerPoint should be disabled
3. **PDF → Web**: PDF to HTML/XML should be disabled
4. **PDF → PDF/A**: Should be disabled
### Error Scenarios
1. **Corrupted files**: Should show helpful error messages
2. **Network failures**: Should handle backend unavailability
3. **Large files**: Should handle memory constraints gracefully
4. **Invalid parameters**: Should validate before submission
## Adding New Tests
When adding new conversion formats:
1. **Update ConvertTool.test.tsx**:
- Add the new format to test data
- Test dropdown behavior for the new format
- Test format-specific options if any
2. **Update ConvertIntegration.test.ts**:
- Add endpoint availability test cases
- Add conversion matrix test cases
- Add parameter validation tests
3. **Update ConvertE2E.spec.ts**:
- Add end-to-end workflow tests
- Add test fixture files
- Test actual conversion functionality
4. **Update test fixtures**:
- Add sample files for the new format
- Update ../test-fixtures/README.md
## Debugging Failed Tests
### Unit Test Failures
- Check mock data matches real endpoint status
- Verify component props and state management
- Check for React hook dependency issues
### Integration Test Failures
- Verify conversion matrix includes new formats
- Check endpoint name mappings
- Ensure parameter validation logic is correct
### E2E Test Failures
- Ensure backend server is running
- Check test fixture files exist and are valid
- Verify element selectors match current UI
- Check for timing issues (increase timeouts if needed)
## Test Maintenance
### Regular Updates Needed
1. **Endpoint Status**: Update mock data when backend endpoints change
2. **UI Selectors**: Update test selectors when UI changes
3. **Test Fixtures**: Replace old test files with new ones periodically
4. **Performance Benchmarks**: Update expected performance metrics
### CI/CD Integration
- Unit tests: Run on every commit
- Integration tests: Run on pull requests
- E2E tests: Run on staging deployment
- Performance tests: Run weekly or on major releases
## Performance Expectations
These tests focus on frontend functionality, not backend performance:
- **File upload/UI**: < 1 second for small test files
- **Dropdown interactions**: < 200ms
- **Form validation**: < 100ms
- **Conversion UI flow**: < 5 seconds for small test files
Tests will fail if UI interactions are slow, indicating frontend performance issues.