Testing Quick Setup

Testing Quick Setup for Contributors

Prerequisites

1. Python 3.12+ installed
2. Docker installed and running
3. Git (you already have this if you cloned the repo)

Initial Setup (One-Time)

# 1. Clone the repository
git clone https://github.com/crocodilestick/Calibre-Web-Automated.git
cd Calibre-Web-Automated

# 2. Create virtual environment
python3 -m venv .venv

# 3. Activate virtual environment
source .venv/bin/activate  # Linux/Mac
# OR
.venv\Scripts\activate  # Windows

# 4. Install dependencies
pip install -r requirements.txt
pip install pytest pytest-timeout pytest-flask pytest-mock faker testcontainers

# 5. You're ready to test!
./run_tests.sh

Custom Port Configuration

By default, tests run on port 8085 to avoid conflicts with production CWA instances (which typically run on port 8083). If you need to use a different port, set the CWA_TEST_PORT environment variable:

# Run tests on port 9000 instead of 8085
export CWA_TEST_PORT=9000
./run_tests.sh

# Or inline
CWA_TEST_PORT=9000 ./run_tests.sh

# To use port 8083 (same as production - will conflict if CWA is running)
CWA_TEST_PORT=8083 ./run_tests.sh

Why 8085? Most users run production CWA on port 8083. Using 8085 for tests allows both to coexist during development without port conflicts.

For CI: The CI environment should set CWA_TEST_PORT=8083 if needed to match the workflow configuration.

Troubleshooting

Docker not running

Error: Docker daemon not running

Solution: Start Docker Desktop or Docker daemon

Port already in use

Error: Port 8083 already allocated

Solution: Use CWA_TEST_PORT to specify a different port (see above)

Missing dependencies

Error: pytest not found

Solution: Make sure venv is activated and dependencies installed:

source .venv/bin/activate
pip install pytest pytest-timeout pytest-flask pytest-mock faker testcontainers

Python version

Error: Python 3.12+ required

Solution: Update Python or use pyenv:

pyenv install 3.12.3
pyenv local 3.12.3

What Gets Tested?

• ✅ Unit Tests - Fast, no Docker needed (~89 tests)
• ✅ Integration Tests - Docker required (20 tests)
• ✅ Smoke Tests - Quick environment checks (10 tests that run, 9 skip without container)
• ✅ Docker Tests - Auto-skip gracefully if no container (5 tests run with container, 4 skip without)

Running Specific Tests

# Just unit tests (fastest)
pytest tests/unit/ -v

# Just integration tests
pytest tests/integration/ -v

# Specific test file
pytest tests/unit/test_helper.py -v

# Single test
pytest tests/unit/test_helper.py::TestGetValidFilename::test_basic_valid_filename -v

VSCode Integration

The .venv will auto-activate in VSCode terminals. Just open a new terminal and start testing!

Next Steps

• See Testing-Running-Tests.md for detailed test execution
• See Testing-Guide-for-Contributors.md for writing tests