algoryn/dots-ocr-idcard

1# Dots.OCR API Testing2 3This directory contains comprehensive testing scripts for the Dots.OCR API endpoint.4 5## Test Scripts6 7### 1. `test_api_endpoint.py` - Comprehensive API Testing8 9The main testing script that provides full API validation capabilities.10 11**Features:**12- Health check validation13- Single and multiple image testing14- ROI (Region of Interest) testing15- Field extraction validation16- Response structure validation17- Performance metrics18- Detailed error reporting19 20**Usage:**21```bash22# Basic test with default settings23python test_api_endpoint.py24 25# Test with custom API URL26python test_api_endpoint.py --url https://your-api.example.com27 28# Test with ROI29python test_api_endpoint.py --roi '{"x1": 0.1, "y1": 0.1, "x2": 0.9, "y2": 0.9}'30 31# Test with specific expected fields32python test_api_endpoint.py --expected-fields document_number surname given_names33 34# Verbose output35python test_api_endpoint.py --verbose36 37# Custom timeout38python test_api_endpoint.py --timeout 6039```40 41**Options:**42- `--url`: API base URL (default: http://localhost:7860)43- `--timeout`: Request timeout in seconds (default: 30)44- `--roi`: ROI coordinates as JSON string45- `--expected-fields`: List of expected field names to validate46- `--verbose`: Enable verbose logging47 48### 2. `quick_test.py` - Quick Validation49 50A simple script for quick API validation after deployment.51 52**Usage:**53```bash54# Test local API55python quick_test.py56 57# Test remote API58python quick_test.py https://your-api.example.com59```60 61## Test Configuration62 63### `test_config.json`64 65Configuration file for test parameters and thresholds.66 67**Configuration sections:**68- `api_endpoints`: Different API URLs for various environments69- `test_images`: List of test image files70- `expected_fields`: Fields that should be extracted71- `roi_test_cases`: Different ROI configurations to test72- `performance_thresholds`: Performance validation criteria73- `test_timeout`: Default timeout for requests74 75## Test Images76 77The following test images are used for validation:78 79- `tom_id_card_front.jpg` - Front of Dutch ID card80- `tom_id_card_back.jpg` - Back of Dutch ID card81 82## Testing Scenarios83 84### 1. Basic Functionality Test85```bash86python test_api_endpoint.py87```88Tests basic API functionality with default settings.89 90### 2. ROI Testing91```bash92python test_api_endpoint.py --roi '{"x1": 0.25, "y1": 0.25, "x2": 0.75, "y2": 0.75}'93```94Tests Region of Interest cropping functionality.95 96### 3. Field Validation Test97```bash98python test_api_endpoint.py --expected-fields document_number surname given_names nationality99```100Tests that specific fields are extracted correctly.101 102### 4. Performance Test103```bash104python test_api_endpoint.py --timeout 60 --verbose105```106Tests API performance with extended timeout and detailed logging.107 108## Expected Results109 110### Successful Test Output111```112🔍 Checking API health...113✅ API is healthy: {'status': 'healthy', 'version': '1.0.0', 'model_loaded': True}114🚀 Starting API tests with 2 images...115✅ tom_id_card_front.jpg: 2.45s116✅ tom_id_card_back.jpg: 1.23s117📊 Test Results:118   Total images: 2119   Successful: 2120   Failed: 0121   Success rate: 100.0%122   Average processing time: 1.84s123🎉 All tests completed successfully!124```125 126### Field Extraction Example127```128Page 1: 11 fields extracted129  document_number: NLD123456789 (confidence: 0.90)130  surname: MULDER (confidence: 0.90)131  given_names: THOMAS JAN (confidence: 0.90)132  nationality: NLD (confidence: 0.95)133  date_of_birth: 15-03-1990 (confidence: 0.90)134  gender: M (confidence: 0.95)135```136 137## Troubleshooting138 139### Common Issues140 1411. **Connection Refused**142   - Check if the API is running143   - Verify the correct URL and port144   - Check firewall settings145 1462. **Timeout Errors**147   - Increase timeout with `--timeout` parameter148   - Check API performance and resource usage149 1503. **Missing Fields**151   - Verify test images contain the expected text152   - Check field extraction patterns in the code153   - Review API logs for processing errors154 1554. **Validation Errors**156   - Check API response format157   - Verify model is loaded correctly158   - Review error logs for details159 160### Debug Mode161 162Enable verbose logging for detailed debugging:163```bash164python test_api_endpoint.py --verbose165```166 167## Integration with CI/CD168 169The test scripts can be integrated into CI/CD pipelines:170 171```yaml172# Example GitHub Actions step173- name: Test API Endpoint174  run: |175    python scripts/test_api_endpoint.py --url ${{ env.API_URL }} --timeout 60176```177 178## Performance Monitoring179 180The scripts provide performance metrics that can be used for monitoring:181 182- Processing time per image183- Success rate184- Field extraction accuracy185- Response validation results186 187These metrics can be integrated with monitoring systems like Prometheus or DataDog.188 189## 🚀 Production API Testing190 191### Current Production Endpoint192- **URL**: https://algoryn-dots-ocr-idcard.hf.space193- **Health Check**: https://algoryn-dots-ocr-idcard.hf.space/health194- **API Docs**: https://algoryn-dots-ocr-idcard.hf.space/docs195 196### Quick Production Test197```bash198# Test production API199./run_tests.sh -e production200 201# Quick test with curl (no Python dependencies)202./test_production_curl.sh203```204 205### Staging Environment206- **Staging URL**: https://algoryn-dots-ocr-idcard-staging.hf.space (to be created)207- **Purpose**: Safe testing before production deployment208 209### Environment-Specific Testing210```bash211# Test different environments212./run_tests.sh -e local      # Local development213./run_tests.sh -e staging    # Staging environment214./run_tests.sh -e production # Production environment215```216 217---218 219### 5. `test_debug_ocr.sh` - Per-request debug logging via curl220 221Use this for quick, dependency-light testing of the server-side debug mode that prints OCR snippets, extracted fields, and MRZ details to logs.222 223**Usage:**224```bash225# Local server (per-request debug on)226./test_debug_ocr.sh -u http://localhost:7860 -f tom_id_card_front.jpg -d227 228# Hugging Face Space (replace with your Space URL)229./test_debug_ocr.sh -u https://<your-space>.hf.space -f tom_id_card_front.jpg -d \230  -r '{"x1":0,"y1":0,"x2":1,"y2":0.5}'231```232 233You can also enable debug globally on the server with `DOTS_OCR_DEBUG=1`. The script only toggles the request-level flag via `-d`.234