Dispatcharr/tests/README.md

EPG Program Search API - Test Suite

Comprehensive test suite for the EPG Program Search API endpoint. Tests can be run against any Dispatcharr instance with configurable credentials and server settings.

Features Tested

Text Search Capabilities

• ✅ Simple text search
• ✅ AND operator (premier AND league)
• ✅ OR operator (Newcastle OR Villa)
• ✅ Nested parentheses ((Newcastle OR NEW) AND (Villa OR AST))
• ✅ Whole word matching (prevent "NEW" from matching "News")
• ✅ Regex pattern matching (^Premier for titles starting with "Premier")
• ✅ Case-insensitive searching
• ✅ Description field searching

Time Filtering

• ✅ airing_at - programs airing at specific time
• ✅ start_after / start_before - time range filtering
• ✅ end_after / end_before - end time filtering

Channel & Stream Filtering

• ✅ Channel name filtering
• ✅ Channel ID filtering
• ✅ Stream name filtering
• ✅ Group name filtering (channel or stream groups)

Response Features

• ✅ Field selection (customize response fields)
• ✅ Pagination (page number and page size)
• ✅ Response structure validation
• ✅ Nested channel and stream data

Edge Cases

• ✅ Invalid datetime formats
• ✅ Empty search terms
• ✅ Special characters
• ✅ Maximum page size enforcement
• ✅ Empty result sets

Installation

Install Test Dependencies

cd tests
pip install -r requirements.txt

Or install globally:

pip install pytest requests python-dotenv

Running Tests

Quick Start (Local Development)

Run tests against localhost with default credentials:

cd tests
pytest test_epg_search_api.py -v

Production/Remote Server Testing

Set environment variables for your Dispatcharr instance:

# Configure server
export DISPATCHARR_HOST=192.168.1.180
export DISPATCHARR_PORT=9191
export DISPATCHARR_USERNAME=admin
export DISPATCHARR_PASSWORD=your_password

# Run tests
pytest test_epg_search_api.py -v

Using .env File

Create a .env file in the tests/ directory:

DISPATCHARR_HOST=192.168.1.180
DISPATCHARR_PORT=9191
DISPATCHARR_USERNAME=admin
DISPATCHARR_PASSWORD=your_password
DISPATCHARR_HTTPS=false
TEST_TIMESTAMP=2026-02-14T20:00:00Z

Then run:

pytest test_epg_search_api.py -v

Run Specific Tests

Run a single test:

pytest test_epg_search_api.py::TestEPGSearchAPI::test_text_search_or_operator -v

Run a test class:

pytest test_epg_search_api.py::TestEPGSearchAPI -v

Run tests matching a pattern:

pytest test_epg_search_api.py -k "text_search" -v

Run with Different Verbosity

# Verbose output
pytest test_epg_search_api.py -v

# Very verbose (show all output)
pytest test_epg_search_api.py -vv

# Quiet (minimal output)
pytest test_epg_search_api.py -q

# Show print statements
pytest test_epg_search_api.py -v -s

Generate Test Report

# Generate HTML report
pytest test_epg_search_api.py -v --html=report.html --self-contained-html

# Generate JUnit XML (for CI/CD)
pytest test_epg_search_api.py -v --junitxml=report.xml

Configuration Options

All configuration is via environment variables:

Variable	Description	Default
DISPATCHARR_HOST	Server hostname or IP	localhost
DISPATCHARR_PORT	Server port	9191
DISPATCHARR_USERNAME	API username	admin
DISPATCHARR_PASSWORD	API password	admin
DISPATCHARR_HTTPS	Use HTTPS (true/false)	false
TEST_TIMESTAMP	ISO 8601 timestamp for time-based tests	Current time

Test Results Interpretation

Success Example

tests/test_epg_search_api.py::TestEPGSearchAPI::test_basic_search PASSED
tests/test_epg_search_api.py::TestEPGSearchAPI::test_text_search_and_operator PASSED
tests/test_epg_search_api.py::TestEPGSearchAPI::test_airing_at_filter PASSED
================================ 32 passed in 15.23s =================================

Failure Example

tests/test_epg_search_api.py::TestEPGSearchAPI::test_basic_search FAILED

FAILED test_epg_search_api.py::TestEPGSearchAPI::test_basic_search - AssertionError: ...

Skip Example (when server unavailable)

tests/test_epg_search_api.py::TestEPGSearchAPI SKIPPED (Could not authenticate...)

Continuous Integration

GitHub Actions Example

name: EPG Search API Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      
      - name: Install dependencies
        run: |
          pip install -r tests/requirements.txt
      
      - name: Run tests
        env:
          DISPATCHARR_HOST: ${{ secrets.DISPATCHARR_HOST }}
          DISPATCHARR_PORT: ${{ secrets.DISPATCHARR_PORT }}
          DISPATCHARR_USERNAME: ${{ secrets.DISPATCHARR_USERNAME }}
          DISPATCHARR_PASSWORD: ${{ secrets.DISPATCHARR_PASSWORD }}
        run: |
          pytest tests/test_epg_search_api.py -v --junitxml=report.xml
      
      - name: Publish Test Results
        uses: EnricoMi/publish-unit-test-result-action@v2
        if: always()
        with:
          files: report.xml

Troubleshooting

Authentication Failures

If tests skip with "Could not authenticate":

1. Check credentials:

   curl -X POST "http://localhost:9191/api/accounts/token/" \
     -H "Content-Type: application/json" \
     -d '{"username":"admin","password":"admin"}'
   

2. Verify server is running:

   curl http://localhost:9191/api/swagger/
   

3. Check environment variables:

   env | grep DISPATCHARR
   

Connection Timeouts

If tests timeout:

1. Check network connectivity
2. Verify firewall rules allow connections
3. Increase timeout in DispatcharrAPIClient class (edit test_epg_search_api.py)

Test Data Issues

Some tests verify specific program data exists. If your EPG database is empty or has limited data:

• Tests may skip or have fewer results
• Time-based tests may fail if no programs match the test timestamp
• Solution: Import EPG data before running tests or adjust TEST_TIMESTAMP

HTTPS/SSL Issues

For self-signed certificates:

# Add to DispatcharrAPIClient.__init__()
self.session.verify = False  # Disable SSL verification (not recommended for production)

Or set environment variable:

export PYTHONHTTPSVERIFY=0

Development

Adding New Tests

1. Add test method to TestEPGSearchAPI class:

   def test_my_new_feature(self, api_client):
       """Test description"""
       result = api_client.search_programs({"param": "value"})
       assert "results" in result
   

2. Run your new test:

   pytest test_epg_search_api.py::TestEPGSearchAPI::test_my_new_feature -v
   

Debugging Tests

Enable verbose output and print statements:

pytest test_epg_search_api.py -vv -s --tb=long

Add debug logging in test:

def test_debug_example(self, api_client):
    result = api_client.search_programs({"title": "test"})
    print(f"Result: {result}")  # Will show with -s flag
    assert "results" in result

Test Coverage

Current test coverage includes:

• 32+ test cases covering all major features
• Text search: 8 tests
• Time filtering: 2 tests
• Channel/stream filtering: 2 tests
• Response features: 3 tests
• Edge cases: 5+ tests
• Response validation: 2 tests

Performance Benchmarking

Run with performance timing:

pytest test_epg_search_api.py -v --durations=10

This shows the 10 slowest tests, helping identify performance bottlenecks.

Support

For issues or questions:

• Check the API Documentation
• Review test output with -vv flag for detailed errors
• Check Dispatcharr logs for server-side issues

License

Same as the main Dispatcharr project.