paulg/FCI_WaterMaker_API
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
FCI_WaterMaker_API/DTS_API_TEST_README.md

7.7 KiB
Raw Permalink Blame History

DTS API Test Suite

A comprehensive test script for monitoring DTS (Desalination Treatment System) mode progression through the Watermaker PLC API. This tool starts DTS mode, monitors all screen transitions, tracks timer progress, and provides detailed debugging information.

Features

  • ✅ Complete DTS Flow Monitoring: Tracks all 5 DTS screens (Requested → Priming → Init → Production → Fresh Water Flush)
  • ⏱️ Timer Progress Tracking: Monitors countdown timers and calculates progress percentages
  • 🔄 Transition Detection: Detects and logs when the controller advances between screens
  • 📊 Detailed Logging: Structured logging with timestamps and comprehensive context
  • 📈 Performance Analysis: Tracks API response times and system performance
  • 🚨 Error Detection: Identifies stuck timers, timeouts, and API communication issues
  • 📄 Multiple Report Formats: JSON logs, CSV data export, and console summaries

DTS Flow Overview

The test monitors the complete DTS process through these screens:

  1. DTS Requested (Mode 34) - Initial request state
  2. Priming (Mode 5) - Timer R128 (180 seconds) - Flush with shore pressure
  3. Init (Mode 6) - Timer R129 (60 seconds) - High pressure pump initialization
  4. Production (Mode 7) - No timer - Water flowing to tank
  5. Fresh Water Flush (Mode 8) - Timer R133 (60 seconds) - Process ending
  6. Complete (Mode 2) - Return to standby

Installation

Prerequisites

# Install required Python packages
pip install requests

Setup

  1. Ensure the Watermaker PLC API server is running:

    python run_server.py

  2. Make the test scripts executable (already done):

    chmod +x dts_api_test_suite.py run_dts_test.py

Usage

Quick Start

Basic Test

python run_dts_test.py basic

Verbose Test with CSV Export

python run_dts_test.py verbose

Custom API Endpoint

python run_dts_test.py custom http://192.168.1.100:5000/api

Advanced Usage

Full Command Line Options

python dts_api_test_suite.py --help

Custom Configuration

python dts_api_test_suite.py --config config/test_config.json --verbose

Different Polling Intervals

# Fast polling (0.5 seconds)
python dts_api_test_suite.py --polling-interval 0.5 --verbose

# Slow polling (2 seconds) 
python dts_api_test_suite.py --polling-interval 2.0

Export Data

python dts_api_test_suite.py --export-csv --verbose

Configuration

Configuration File

Edit config/test_config.json to customize test behavior:

{
  "API_BASE_URL": "http://localhost:5000/api",
  "REQUEST_TIMEOUT": 10,
  "RETRY_ATTEMPTS": 3,
  "POLLING_INTERVAL": 1.0,
  "TRANSITION_TIMEOUT": 300,
  "CONSOLE_VERBOSITY": "INFO",
  "LOG_FILE_ENABLED": true,
  "CSV_EXPORT_ENABLED": true,
  "EXPECTED_SCREEN_DURATIONS": {
    "5": 180,
    "6": 60,
    "8": 60
  }
}

Key Configuration Options

  • API_BASE_URL: Base URL for the API (default: http://localhost:5000/api)
  • POLLING_INTERVAL: How often to check status in seconds (default: 1.0)
  • TRANSITION_TIMEOUT: Maximum time to wait for complete process (default: 300s)
  • CONSOLE_VERBOSITY: Log level - DEBUG, INFO, WARNING, ERROR
  • EXPECTED_SCREEN_DURATIONS: Expected duration for each timed screen
  • STUCK_TIMER_THRESHOLD: Seconds without timer change to consider "stuck" (default: 30)

Output Examples

Console Output

🚀 DTS API Test Suite v1.0
📡 API Endpoint: http://localhost:5000/api
⏰ Started: 2025-01-11 18:12:00

✅ System Status: Connected
🔄 Starting DTS sequence...
📋 DTS sequence started - Task ID: abc12345

📺 Screen Transition Detected:
   DTS Requested → Priming (Mode 34 → 5)
   ⏱️  Timer R128: 1800 (0% progress)

⏳ Current: Priming (Mode 5)
📊 Progress: ████████░░░░░░░░░░░░ 40%
⏱️  Timer R128: 1080

📺 Screen Transition Detected:
   Priming → Init (Mode 5 → 6)
   ⏱️  Timer R129: 600 (0% progress)
   ⏳ Duration: 3m 0s

✅ DTS process completed successfully!

📊 DTS API Test Summary
============================================================
Status: ✅ SUCCESS
Total Duration: 9m 5s
Screens Completed: 4
Transitions Detected: 4
API Errors: 0
Timer Issues: 0
============================================================

Generated Files

The test creates several output files:

logs/
├── dts_test_20250111_181200.log     # Detailed log file

reports/  
├── dts_test_report_20250111_181200.json  # Complete test results

data/
├── dts_timer_data_20250111_181200.csv    # Timer progress data

API Endpoints Used

The test interacts with these API endpoints:

  • GET /api/system/status - Check system health
  • POST /api/dts/start - Start DTS sequence
  • GET /api/dts/status/{task_id} - Monitor task progress
  • GET /api/dts/current-step-progress - Get real-time timer info
  • POST /api/dts/stop - Emergency stop (if needed)

Troubleshooting

Common Issues

API Connection Failed

❌ System status: Failed to connect

Solution: Ensure the API server is running on the correct port:

python run_server.py

DTS Sequence Won't Start

❌ Failed to start DTS sequence

Possible causes:

  • Another DTS operation is already running
  • PLC is not in a valid starting mode
  • PLC connection issues

Check current status:

curl http://localhost:5000/api/dts/status

Stuck Timer Detected

⚠️  Timer R128 appears stuck at 1500

Solution: This indicates a potential PLC communication issue or the timer isn't counting down as expected. Check PLC connection and system logs.

Slow Transitions

⚠️  Slow transition: 4m 30s (expected ~3m 0s)

Solution: This is informational - the system is working but slower than expected. May indicate system load or PLC performance issues.

Debug Mode

For detailed debugging, run with verbose output:

python dts_api_test_suite.py --verbose

This will show:

  • All API requests and responses
  • Detailed timer value changes
  • Internal state transitions
  • Performance metrics

Log Analysis

Check the generated log files in the logs/ directory for detailed information:

# View latest log
ls -la logs/
tail -f logs/dts_test_*.log

Integration with CI/CD

The test script returns appropriate exit codes:

  • 0 - Test passed successfully
  • 1 - Test failed

Example integration:

#!/bin/bash
# Run DTS API test
python dts_api_test_suite.py --config config/ci_test_config.json

if [ $? -eq 0 ]; then
    echo "✅ DTS API tests passed"
else
    echo "❌ DTS API tests failed"
    exit 1
fi

Development

Adding New Features

The test suite is designed to be extensible:

  1. Custom Analyzers: Add new analysis functions in the DTSAPITester class
  2. Additional Reports: Extend the generate_reports() method
  3. New Configurations: Add options to the TestConfig class
  4. Custom Endpoints: Add new API endpoint methods

Testing the Test Suite

To test the test suite itself without running a full DTS cycle:

# Test API connectivity only
python -c "
from dts_api_test_suite import DTSAPITester
tester = DTSAPITester()
print('✅ Connected' if tester.check_system_status() else '❌ Failed')
"

Support

For issues or questions:

  1. Check the generated log files for detailed error information
  2. Verify API server is running and accessible
  3. Ensure PLC connection is stable
  4. Review configuration settings

The test suite provides comprehensive logging and error reporting to help diagnose any issues with the DTS API or PLC communication.

Reference in New Issue View Git Blame Copy Permalink